{"openapi":"3.1.0","info":{"title":"MaYi's MaaS API","version":"0.1.0-current","description":"Current public integration API for MaYi's MaaS. Generated from the checked-in route handlers and platform helpers."},"servers":[{"description":"Production","url":"https://maas.flyingant.win"},{"description":"Local development","url":"http://localhost:3000"}],"tags":[{"name":"Health"},{"name":"Auth"},{"name":"Files"},{"name":"Text"},{"name":"Images"},{"name":"Async"}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"MaaS 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/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/images/generate":{"post":{"operationId":"createImageGeneration","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"count":{"maximum":10,"minimum":1,"type":"number"},"guidanceScale":{"type":"number"},"image":{"oneOf":[{"format":"uri","type":"string"},{"items":{"format":"uri","type":"string"},"type":"array"}]},"model":{"type":"string"},"prompt":{"maxLength":8000,"type":"string"},"provider":{"enum":["doubao","openai"],"type":"string"},"quality":{"enum":["low","medium","high"],"type":"string"},"referenceImageUrls":{"items":{"format":"uri","type":"string"},"maxItems":4,"type":"array"},"responseFormat":{"enum":["url","b64_json"],"type":"string"},"seed":{"type":"number"},"size":{"type":"string"},"watermark":{"type":"boolean"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"result":{"properties":{"images":{"items":{"properties":{"b64_json":{"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"},"type":"array"},"model":{"type":"string"},"provider":{"enum":["doubao","openai"],"type":"string"}},"required":["images","model","provider"],"type":"object"},"success":{"const":true},"usage":{"type":"object"}},"required":["success","result","usage"],"type":"object"}}},"description":"Generated image outputs."},"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"]}}}}