Current API Specs

Success Response

{
  "ok": true
}

Notes

• Use this for deployment liveness only. It does not verify Payload or database connectivity.

Success Response

{
  "database": "ready",
  "ok": true
}

Relevant Error Codes

Notes

• This route loads Payload and runs a minimal admin-users query.
• A failed database check returns status 503 with ok: false.

Required Headers

Authorization: Bearer <maas_test_or_live_key>

Success Response

{
  "capabilityKey": "health.auth-check",
  "consumerId": 12,
  "ok": true,
  "traceId": "9f4d8f4c-7f57-4f4e-a684-7a99a8b4f2a0"
}

Relevant Error Codes

Notes

• Use this as the first integration smoke test after creating a consumer, credential, capability, and permission grant.
• The response includes the resolved consumer id and trace id for support.

Required Headers

Authorization: Bearer <maas_test_or_live_key>

Request Fields

Request Example

curl -i https://maas.flyingant.win/api/v1/files/upload \
  -H "Authorization: Bearer <api-key>" \
  -F "file=@./sample.pdf;type=application/pdf" \
  -F "prefix=documents/contracts"

Success Response

{
  "success": true,
  "url": "https://cdn.example.test/maas/documents/contracts/2026-05-20T10-00-00-000Z-a1b2c3d4e5f6.pdf"
}

Relevant Error Codes

Notes

• The file part is required and must use one of the supported content types.
• Maximum upload size is 4,194,304 bytes.
• prefix is optional. It is normalized under the maas/ root, so reports/raw becomes maas/reports/raw.
• Successful uploads return a public R2 URL. File bytes are not stored in Payload.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json

Request Fields

Request Example

{
  "channel": "C0123456789",
  "text": "Deployment finished successfully."
}

Success Response

{
  "success": true,
  "channel": "C0123456789",
  "messageTs": "1779456000.000100"
}

Relevant Error Codes

Notes

• The endpoint posts through the configured Slack bot token.
• The channel field should be a Slack channel id, such as C0123456789.
• Successful calls record invocation metadata with the channel id and Slack message timestamp, not the message text.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json

Request Fields

Request Example

{
  "messages": [
    {
      "role": "system",
      "content": "Answer in concise Chinese."
    },
    {
      "role": "user",
      "content": "Explain MaaS usage accounting."
    }
  ],
  "provider": "openai",
  "temperature": 0.7,
  "reasoningEffort": "high"
}

Success Response

{
  "success": true,
  "result": {
    "model": "gpt-5.6-sol",
    "provider": "openai",
    "text": "MaaS usage accounting works by..."
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 80,
    "totalTokens": 203
  }
}

Relevant Error Codes

Notes

• messages must contain exactly one user message and at most one system message.
• Caller system instructions are scoped below the MaaS platform policy.
• provider is optional. When omitted, the server uses the code default openai provider.
• OpenAI accepts reasoningEffort values none, low, medium, high, xhigh, and max; when omitted, OpenAI defaults to medium.
• xAI accepts reasoningEffort values low, medium, and high; when omitted, MaaS defaults xAI requests to low.
• Doubao rejects requests that include reasoningEffort.
• Callers cannot submit assistant history, arbitrary model ids, base URLs, credentials, tool calls, or raw provider payload fields.
• Successful calls record invocation and usage-ledger rows. Validation and provider failures are not billable usage rows.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json

Request Fields

Request Example

{
  "input": "Find today's market-moving China tech news and cite sources.",
  "inputFiles": [
    {
      "fileUrl": "https://files.example.com/brief.pdf"
    }
  ],
  "instructions": "Use concise Slack-friendly bullets.",
  "tools": [
    "web_search"
  ],
  "toolChoice": "auto",
  "includeSources": true,
  "maxOutputTokens": 2000,
  "provider": "doubao"
}

Success Response

