{"openapi":"3.1.0","info":{"title":"MaYi's MaaS API","version":"0.1.0-current","description":"Current public production integration API for MaYi's MaaS."},"servers":[{"description":"Production","url":"https://maas.flyingant.win"}],"tags":[{"name":"Health"},{"name":"Auth"},{"name":"Files"},{"name":"Slack"},{"name":"Finance"},{"name":"Text"},{"name":"Images"},{"name":"Async"}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"MaaS API key","description":"Use a maas_test_ or maas_live_ API key provisioned by a MaaS admin. Send it as Authorization: Bearer <api-key>.","scheme":"bearer","type":"http"}},"schemas":{"ErrorResponse":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"traceId":{"type":"string"}},"required":["error","traceId"],"type":"object"},"AsyncJob":{"additionalProperties":true,"properties":{"capabilityKey":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"finishedAt":{"format":"date-time","type":"string"},"jobId":{"type":"string"},"lastPolledAt":{"format":"date-time","type":"string"},"pollCount":{"type":"number"},"result":{"type":"object"},"status":{"enum":["queued","submitted","processing","succeeded","failed","cancelled","submit_unknown","result_persist_failed"],"type":"string"},"usage":{"type":"object"}},"required":["jobId","status","capabilityKey"],"type":"object"},"AsyncJobResponse":{"additionalProperties":false,"properties":{"job":{"$ref":"#/components/schemas/AsyncJob"},"success":{"const":true}},"required":["success","job"],"type":"object"}}},"paths":{"/api/health":{"get":{"operationId":"getHealth","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"ok":{"const":true}},"required":["ok"],"type":"object"}}},"description":"Deployment is reachable."}},"summary":"Basic deployment health check","tags":["Health"]}},"/api/health/db":{"get":{"operationId":"getDatabaseHealth","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"database":{"const":"ready"},"ok":{"const":true}},"required":["database","ok"],"type":"object"}}},"description":"Payload database is ready."},"503":{"content":{"application/json":{"schema":{"properties":{"database":{"const":"unavailable"},"error":{"type":"string"},"ok":{"const":false}},"required":["database","error","ok"],"type":"object"}}},"description":"Payload database is unavailable."}},"summary":"Payload/database readiness check","tags":["Health"]}},"/api/v1/health/auth-check":{"get":{"operationId":"getAuthCheck","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"capabilityKey":{"const":"health.auth-check"},"consumerId":{"oneOf":[{"type":"number"},{"type":"string"},{"type":"null"}]},"ok":{"const":true},"traceId":{"type":"string"}},"required":["capabilityKey","consumerId","ok","traceId"],"type":"object"}}},"description":"API key and permission are valid."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Auth or permission failure."}},"security":[{"bearerAuth":[]}],"summary":"Verify protected API auth wiring","tags":["Auth"]}},"/api/v1/files/upload":{"post":{"operationId":"uploadFile","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"format":"binary","type":"string"},"prefix":{"type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"success":{"const":true},"url":{"format":"uri","type":"string"}},"required":["success","url"],"type":"object"}}},"description":"File uploaded to R2."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Upload, auth, or storage error."}},"security":[{"bearerAuth":[]}],"summary":"Upload a file","tags":["Files"]}},"/api/v1/slack/notify":{"post":{"operationId":"postSlackNotify","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"channel":{"type":"string"},"text":{"type":"string"}},"required":["channel","text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"channel":{"type":"string"},"messageTs":{"type":"string"},"success":{"const":true}},"required":["success","channel","messageTs"],"type":"object"}}},"description":"Message posted to Slack."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, auth, configuration, or Slack API error."}},"security":[{"bearerAuth":[]}],"summary":"Post a Slack notification","tags":["Slack"]}},"/api/v1/chat":{"post":{"operationId":"createChat","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"maxTokens":{"description":"Optional integer from 1 to 1000000. When omitted, MaaS uses the provider-managed limit.","maximum":1000000,"minimum":1,"type":"integer"},"messages":{"items":{"additionalProperties":false,"properties":{"content":{"type":"string"},"role":{"enum":["system","user"],"type":"string"}},"required":["role","content"],"type":"object"},"maxItems":2,"minItems":1,"type":"array"},"provider":{"enum":["doubao","openai","xai"],"type":"string"},"reasoningEffort":{"description":"Optional provider-specific effort. OpenAI accepts none, low, medium, high, xhigh, and max and defaults to medium. xAI accepts low, medium, and high and MaaS defaults xAI requests to low. Doubao rejects this field.","enum":["none","low","medium","high","xhigh","max"],"type":"string"},"temperature":{"maximum":2,"minimum":0,"type":"number"}},"required":["messages"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"result":{"properties":{"model":{"type":"string"},"provider":{"enum":["doubao","openai","xai"],"type":"string"},"text":{"type":"string"}},"required":["model","provider","text"],"type":"object"},"success":{"const":true},"usage":{"type":"object"}},"required":["success","result","usage"],"type":"object"}}},"description":"Controlled single-turn chat response."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, auth, quota, spend, or provider error."}},"security":[{"bearerAuth":[]}],"summary":"Run controlled chat","tags":["Text"]}},"/api/v1/responses":{"post":{"operationId":"createResponses","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"includeSources":{"type":"boolean"},"input":{"maxLength":48000,"type":"string"},"inputFiles":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"fileId":{"maxLength":256,"minLength":1,"type":"string"}},"required":["fileId"],"type":"object"},{"additionalProperties":false,"properties":{"fileUrl":{"format":"uri","maxLength":2048,"minLength":1,"type":"string"}},"required":["fileUrl"],"type":"object"}]},"maxItems":5,"type":"array"},"instructions":{"maxLength":48000,"type":"string"},"maxOutputTokens":{"maximum":1000000,"minimum":1,"type":"number"},"provider":{"enum":["doubao","openai"],"type":"string"},"reasoningEffort":{"enum":["none","low","medium","high","xhigh","max"],"type":"string"},"thinkingType":{"enum":["auto","disabled","enabled"],"type":"string"},"toolChoice":{"enum":["auto","required"],"type":"string"},"tools":{"items":{"enum":["web_search"],"type":"string"},"type":"array"}},"required":["input"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"result":{"properties":{"id":{"type":"string"},"model":{"type":"string"},"provider":{"enum":["doubao","openai"],"type":"string"},"sources":{"items":{"properties":{"endIndex":{"type":"number"},"startIndex":{"type":"number"},"title":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["url"],"type":"object"},"type":"array"},"text":{"type":"string"}},"required":["model","provider","text","sources"],"type":"object"},"success":{"const":true},"usage":{"type":"object"}},"required":["success","result","usage"],"type":"object"}}},"description":"Controlled Responses output."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, auth, quota, spend, or provider error."}},"security":[{"bearerAuth":[]}],"summary":"Run Responses","tags":["Text"]}},"/api/v1/text/polish":{"post":{"operationId":"createTextPolish","requestBody":{"content":{"application/json":{"schema":{"properties":{"provider":{"enum":["doubao","openai","xai"],"type":"string"},"text":{"maxLength":48000,"type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"result":{"properties":{"model":{"type":"string"},"provider":{"enum":["doubao","openai","xai"],"type":"string"},"text":{"type":"string"}},"required":["model","provider","text"],"type":"object"},"success":{"const":true},"usage":{"type":"object"}},"required":["success","result","usage"],"type":"object"}}},"description":"Polished text."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, auth, quota, spend, or provider error."}},"security":[{"bearerAuth":[]}],"summary":"Polish text","tags":["Text"]}},"/api/v1/information/extract":{"post":{"operationId":"createInformationExtraction","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"required":["text"]},{"required":["imageUrls"]}],"properties":{"context":{"maxLength":8000,"type":"string"},"imageUrls":{"items":{"format":"uri","type":"string"},"maxItems":10,"type":"array"},"instructions":{"maxLength":8000,"type":"string"},"provider":{"enum":["doubao","openai"],"type":"string"},"text":{"maxLength":48000,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"result":{"properties":{"markdown":{"type":"string"},"model":{"type":"string"},"provider":{"enum":["doubao","openai"],"type":"string"}},"required":["markdown","model","provider"],"type":"object"},"success":{"const":true},"usage":{"type":"object"}},"required":["success","result","usage"],"type":"object"}}},"description":"Information extracted as Markdown."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, auth, quota, spend, or provider error."}},"security":[{"bearerAuth":[]}],"summary":"Extract information","tags":["Text"]}},"/api/v1/images/generate":{"post":{"operationId":"createImageGeneration","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":8,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"background":{"enum":["opaque","auto"],"type":"string"},"count":{"maximum":15,"minimum":1,"type":"number"},"image":{"oneOf":[{"type":"string"},{"items":{"type":"string"},"maxItems":14,"type":"array"}]},"maskImageUrl":{"type":"string"},"model":{"type":"string"},"moderation":{"enum":["low","auto"],"type":"string"},"optimizePromptOptions":{"additionalProperties":false,"properties":{"mode":{"enum":["standard"],"type":"string"}},"required":["mode"],"type":"object"},"outputCompression":{"maximum":100,"minimum":0,"type":"number"},"outputFormat":{"enum":["png","jpeg","webp"],"type":"string"},"prompt":{"maxLength":32000,"type":"string"},"provider":{"enum":["doubao","openai"],"type":"string"},"quality":{"enum":["low","medium","high","auto"],"type":"string"},"referenceImageUrls":{"items":{"type":"string"},"maxItems":16,"type":"array"},"responseFormat":{"enum":["url","b64_json"],"type":"string"},"sequentialImageGeneration":{"enum":["auto","disabled"],"type":"string"},"sequentialImageGenerationOptions":{"additionalProperties":false,"properties":{"maxImages":{"maximum":15,"minimum":1,"type":"number"}},"type":"object"},"size":{"type":"string"},"tools":{"items":{"additionalProperties":false,"properties":{"type":{"enum":["web_search"],"type":"string"}},"required":["type"],"type":"object"},"type":"array"},"watermark":{"type":"boolean"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}},"description":"Async image job created or recovered."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, auth, quota, spend, or provider error."}},"security":[{"bearerAuth":[]}],"summary":"Generate images","tags":["Images"]}},"/api/v1/videos/generate":{"post":{"operationId":"createVideoGenerationJob","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":8,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"audioItems":{"items":{"type":"object"},"maxItems":3,"type":"array"},"audioUrl":{"format":"uri","type":"string"},"audioUrls":{"items":{"format":"uri","type":"string"},"maxItems":3,"type":"array"},"callbackUrl":{"format":"uri","type":"string"},"duration":{"type":"number"},"generateAudio":{"type":"boolean"},"imageBeforeText":{"type":"boolean"},"imageItems":{"items":{"type":"object"},"maxItems":9,"type":"array"},"imageUrl":{"format":"uri","type":"string"},"imageUrls":{"items":{"format":"uri","type":"string"},"maxItems":9,"type":"array"},"model":{"enum":["doubao-seedance-2-0-260128","doubao-seedance-2-0-fast-260128"],"type":"string"},"prompt":{"maxLength":8000,"type":"string"},"provider":{"enum":["doubao"],"type":"string"},"ratio":{"type":"string"},"resolution":{"enum":["480p","720p"],"type":"string"},"returnLastFrame":{"type":"boolean"},"seed":{"maximum":4294967295,"minimum":-1,"type":"number"},"text":{"maxLength":8000,"type":"string"},"videoItems":{"items":{"type":"object"},"maxItems":3,"type":"array"},"videoUrl":{"format":"uri","type":"string"},"videoUrls":{"items":{"format":"uri","type":"string"},"maxItems":3,"type":"array"},"watermark":{"type":"boolean"}},"required":["duration"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}},"description":"Async job created or recovered."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, idempotency, auth, or provider submit error."}},"security":[{"bearerAuth":[]}],"summary":"Create async video generation job","tags":["Async"]}},"/api/v1/audio/transcriptions":{"post":{"operationId":"createAudioTranscriptionJob","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":8,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"audioUrl":{"format":"uri","type":"string"},"codec":{"type":"string"},"duration":{"exclusiveMinimum":0,"type":"number"},"format":{"type":"string"},"language":{"type":"string"},"provider":{"enum":["doubao"],"type":"string"}},"required":["audioUrl","format","duration"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}},"description":"Async transcription job created or recovered."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Validation, idempotency, auth, or provider submit error."}},"security":[{"bearerAuth":[]}],"summary":"Create async audio transcription job","tags":["Async"]}},"/api/v1/jobs/{jobId}":{"get":{"operationId":"getAsyncJob","parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}},"description":"Current async job state."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Auth, ownership, permission, or provider poll error."}},"security":[{"bearerAuth":[]}],"summary":"Poll an async job","tags":["Async"]}}}}