{"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"},"details":{"$ref":"#/components/schemas/ProviderErrorDetails"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"traceId":{"type":"string"}},"required":["error","traceId"],"type":"object"},"ProviderErrorDetails":{"additionalProperties":false,"description":"Optional sanitized diagnostics on authorized Chat/Responses provider errors. All fields are optional. Strings are bounded and redacted; raw bodies, credentials, input echoes, and stacks are not returned. MaaS does not persist these details. Upstream status is distinct from the MaaS HTTP response status.","properties":{"message":{"description":"Known local cause or diagnostic extraction limitation.","type":"string"},"model":{"description":"Attempted provider model when known.","type":"string"},"providerCode":{"type":"string"},"providerMessage":{"type":"string"},"providerParam":{"type":"string"},"providerType":{"type":"string"},"requestId":{"description":"Upstream request ID, not the MaaS trace ID.","type":"string"},"stage":{"enum":["configuration","request","response","output"],"type":"string"},"timeoutMs":{"minimum":0,"type":"number"},"upstreamStatus":{"maximum":599,"minimum":100,"type":"integer"}},"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":["deepseek","doubao","openai","xai"],"type":"string"},"model":{"description":"Optional model name for the selected provider; omission uses its code-owned default. Trimmed before validation; no internal whitespace or control characters. Does not infer a provider or change endpoints or credentials. Model and option support is checked by the provider.","minLength":1,"pattern":"^\\s*[^\\s\\u0000-\\u001f\\u007f]{1,256}\\s*$","type":"string"},"reasoningEffort":{"description":"Optional provider-specific effort. The configured OpenAI default model accepts none, low, medium, high, xhigh, and max and defaults to medium. Other models may have different defaults or narrower option support. xAI accepts low, medium, and high and MaaS defaults xAI requests to low. Doubao and DeepSeek reject this field.","enum":["none","low","medium","high","xhigh","max"],"type":"string"},"temperature":{"description":"Optional number from 0 to 2. OpenAI GPT-5 models use the provider-managed temperature; other models default to 0.7, subject to provider support.","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":["deepseek","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"},"inputImages":{"items":{"additionalProperties":false,"properties":{"detail":{"enum":["auto","low","high"],"type":"string"},"imageUrl":{"format":"uri","maxLength":2048,"minLength":1,"type":"string"}},"required":["imageUrl"],"type":"object"},"maxItems":10,"type":"array"},"instructions":{"maxLength":48000,"type":"string"},"maxOutputTokens":{"maximum":1000000,"minimum":1,"type":"number"},"model":{"description":"Optional model name for the selected provider; omission uses its code-owned default. Trimmed before validation; no internal whitespace or control characters. Does not infer a provider or change endpoints or credentials. Model, tool, and media support is checked by the provider.","minLength":1,"pattern":"^\\s*[^\\s\\u0000-\\u001f\\u007f]{1,256}\\s*$","type":"string"},"provider":{"enum":["deepseek","doubao","openai","xai"],"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":["deepseek","doubao","openai","xai"],"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":10,"minimum":1,"type":"number"},"image":{"oneOf":[{"type":"string"},{"items":{"type":"string"},"maxItems":10,"type":"array"}]},"maskImageUrl":{"type":"string"},"model":{"type":"string"},"moderation":{"enum":["low","auto"],"type":"string"},"optimizePromptOptions":{"additionalProperties":false,"properties":{"mode":{"enum":["standard","fast"],"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"},"size":{"type":"string"},"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-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"]}}}}