{
  "success": true,
  "result": {
    "id": "resp_123",
    "model": "gpt-5.6-sol",
    "provider": "openai",
    "text": "Market-moving China tech news...",
    "sources": [
      {
        "title": "Example News",
        "url": "https://example.com/news"
      }
    ]
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 80,
    "totalTokens": 203
  }
}

Relevant Error Codes

Notes

• This endpoint uses the provider Responses API, not Chat Completions. Supported providers are openai and doubao.
• tools is a MaaS allowlist of string tool names. Currently only web_search is accepted.
• inputFiles accepts MaaS-normalized provider file IDs or HTTPS file URLs. Raw provider file fields and base64 file data are rejected.
• The endpoint does not accept raw provider tool definitions, provider payload passthrough, model ids, base URLs, or credentials.
• MaaS sets store=false on provider requests and does not store input text, model output text, raw provider payloads, or raw provider responses in durable invocation metadata.
• includeSources defaults to true when web_search is enabled. MaaS sends OpenAI source include parameters only to OpenAI, and normalizes URL citations/search sources returned by the selected provider.
• reasoningEffort is optional and OpenAI-only. thinkingType is optional and Doubao-only. When omitted, MaaS leaves reasoning behavior to the selected provider.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json

Request Fields

Request Example

{
  "text": "please make this email better",
  "provider": "xai"
}

Success Response

{
  "success": true,
  "result": {
    "model": "grok-4.5",
    "provider": "xai",
    "text": "Please improve this email."
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 80,
    "totalTokens": 203
  }
}

Relevant Error Codes

Notes

• text is trimmed before processing and must be at most 48,000 characters.
• provider is optional. When omitted, the server uses the code default xai provider.
• Callers cannot submit arbitrary model ids, base URLs, credentials, or system prompts.
• Successful calls record invocation and usage-ledger rows. Validation and provider failures are not billable usage rows.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json

Request Fields

Request Example

{
  "text": "Invoice #A-100 total $42",
  "imageUrls": [
    "https://cdn.example.test/invoice-page-1.png"
  ],
  "instructions": "Extract key invoice fields as a Markdown table.",
  "context": "The image is the authoritative source.",
  "provider": "openai"
}

Success Response

{
  "success": true,
  "result": {
    "model": "gpt-5.6-sol",
    "provider": "openai",
    "markdown": "## Summary\n\n...\n\n## Extracted Information\n\n..."
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 80,
    "totalTokens": 203
  }
}

Relevant Error Codes

Notes

• At least one of text or imageUrls is required. Text and image URLs can be used together.
• imageUrls must contain HTTPS URLs and accepts at most 10 URLs.
• instructions can shape the Markdown output but cannot override platform accuracy rules.
• provider is optional. When omitted, the server uses the code default openai provider.
• Durable records do not store source text, image URLs, instructions, context, Markdown output, or raw provider payloads.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json
Idempotency-Key: <8-128 printable characters>

Request Fields

Request Example

{
  "prompt": "a clean studio photo of a desk lamp",
  "provider": "openai",
  "size": "1536x864",
  "count": 1,
  "quality": "auto",
  "background": "auto"
}

Success Response

{
  "success": true,
  "job": {
    "jobId": "job_image123",
    "capabilityKey": "image.generate",
    "status": "queued"
  }
}

Relevant Error Codes

Notes

• This is an async create route. It returns HTTP 202; poll the returned jobId with GET /api/v1/jobs/{jobId}.
• Reusing the same Idempotency-Key with the same normalized request returns the existing job. Reusing it with a different request returns IDEMPOTENCY_CONFLICT.
• prompt is trimmed. OpenAI allows up to 32,000 characters; Doubao keeps the MaaS safety cap of 8,000 characters.
• provider is optional. When omitted, the server uses the code default openai provider. Accepted values are doubao and openai.
• model is optional but must match the configured model for the resolved provider.
• Omitted provider requests infer the provider from Doubao-only or OpenAI-only fields; otherwise they use the OpenAI default path.
• Doubao accepts responseFormat, image, watermark, outputFormat, sequentialImageGeneration, sequentialImageGenerationOptions, optimizePromptOptions, and tools. The configured Seedream 5.0 Lite model rejects seed, guidanceScale, and fast prompt optimization.
• OpenAI accepts quality, referenceImageUrls, background, moderation, outputFormat, outputCompression, and maskImageUrl. gpt-image-2 rejects transparent backgrounds and inputFidelity.
• Provider image output is copied to Cloudflare R2 by a no-retry Workflow step. Polling reads saved job state and never calls the image provider.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json
Idempotency-Key: <8-128 printable characters>

