Current API Specs

Success Response

{
  "ok": true
}

Implementation Sources

Notes

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

Success Response

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

Relevant Error Codes

Implementation Sources

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

Implementation Sources

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 http://localhost:3000/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

Implementation Sources

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

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

Success Response

{
  "success": true,
  "result": {
    "model": "doubao-seed-2-0-lite-260428",
    "provider": "doubao",
    "text": "Please improve this email."
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 80,
    "totalTokens": 203
  }
}

Relevant Error Codes

Implementation Sources

Notes

• text is trimmed before processing and must be at most 48,000 characters.
• provider is optional. When omitted, the server uses TEXT_POLISH_PROVIDER or defaults to doubao.
• 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

{
  "prompt": "a clean studio photo of a desk lamp",
  "provider": "doubao",
  "size": "2048x2048",
  "count": 1,
  "responseFormat": "url"
}

Success Response

{
  "success": true,
  "result": {
    "images": [
      {
        "url": "https://provider.example.test/image.png"
      }
    ],
    "model": "doubao-seedream-4-5-251128",
    "provider": "doubao"
  },
  "usage": {
    "quantity": 1,
    "source": "generated_image_count",
    "unit": "image"
  }
}

Relevant Error Codes

Implementation Sources

Notes

• prompt is trimmed and must be at most 8,000 characters.
• provider is optional. Accepted values are doubao and openai.
• model is optional but must match the configured model for the resolved provider.
• Doubao accepts responseFormat, image, watermark, seed, and guidanceScale. OpenAI accepts quality and referenceImageUrls.
• Generated image URLs or base64 values are returned to the caller but are not persisted to Payload or copied to R2 by this route.

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

Implementation Sources

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

Implementation Sources

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

Implementation Sources

Notes

• Unknown jobs and jobs owned by another consumer both return JOB_NOT_FOUND.
• The route checks the saved job capability key, so a video job still requires video.generate permission and an audio job still requires audio.transcribe permission.
• Terminal jobs are returned from the database without provider polling. Non-terminal jobs refresh provider state.
• Successful video jobs are copied from the provider URL to R2 before returning succeeded. Successful audio jobs return transcript text from the provider snapshot.
• Usage is recorded once when a job reaches succeeded.