> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Render Video (from Character and/or Motion)
> Create a render directly, or finalize one prepared with Prepare Render.
The request body carries one of two shapes, selected by `Content-Type`.
`multipart/form-data` creates a render directly from character and motion inputs, each supplied as an uploaded file, a URL, or the ID of a saved asset. This form answers `200` and ignores `Idempotency-Key`.
`application/json` creates a render from a draft prepared by [Prepare Render](/v1/api-reference/renders/prepare). This form answers `202`, **requires** `Idempotency-Key`, and is idempotent within the authenticated project or OAuth principal: reusing the same key with the same normalized input returns the original render, while reusing it with different input returns `IDEMPOTENCY_KEY_REUSED`.
**Pricing** (1 credit = $0.01): **$0.01 per character in the render, per second\*\* of the finished video. Only one character is supported per render today, so this is **$0.01/second** in practice — a 10-second render costs **$0.10 (10 credits)**. There is no per-render minimum charge; the amount reserved when the render starts is an estimate based on the requested inputs and is finalized against the actual completed duration once the render finishes. See [Pricing and retention](/v1/pricing#video-remix).
## Request parameters — `multipart/form-data`
| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `character_id` | string | One character source | — | ID of a `ready` Character owned by the caller, normally beginning with `char_`. Use instead of uploading or linking a new image. |
| `image` | file | One character source | — | Character source image uploaded directly. Use exactly one character source among `image`, `image_url`, and `character_id`. |
| `image_url` | string | One character source | — | Publicly reachable URL of a character image that the service can fetch. Use instead of `image` or `character_id`. |
| `ref_url` | string | One character source | — | Backward-compatible alias for `image_url`. Do not combine character URL aliases. |
| `ref_image_url` | string | One character source | — | Backward-compatible alias for `image_url`. Do not combine character URL aliases. |
| `motion_id` | string | One motion source | — | ID of a `ready` Motion owned by the caller, normally beginning with `mot_`. Use instead of uploading or linking a new driving video. |
| `motion_video` | file | One motion source | — | Driving video uploaded directly. Use exactly one motion source among `motion_video`, `motion_video_url`, and `motion_id`. |
| `motion_video_url` | string | One motion source | — | Publicly reachable URL of a driving video that the service can fetch. Use instead of `motion_video` or `motion_id`. |
| `video_url` | string | One motion source | — | Backward-compatible alias for `motion_video_url`. Do not combine motion URL aliases. |
| `driving_video_url` | string | One motion source | — | Backward-compatible alias for `motion_video_url`. Do not combine motion URL aliases. |
| `scene_id` | string | One motion source | — | Backward-compatible alias for `motion_id`. Do not send both IDs. |
| `background_mode` | string | No | `original` | Background treatment: `original` preserves or reconstructs the source background, `solid` uses `bg_color`, `transparent` requests alpha output, and `inpaint` is accepted as an alias of `original`. |
| `bg_color` | string | With `solid` | — | Solid background colour as `"R,G,B"`, for example `"0,177,64"`. Valid only with `background_mode=solid`. |
| `background_url` | string | No | — | Optional custom background image URL forwarded to the render pipeline. Normally omitted unless the selected pipeline mode supports it. |
| `model` | string | No | Service default | Render model: `V3`, `v3`, `V3_Preview`, `V4`, `v4`, `V4_Preview`, or `V4_BaseSG`. The service otherwise infers it from saved assets or uses its configured default. |
| `mode` | string | No | Inferred | Advanced pipeline mode: `full_pipeline`, `preprocessed`, `character_only`, or `scene_preprocess`. Omit to infer it from the supplied source types. |
| `character_mapping` | JSON string | No | — | Advanced mapping from motion segment IDs to Character IDs. In multipart requests, encode the JSON object as a string. |
If neither the character group nor the motion group is supplied at all, the server substitutes its own preconfigured default `character_id`/`motion_id` and renders that instead of rejecting the request. Supplying either group *partially* — for example a character source with no motion source — is still an error. `bg_color` is only valid with `background_mode=solid`.
The default `character_id`/`motion_id` are configured per project/environment, not fixed across all of Viggle — two API keys can send an all-empty request and get different results. Don't rely on this fallback for anything beyond a quick smoke test; always supply an explicit character and motion source in production traffic.
## Request parameters — `application/json` (draft-based)
| Header | Required | Description |
| - | :-: | - |
| `Idempotency-Key` | Yes | Caller-generated stable key of 1–255 characters. Reusing it with the same normalized draft returns the original Render; reusing it with different input returns `IDEMPOTENCY_KEY_REUSED`. |
| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `draft_id` | string | Yes | Opaque draft ID returned by [Prepare Render](/v1/api-reference/renders/prepare). Pass it unchanged after completing every required direct upload; a draft can be consumed only once. |
| `upload_completions` | array | With uploads | One entry for every upload plan returned by Prepare Render. Required when the draft's `state` was `awaiting_uploads`; omit or send an empty array when no upload was required. |
| `upload_completions[].upload_handle` | string | Yes per entry | Opaque handle from the matching upload plan. It identifies which character or motion upload was completed. |
| `upload_completions[].etag` | string | No | Optional ETag returned by the object-store `PUT` response. Preserve surrounding quotes when the storage service includes them. |
## Response parameters
`multipart/form-data` returns `200 OK`; the `application/json` draft form returns `202 Accepted`. Both return a Render object, though the `200` response from a direct multipart request only carries information in `id`, `status`, `progress`, and `created_at`.
| Field | Type | Always present | Description |
| - | - | :-: | - |
| `id` | string | Yes | Public Render ID beginning with `render_`. |
| `status` | string | Yes | `queued`, `processing`, `ready`, `failed`, or `cancelled`. |
| `stage` | string or null | Yes | Coarse progress hint when available. `analyzing`/`rendering`/`finishing` come from the multipart pipeline; other values come from the draft-based pipeline. |
| `progress` | integer or null | Yes | Progress from 0 to 100 when available. |
| `video_url` | string or null | Yes | Finished video URL when ready. |
| `alpha_url` | string or null | Yes | Alpha video URL for transparent output, when available. |
| `created_at` / `completed_at` | string or null | Yes | ISO 8601 timestamps. |
| `error` | object or null | Yes | Failure details when the Render fails. |
| `links` | object | No | `{self, events, download}` — absent on renders served by the legacy migration proxy. |
```json theme={null}
{"id":"render_789ghi","status":"queued","stage":null,"progress":0,"video_url":null,"alpha_url":null,"created_at":"2026-07-21T10:00:00+00:00","completed_at":null,"error":null,"links":{"self":"/v1/renders/render_789ghi","events":"/v1/renders/render_789ghi/events","download":"/v1/renders/render_789ghi/download"}}
```
`links.self` mirrors the retired `GET /v1/renders/{render_id}` and no longer resolves — poll [Get Video](/v1/api-reference/videos/get) with the same `id` instead. `links.events` and `links.download` are unaffected.
## Examples — direct `multipart/form-data`
```go Go theme={null}
body:=&bytes.Buffer{}; w:=multipart.NewWriter(body); image,_:=os.Open("character.png"); defer image.Close(); video,_:=os.Open("dance.mp4"); defer video.Close(); p,_:=w.CreateFormFile("image","character.png"); io.Copy(p,image); p,_=w.CreateFormFile("motion_video","dance.mp4"); io.Copy(p,video); w.WriteField("background_mode","original"); w.Close(); req,_:=http.NewRequest("POST","https://apis.viggle.ai/v1/renders",body); req.Header.Set("Authorization","Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type",w.FormDataContentType()); resp,err:=http.DefaultClient.Do(req); if err!=nil { panic(err) }; defer resp.Body.Close()
```
```javascript JavaScript theme={null}
const form=new FormData(); form.append("image",imageFile); form.append("motion_video",videoFile); form.append("background_mode","original"); const response=await fetch("https://apis.viggle.ai/v1/renders",{method:"POST",headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`},body:form}); const render=await response.json();
```
```python Python theme={null}
import os, requests
with open("character.png","rb") as image, open("dance.mp4","rb") as video: response=requests.post("https://apis.viggle.ai/v1/renders",headers={"Authorization":f"Bearer {os.environ['VIGGLE_API_KEY']}"},files={"image":image,"motion_video":video},data={"background_mode":"original"})
response.raise_for_status(); render=response.json()
```
```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/renders" -H "Authorization: Bearer $VIGGLE_API_KEY" -F "image=@character.png" -F "motion_video=@dance.mp4" -F "background_mode=original"
```
## Examples — draft-based `application/json`
```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/renders" \
-H "Authorization: Bearer $VIGGLE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"draft_id":"draft_abc123","upload_completions":[{"upload_handle":"up_1","etag":"\"9f...\""}]}'
```
```python Python theme={null}
import os, uuid, requests
response = requests.post(
"https://apis.viggle.ai/v1/renders",
headers={
"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"draft_id": "draft_abc123", "upload_completions": [{"upload_handle": "up_1", "etag": "\"9f...\""}]},
)
response.raise_for_status()
render = response.json()
```
See [Prepare Render](/v1/api-reference/renders/prepare) for how to obtain `draft_id` and upload the character/motion media before calling this endpoint in JSON mode.
## OpenAPI
````yaml openapi.yaml POST /v1/renders
openapi: 3.0.3
info:
title: Viggle API
description: Generate AI-powered character animation videos
version: 2.0.0
contact:
name: Viggle Support
url: https://viggle.ai
servers:
- url: https://apis.viggle.ai
description: Production server
security:
- bearerAuth: []
tags:
- name: Renders
description: Prepare inputs, create renders, observe progress, and retrieve results.
- name: Credits
description: Read the credit balance available to the calling principal.
- name: Characters
description: |
Create, list, inspect, and delete reusable character assets. `type`
selects whether creation also extracts a 3D vsplat; export its
download URL separately once ready.
- name: Motions
description: |
Create, list, inspect, and delete reusable motion assets, and import one
from an official motion template. `type` selects whether creation also
extracts or generates a 3D animation; export its download URL
separately once ready.
- name: Videos
description: >
Generate a MiniMax H3 video from text, frames, or references (`vid_`
prefix) or a character-animation video from a character image and/or
driving video
(`anim_` prefix), and read the unified view over every video the
caller owns — H3 generations, character-animation generations, and
character+motion Renders (`render_` prefix) — merged into one
resource.
- name: Images
description: |
Viggle Image — generate 1–6 PNG images from a text prompt with the
`qwen` model, optionally guided by up to 8 reference images
(`img_` prefix), and retrieve them by ID.
paths:
/v1/renders:
post:
tags:
- Renders
summary: Create a render
description: |
The request body carries one of two shapes and the `Content-Type`
selects between them.
`multipart/form-data` creates a render directly from character and
motion inputs, each supplied as an uploaded file, a URL, or the id of a
saved asset. This form answers `200` and ignores `Idempotency-Key`.
`application/json` creates a render from a draft prepared by
`POST /v1/renders/prepare`. This form answers `202`, requires
`Idempotency-Key`, and is idempotent within the authenticated project or
OAuth principal: reusing the same key with the same normalized input
returns the original render, while reusing it with different input
returns `IDEMPOTENCY_KEY_REUSED`.
Billed at $0.01 per character in the render, per second of the
finished video. Only one character is supported per render today,
so this is $0.01/second in practice, with no per-render minimum.
The amount reserved at creation time is an estimate; it is finalized
against the actual completed duration once the render finishes.
operationId: createRender
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateRenderForm'
application/json:
schema:
$ref: '#/components/schemas/CreateRenderRequest'
responses:
'200':
description: |
Render accepted from a direct `multipart/form-data` request. Only
`id`, `status`, `progress`, and `created_at` carry information.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Render'
'202':
description: Render accepted from a prepared draft.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Render'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/V1Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: |
Caller-generated stable key, maximum 255 characters. Required by the
`application/json` draft form of `POST /v1/renders` and ignored by the
`multipart/form-data` form.
schema:
type: string
minLength: 1
maxLength: 255
RequestId:
name: X-Request-Id
in: header
required: false
description: >-
Optional caller-supplied correlation ID, up to 128 characters. The
service returns the effective value in the response header for tracing
and support.
schema:
type: string
minLength: 1
maxLength: 128
SourceChannel:
name: X-Viggle-Source
in: header
required: false
description: >-
Optional source-channel label, up to 128 characters, used to attribute
traffic to an SDK, integration, product surface, or internal workflow.
schema:
type: string
minLength: 1
maxLength: 128
schemas:
CreateRenderForm:
description: |
Supply the character as one of `image`, `image_url` (or its
`ref_url`/`ref_image_url` aliases), or `character_id`, and the motion
as one of `motion_video`, `motion_video_url` (or its
`video_url`/`driving_video_url` aliases), or `motion_id`/`scene_id`.
If neither group is supplied at all, the server
substitutes its own preconfigured default `character_id`/`motion_id`
and renders that instead of rejecting the request — supplying either
group partially (for example a character source with no motion
source) is still an error.
type: object
properties:
image:
type: string
format: binary
description: >-
Character image uploaded directly. Use exactly one character source
among `image`, `image_url`, and `character_id`.
image_url:
type: string
format: uri
description: >-
Public URL of a character image that the service can fetch. Use
instead of `image` or `character_id`.
ref_url:
type: string
format: uri
deprecated: true
description: >-
Backward-compatible alias for `image_url`. Do not combine character
URL aliases.
ref_image_url:
type: string
format: uri
deprecated: true
description: >-
Backward-compatible alias for `image_url`. Do not combine character
URL aliases.
character_id:
type: string
description: >-
ID of a ready reusable Character owned by the caller. Use instead of
uploading or linking a new image.
minLength: 1
motion_video:
type: string
format: binary
description: >-
Driving video uploaded directly. Use exactly one motion source among
`motion_video`, `motion_video_url`, and `motion_id`.
motion_video_url:
type: string
format: uri
description: >-
Public URL of a driving video that the service can fetch. Use
instead of `motion_video` or `motion_id`.
video_url:
type: string
format: uri
deprecated: true
description: >-
Backward-compatible alias for `motion_video_url`. Do not combine
motion URL aliases.
driving_video_url:
type: string
format: uri
deprecated: true
description: >-
Backward-compatible alias for `motion_video_url`. Do not combine
motion URL aliases.
motion_id:
type: string
description: >-
ID of a ready reusable Motion owned by the caller. Use instead of
uploading or linking a new driving video.
minLength: 1
scene_id:
type: string
deprecated: true
description: >-
Backward-compatible alias for `motion_id` (the internal name for a
reusable Motion). Do not send both fields.
minLength: 1
mode:
type: string
enum:
- full_pipeline
- preprocessed
- character_only
- scene_preprocess
description: >-
Advanced pipeline mode. Omit to infer `preprocessed` when a Motion
ID is supplied and `full_pipeline` otherwise.
background_mode:
description: |
`inpaint` is accepted and treated as `original`. This set is
unrelated to `RenderOutputOptions.background_mode`, which belongs to
the draft-based flow.
type: string
enum:
- original
- solid
- transparent
- inpaint
default: original
bg_color:
description: |
Solid background colour as three decimal components, `"R,G,B"`, for
example `"0,177,64"`. Valid only with `background_mode=solid`.
type: string
example: 0,177,64
background_url:
type: string
format: uri
description: >-
Optional custom background image URL forwarded to the render
pipeline. Normally omitted unless the selected pipeline mode
supports it.
model:
type: string
enum:
- V3
- v3
- V3_Preview
- V4
- v4
- V4_Preview
- V4_BaseSG
description: >-
Optional render model. Omit to let the service infer the model from
saved assets or use its configured default.
character_mapping:
type: string
description: >-
Advanced multipart field containing a JSON object that maps motion
segment IDs to Character IDs. Character IDs may use the public
`char_` prefix.
CreateRenderRequest:
type: object
additionalProperties: false
required:
- draft_id
properties:
draft_id:
type: string
description: >-
Draft identifier returned by `POST /v1/renders/prepare`. A draft can
be consumed only once, subject to idempotency handling.
minLength: 1
upload_completions:
type: array
description: >-
Completed upload handles for every plan returned by Prepare Render.
Omit or send an empty array when the draft required no uploads.
items:
$ref: '#/components/schemas/UploadCompletion'
Render:
description: |
`stage`, `progress`, and `created_at` are null on renders that carry no
such information, and `links` is absent on renders served by the
migration proxy. Treat all four as optional when reading.
The resource response exposes the result URLs but does not expose
media dimensions, duration, thumbnail URL, or URL expiry metadata.
Clients must not infer those fields from this contract.
type: object
additionalProperties: false
required:
- id
- status
- stage
- progress
- video_url
- alpha_url
- created_at
- completed_at
- error
properties:
id:
type: string
description: >-
Public Render ID, normally beginning with `render_`; use it with
get, events, and download operations.
minLength: 1
status:
description: >-
Overall render lifecycle. `ready`, `failed`, and `cancelled` are
terminal states.
allOf:
- $ref: '#/components/schemas/RenderStatus'
stage:
type: string
description: >-
Coarse pipeline phase when one can be mapped to the public
vocabulary; null when unavailable or unknown.
nullable: true
allOf:
- $ref: '#/components/schemas/RenderStage'
progress:
type: integer
description: >-
Best-effort completion percentage from 0 through 100; null when the
active pipeline does not report progress.
nullable: true
minimum: 0
maximum: 100
video_url:
type: string
description: >-
Short-lived URL of the completed rendered video; null until the
render is ready or when no output was produced.
nullable: true
format: uri
alpha_url:
type: string
description: >-
Short-lived alpha/mask video URL for transparent output; null for
non-transparent renders or until ready.
nullable: true
format: uri
created_at:
type: string
description: >-
ISO 8601 timestamp when the render was created; null when the
backing pipeline did not provide it.
nullable: true
format: date-time
completed_at:
type: string
description: >-
ISO 8601 timestamp when the render entered a terminal state; null
while it is still active.
nullable: true
format: date-time
error:
type: object
description: >-
Structured failure details when `status` is `failed`; otherwise
null.
nullable: true
allOf:
- $ref: '#/components/schemas/RenderFailure'
links:
description: >-
Navigation paths for this render. May be absent on records served
through the migration proxy.
allOf:
- $ref: '#/components/schemas/RenderLinks'
UploadCompletion:
type: object
additionalProperties: false
required:
- upload_handle
properties:
upload_handle:
type: string
description: >-
Opaque handle from the matching `UploadPlan`; it tells the service
which planned input was uploaded.
minLength: 1
etag:
type: string
description: >-
Optional ETag returned by the object-store upload response,
including quotes when the storage service supplies them.
minLength: 1
RenderStatus:
type: string
enum:
- queued
- processing
- ready
- failed
- cancelled
RenderStage:
description: |
A coarse progress hint. `analyzing`, `rendering`, and `finishing` are
emitted for renders created through the `multipart/form-data` form;
every other value belongs to the draft-based pipeline. Treat an
unrecognized value as "in progress" rather than failing.
type: string
enum:
- queued
- preparing
- generating
- finalizing
- ready
- failed
- cancelled
- analyzing
- rendering
- finishing
RenderFailure:
type: object
additionalProperties: false
required:
- code
- message
properties:
code:
type: string
description: >-
Stable machine-readable failure code. Use it for programmatic
handling instead of parsing the message.
message:
type: string
description: Human-readable explanation of why the render failed.
details:
type: object
description: >-
Additional structured context supplied by the failing service; keys
vary by error code.
additionalProperties: true
request_id:
type: string
description: >-
Request or worker correlation identifier to provide to support; null
when the failure was not associated with one.
nullable: true
RenderLinks:
type: object
additionalProperties: false
required:
- self
- events
- download
properties:
self:
type: string
description: >-
Relative API path for retrieving the latest durable state of this
render.
events:
type: string
description: >-
Relative API path for watching this render through Server-Sent
Events.
download:
type: string
description: >-
Relative API path that resolves a fresh short-lived download URL
after the render is ready.
ErrorResponse:
type: object
additionalProperties: false
required:
- error
properties:
error:
description: >-
Top-level draft-flow error payload containing the stable code,
message, retry guidance, correlation ID, and error-specific details.
allOf:
- $ref: '#/components/schemas/ErrorBody'
ErrorBody:
type: object
additionalProperties: false
required:
- code
- message
- retryable
- request_id
- details
- remediation
properties:
code:
description: Stable error category from the draft-based render error vocabulary.
allOf:
- $ref: '#/components/schemas/ErrorCode'
message:
type: string
description: >-
Human-readable explanation suitable for logs or presentation to a
developer.
retryable:
type: boolean
description: >-
Whether retrying the operation without changing its semantic input
may succeed.
request_id:
type: string
description: >-
Correlation identifier for tracing and support. Include it when
reporting the failure.
details:
type: object
description: Error-specific structured context; available keys depend on `code`.
additionalProperties: true
remediation:
description: Suggested recovery action and optional retry delay.
allOf:
- $ref: '#/components/schemas/ErrorRemediation'
ErrorCode:
description: |
The failure vocabulary of the draft-based render flow. The resource
operations project the same vocabulary onto the lower_snake_case codes
described by `ResourceError`.
type: string
enum:
- UNAUTHENTICATED
- INVALID_CREDENTIAL
- FORBIDDEN
- INVALID_REQUEST
- INVALID_CHARACTER
- INVALID_MOTION
- UNSUPPORTED_MEDIA
- CONTENT_POLICY_VIOLATION
- UPLOAD_REQUIRED
- UPLOAD_MISMATCH
- UPLOAD_EXPIRED
- DRAFT_NOT_FOUND
- DRAFT_ALREADY_CONSUMED
- RENDER_NOT_FOUND
- RENDER_NOT_CANCELLABLE
- CHARACTER_NOT_FOUND
- MOTION_NOT_FOUND
- MOTION_NOT_READY
- MOTION_TEMPLATE_NOT_FOUND
- AVATAR_NOT_FOUND
- ANIMATION_NOT_FOUND
- EXTRACTION_UNAVAILABLE
- EXTRACTION_FAILED
- IDEMPOTENCY_KEY_REUSED
- INSUFFICIENT_CREDITS
- RATE_LIMITED
- SERVICE_BUSY
- INTERNAL_ERROR
- NOT_FOUND
- TASK_FAILED
ErrorRemediation:
type: object
additionalProperties: false
required:
- action
- retry_after_ms
properties:
action:
type: string
description: >-
Suggested machine-readable or human-readable next action, such as
retrying later, uploading media again, or correcting input.
retry_after_ms:
type: integer
description: >-
Recommended delay in milliseconds before retrying; null when no
timed retry is advised.
nullable: true
format: int64
minimum: 0
headers:
RequestId:
description: Stable request identifier for support and tracing.
schema:
type: string
responses:
BadRequest:
description: Invalid request.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
V1Unauthorized:
description: Missing, invalid, or expired credential.
headers:
WWW-Authenticate:
schema:
type: string
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PaymentRequired:
description: Insufficient credits.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Credential does not grant access to this resource.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Draft or render not found.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Conflict:
description: State or idempotency conflict.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
UnprocessableEntity:
description: Media or content policy rejection.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: Rate limit exceeded.
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Unexpected server error.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServiceUnavailable:
description: Service temporarily unavailable.
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or OAuth access token
description: |
Server-side SDK clients use a project API key. Remote MCP clients use
an OAuth access token. Never expose a project API key in browser code.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.