Requests and responses

Use these conventions across the REST API. The endpoint reference describes each operation's exact fields and exceptions.

Base URLs

Reference paths already include /v1. Combine them with the production origin https://api.masko.ai, without adding /v1 twice. Local keys and resources belong to your local environment.

Send Authorization: Bearer $MASKO_API_KEY on protected requests and Content-Type: application/json for JSON bodies. Multipart uploads use their documented content type. See API keys and workspaces.

Response envelopes

Successful JSON responses put the result in data:

{
  "data": {
    "id": "RESOURCE_ID",
    "name": "My mascot"
  }
}

Errors contain error.code, error.message, and optional error.details. Check the HTTP status before reading data; see errors and recovery.

A 204 response has no body. The public /v1/openapi.json endpoint returns the specification directly, and /v1/docs returns documentation text.

Pagination

Most list endpoints accept limit and offset; the common defaults are 50 and 0, with a maximum limit of 100. Check the operation for its limits. Continue while meta.pagination.has_more is true, increasing the offset by the returned limit.

{
  "data": [],
  "meta": {
    "pagination": {
      "total": 0,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  }
}

Generation receipts

Individual generation requests normally return 202 Accepted with a job receipt:

{
  "data": {
    "job_id": "JOB_ID",
    "poll_url": "/v1/jobs/JOB_ID"
  }
}

Save the receipt before waiting. Poll GET /v1/jobs/JOB_ID until completed or failed, or register a webhook. A returned file URL may be allocated before the file is ready.

Some polling URLs use the app-relative /api/v1 prefix. For the public API, construct https://api.masko.ai/v1/jobs/JOB_ID from the saved ID, as shown in the quickstart.

Long polling with ?wait=true&timeout=120 waits up to 120 seconds. Reaching that timeout returns the current job state; it does not cancel generation. Continue polling if work is still pending or processing. Derived formats can finish after the parent job: check the required assets before playback. See jobs and polling.

Batch responses contain multiple jobs. Hosted character orchestration returns a run_id and run polling URLs instead of a single generation job. Follow that operation's receipt; see hosted characters and runs.

Costs and retries

Choose animation_model explicitly for new animation integrations. Standard and Premium have different costs and duration limits; omitting the field retains legacy behavior. See credits and costs.

A client timeout does not cancel an accepted generation. Check the saved job or run before resubmitting a paid write. Only use idempotency keys where the operation documents support; the general collection /generate endpoint does not promise idempotent replay.