Request Fields

Request Example

{
  "prompt": "A clean product video of a matte black desk lamp rotating on a white table.",
  "model": "doubao-seedance-2-0-fast-260128",
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "seed": -1,
  "watermark": false,
  "generateAudio": true,
  "imageUrls": [
    "https://cdn.example.test/lamp.png"
  ],
  "imageRole": "first_frame",
  "primaryImageDetail": "high",
  "returnLastFrame": true
}

Success Response

{
  "success": true,
  "job": {
    "capabilityKey": "video.generate",
    "createdAt": "2026-05-20T10:00:00.000Z",
    "jobId": "job_video123",
    "status": "submitted"
  }
}

Relevant Error Codes

Notes

• This is an async create route. Poll the returned jobId with GET /api/v1/jobs/{jobId}.
• Reusing the same Idempotency-Key with the same normalized request returns the existing job. Reusing it with a different request returns IDEMPOTENCY_CONFLICT.
• duration must be -1 or an integer from 4 to 15 seconds.
• Only Seedance 2.0 and Seedance 2.0 Fast are supported. draft and draftTaskId are intentionally rejected.
• Reference audio requires at least one reference image or reference video.

Required Headers

Authorization: Bearer <maas_test_or_live_key>
Content-Type: application/json
Idempotency-Key: <8-128 printable characters>

Request Fields

Request Example

{
  "audioUrl": "https://cdn.example.test/audio/meeting.m4a",
  "format": "m4a",
  "codec": "aac",
  "duration": 31.4,
  "language": "zh-CN"
}

Success Response

{
  "success": true,
  "job": {
    "capabilityKey": "audio.transcribe",
    "createdAt": "2026-05-20T10:00:00.000Z",
    "jobId": "job_audio123",
    "status": "submitted"
  }
}

Relevant Error Codes

Notes

• This is an async create route. Poll the returned jobId with GET /api/v1/jobs/{jobId}.
• audioUrl must be HTTPS.
• duration is required in seconds and is rounded to at least one second for request metadata and fallback usage.
• DOUBAO_ASR_API_KEY is preferred. If unset, the server falls back to DOUBAO_API_KEY.

Required Headers

Authorization: Bearer <maas_test_or_live_key>

Request Fields

Success Response

{
  "success": true,
  "job": {
    "capabilityKey": "video.generate",
    "finishedAt": "2026-05-20T10:02:00.000Z",
    "jobId": "job_video123",
    "result": {
      "providerVideoUrl": "https://provider.example.test/video.mp4",
      "videoKey": "maas/video-results/job_video123.mp4",
      "videoUrl": "https://cdn.example.test/maas/video-results/job_video123.mp4"
    },
    "status": "succeeded",
    "usage": {
      "quantity": 42,
      "source": "provider",
      "unit": "provider_unit"
    }
  }
}

Relevant Error Codes

Notes

• Unknown jobs and jobs owned by another consumer both return JOB_NOT_FOUND.
• The route checks the saved job capability key, so image, video, and audio jobs still require their respective capability permission.
• Image Workflow jobs always return saved database state. Non-terminal video and audio jobs refresh provider state.
• Successful image and video jobs expose R2 references. Successful audio jobs return transcript text from the provider snapshot.
• Usage is recorded once when a job reaches succeeded.