# Runway Dev API reference > Generated from the OpenAPI 3.1 specification that powers the interactive reference at https://docs.dev.runwayml.com/api. The machine-readable document is at https://docs.dev.runwayml.com/openapi.json. ## Conventions - Base URL: `https://api.dev.runwayml.com` - Authentication `ApiKeyAuth`: http, bearer - Header `X-Runway-Version` (required): `2024-11-06` - Generation endpoints are asynchronous. They return a task `id`; poll `GET /v1/tasks/{id}` until `status` is `SUCCEEDED` or `FAILED`. - Where an endpoint lists several models below, the request body is a discriminated union on `model`. Only the fields listed under that model are valid. - Credit costs are not in this file. See https://docs.dev.runwayml.com/guides/pricing. ## Endpoint groups - **Avatars** (9 endpoints) - **Avatar Videos** (1 endpoint) - **Knowledge** (5 endpoints) - **Realtime Sessions** (3 endpoints) - **Task management** (2 endpoints) - **Start generating** (13 endpoints) - **Model Router** (9 endpoints) - **Organization** (5 endpoints) - **Uploads** (1 endpoint) - **Recipes** (7 endpoints) - **Voices** (6 endpoints) - **Workflows** (4 endpoints) ## Avatars ### GET /v1/avatars List avatars List avatars for the authenticated user with cursor-based pagination. Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. Response 200: - `data` (array of object, required) — The list of items for the current page. - `id` (string, required) — format uuid. The unique identifier of the avatar. - `name` (string, required) — The character name for the avatar. - `personality` (string, required) — System prompt defining how the avatar should behave in conversations. - `startScript` (string or null, required) — Opening message that the avatar will say when a session starts, or null if not set. - `voice` (object, required) — The voice configured for this avatar. - `type` (string, required) — one of `runway-live-preset` - `presetId` (string, required) — one of `victoria`, `vincent`, `clara`, `drew`, `skye`, `max`, `morgan`, `felix`, `mia`, `marcus`, `summer`, `ruby`, `aurora`, `jasper`, `leo`, `adrian`, `nina`, `emma`, `blake`, `david`, `maya`, `nathan`, `sam`, `georgia`, `petra`, `adam`, `zach`, `violet`, `roman`, `luna`. The preset voice identifier. - `name` (string, required) — The display name of the voice. - `description` (string, required) — A brief description of the voice characteristics. - `referenceImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the avatar's reference image. - `processedImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the processed reference image. - `documentIds` (array of string, required) — IDs of knowledge documents attached to this avatar. - `createdAt` (string, required) — format date-time. When the avatar was created. - `updatedAt` (string, required) — format date-time. When the avatar was last updated. - `status` (string, required) — one of `PROCESSING` - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ### POST /v1/avatars Create avatar Create a new avatar with a reference image and voice. Request body: - `name` (string, required) — max length 50. The character name for the avatar. - `referenceImage` (string, required) — A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See [our docs](/assets/inputs#images) for supported formats. - `personality` (string, required) — max length 10000. System prompt defining how the avatar should behave in conversations. - `startScript` (string) — max length 2000. Optional opening message that the avatar will say when a session starts. - `voice` (object, required) — The voice configuration for the avatar. - `type` (string, required) — one of `runway-live-preset` - `presetId` (string, required) — one of `victoria`, `vincent`, `clara`, `drew`, `skye`, `max`, `morgan`, `felix`, `mia`, `marcus`, `summer`, `ruby`, `aurora`, `jasper`, `leo`, `adrian`, `nina`, `emma`, `blake`, `david`, `maya`, `nathan`, `sam`, `georgia`, `petra`, `adam`, `zach`, `violet`, `roman`, `luna`. The ID of a preset voice. Available voices: `victoria` (Victoria), `vincent` (Vincent), `clara` (Clara), `drew` (Drew), `skye` (Skye), `max` (Max), `morgan` (Morgan), `felix` (Felix), `mia` (Mia), `marcus` (Marcus), `su… - `documentIds` (array of string) — max 50 items. Optional list of knowledge document IDs to attach to this avatar. Documents provide additional context during conversations. - `imageProcessing` (string) — one of `optimize`, `none`; default `optimize`. Controls image preprocessing. `optimize` improves the image for better avatar results. `none` uses the image as-is; quality not guaranteed. Response 200: - `id` (string, required) — format uuid. The unique identifier of the avatar. - `name` (string, required) — The character name for the avatar. - `personality` (string, required) — System prompt defining how the avatar should behave in conversations. - `startScript` (string or null, required) — Opening message that the avatar will say when a session starts, or null if not set. - `voice` (object, required) — The voice configured for this avatar. - `type` (string, required) — one of `runway-live-preset` - `presetId` (string, required) — one of `victoria`, `vincent`, `clara`, `drew`, `skye`, `max`, `morgan`, `felix`, `mia`, `marcus`, `summer`, `ruby`, `aurora`, `jasper`, `leo`, `adrian`, `nina`, `emma`, `blake`, `david`, `maya`, `nathan`, `sam`, `georgia`, `petra`, `adam`, `zach`, `violet`, `roman`, `luna`. The preset voice identifier. - `name` (string, required) — The display name of the voice. - `description` (string, required) — A brief description of the voice characteristics. - `referenceImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the avatar's reference image. - `processedImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the processed reference image. - `documentIds` (array of string, required) — IDs of knowledge documents attached to this avatar. - `createdAt` (string, required) — format date-time. When the avatar was created. - `updatedAt` (string, required) — format date-time. When the avatar was last updated. - `status` (string, required) — one of `PROCESSING` ### GET /v1/avatar_conversations List conversations List realtime avatar conversations for the authenticated user with cursor-based pagination. Each conversation corresponds to a realtime session, and the conversation ID matches the realtime session ID. Pass `avatar` to… Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `20`. The maximum number of items to return per page. - `avatar` (query, string) — format uuid. Filter to conversations that used the given custom avatar. - `startDate` (query, string) — format date-time. Filter conversations created on or after this timestamp (inclusive). - `endDate` (query, string) — format date-time. Filter conversations created before this timestamp (exclusive). Response 200: - `data` (array of object, required) — Array of conversation summaries. - `id` (string, required) — format uuid. Unique conversation identifier. This is the same value as the realtime session ID for the call. - `name` (string, required) — Conversation name (auto-generated or user-provided). - `status` (string, required) — one of `in_progress`, `ended`, `failed`. The status of the conversation. `in_progress` means the session is active, `ended` means it completed successfully, `failed` means it ended due to an error. - `avatar` (object or null, required) — The avatar used in this conversation, or null if unavailable. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — The preset avatar ID. - `name` (string, required) — The preset avatar's display name (e.g. "Mina"). - `createdAt` (string, required) — format date-time. When the conversation was created. - `duration` (integer or null, required) — Duration of the conversation in seconds, or null if not started. - `hasTools` (boolean, required) — Whether tools were configured for this conversation session. - `hasMore` (boolean, required) — Whether there are more conversations to fetch. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if no more pages. ### GET /v1/avatar_usage Get avatar usage Get aggregate usage statistics for avatar conversations, including total duration, session counts, average duration, and a per-day breakdown. Per-day buckets are keyed by UTC calendar date. The date range must not excee… Parameters: - `startDate` (query, string, required) — format date-time. Start of the date range in UTC (inclusive). Required. - `endDate` (query, string, required) — format date-time. End of the date range in UTC (exclusive). Required. Response 200: - `totalSeconds` (integer, required) — Total seconds across conversations with a measured duration in the date range. - `totalSessions` (integer, required) — Number of conversations started in the date range. Includes unfinished and failed conversations. - `avgDurationSeconds` (integer, required) — Average duration in seconds across conversations with a measured duration, or 0 if none completed. May not equal `totalSeconds / totalSessions` because unfinished conversations contribute to the session count but not th… - `byDay` (array of object, required) — Per-day usage across the date range. Days with no sessions are included with zeroes. - `date` (string, required) — format date. The UTC calendar date (YYYY-MM-DD). - `sessions` (integer, required) — Number of conversations started on this date. - `seconds` (integer, required) — Total seconds of measured conversation duration on this date. ### GET /v1/avatar_conversations/{id} Get conversation Get detailed information about a specific conversation, including the transcript and recording download URL when available. The conversation ID is the same value returned when the realtime session was created. Parameters: - `id` (path, string, required) — format uuid. The conversation ID. This is the same value as the realtime session ID for the call. Response 200: - `id` (string, required) — format uuid. Unique conversation identifier. This is the same value as the realtime session ID for the call. - `name` (string, required) — Conversation name. - `avatar` (object or null, required) — The avatar used in this conversation, or null if unavailable. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — The preset avatar ID. - `createdAt` (string, required) — format date-time. When the conversation was created. - `maxDuration` (integer or null, required) — Maximum allowed duration in seconds, or null if not set. - `transcript` (array of object, required) — max 1000 items. The conversation transcript. - `role` (string, required) — one of `user`, `assistant`. Who produced this transcript entry. - `content` (string or null, required) — The spoken text, or null for tool-only turns. - `timestamp` (string or null, required) — When this entry occurred, or null if unavailable. - `toolCalls` (array of object) — Tool invocations made during this assistant turn. Only present on assistant entries. - `id` (string) — Optional identifier linking this call to its result. - `name` (string, required) — The name of the tool that was called. - `arguments` (object, required) — The arguments passed to the tool. - `toolResults` (array of object) — Tool results received during this assistant turn. Only present on assistant entries. - `id` (string) — Optional identifier linking this result to its call. - `name` (string, required) — The name of the tool that returned a result. - `result` (object or string or null) — The tool result (object, string, or null). - `error` (string or null) — Error message if the tool call failed. - `durationMs` (number or null) — How long the tool call took in milliseconds. - `recordingUrl` (string or null, required) — A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL. - `tools` (array of object, required) — The tools that were configured for this conversation session. Empty if no tools were used. - `type` (string, required) — one of `client_event`, `backend_rpc`. The tool type. - `name` (string, required) — The tool name. - `description` (string, required) — A description of when and how the tool should be used. - `status` (string, required) — one of `in_progress` - `startedAt` (string or null, required) — When the conversation started, or null if not yet started. - `duration` (integer or null, required) — Elapsed duration in seconds, or null if not yet started. ### DELETE /v1/avatar_conversations/{id} Delete conversation Delete a conversation and its associated data. Parameters: - `id` (path, string, required) — format uuid. The conversation ID. ### GET /v1/avatars/{id} Get avatar Get details of a specific avatar. Parameters: - `id` (path, string, required) — format uuid Response 200: - `id` (string, required) — format uuid. The unique identifier of the avatar. - `name` (string, required) — The character name for the avatar. - `personality` (string, required) — System prompt defining how the avatar should behave in conversations. - `startScript` (string or null, required) — Opening message that the avatar will say when a session starts, or null if not set. - `voice` (object, required) — The voice configured for this avatar. - `type` (string, required) — one of `runway-live-preset` - `presetId` (string, required) — one of `victoria`, `vincent`, `clara`, `drew`, `skye`, `max`, `morgan`, `felix`, `mia`, `marcus`, `summer`, `ruby`, `aurora`, `jasper`, `leo`, `adrian`, `nina`, `emma`, `blake`, `david`, `maya`, `nathan`, `sam`, `georgia`, `petra`, `adam`, `zach`, `violet`, `roman`, `luna`. The preset voice identifier. - `name` (string, required) — The display name of the voice. - `description` (string, required) — A brief description of the voice characteristics. - `referenceImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the avatar's reference image. - `processedImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the processed reference image. - `documentIds` (array of string, required) — IDs of knowledge documents attached to this avatar. - `createdAt` (string, required) — format date-time. When the avatar was created. - `updatedAt` (string, required) — format date-time. When the avatar was last updated. - `status` (string, required) — one of `PROCESSING` ### PATCH /v1/avatars/{id} Update avatar Update an existing avatar. At least one field must be provided. Parameters: - `id` (path, string, required) — format uuid Request body: - `name` (string) — max length 50. The character name for the avatar. - `referenceImage` (string) — A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See [our docs](/assets/inputs#images) for supported formats. - `personality` (string) — max length 10000. System prompt defining how the avatar should behave in conversations. - `startScript` (string or null) — Optional opening message that the avatar will say when a session starts. Set to null to clear. - `voice` (object) — The voice configuration for the avatar. - `type` (string, required) — one of `runway-live-preset` - `presetId` (string, required) — one of `victoria`, `vincent`, `clara`, `drew`, `skye`, `max`, `morgan`, `felix`, `mia`, `marcus`, `summer`, `ruby`, `aurora`, `jasper`, `leo`, `adrian`, `nina`, `emma`, `blake`, `david`, `maya`, `nathan`, `sam`, `georgia`, `petra`, `adam`, `zach`, `violet`, `roman`, `luna`. The ID of a preset voice. Available voices: `victoria` (Victoria), `vincent` (Vincent), `clara` (Clara), `drew` (Drew), `skye` (Skye), `max` (Max), `morgan` (Morgan), `felix` (Felix), `mia` (Mia), `marcus` (Marcus), `su… - `documentIds` (array of string) — max 50 items. List of knowledge document IDs to attach to this avatar. Replaces all current attachments. Documents provide additional context during conversations. - `imageProcessing` (string) — one of `optimize`, `none`; default `optimize`. Controls image preprocessing. `optimize` improves the image for better avatar results. `none` uses the image as-is; quality not guaranteed. Response 200: - `id` (string, required) — format uuid. The unique identifier of the avatar. - `name` (string, required) — The character name for the avatar. - `personality` (string, required) — System prompt defining how the avatar should behave in conversations. - `startScript` (string or null, required) — Opening message that the avatar will say when a session starts, or null if not set. - `voice` (object, required) — The voice configured for this avatar. - `type` (string, required) — one of `runway-live-preset` - `presetId` (string, required) — one of `victoria`, `vincent`, `clara`, `drew`, `skye`, `max`, `morgan`, `felix`, `mia`, `marcus`, `summer`, `ruby`, `aurora`, `jasper`, `leo`, `adrian`, `nina`, `emma`, `blake`, `david`, `maya`, `nathan`, `sam`, `georgia`, `petra`, `adam`, `zach`, `violet`, `roman`, `luna`. The preset voice identifier. - `name` (string, required) — The display name of the voice. - `description` (string, required) — A brief description of the voice characteristics. - `referenceImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the avatar's reference image. - `processedImageUri` (string or null, required) — A URI pointing to a low-resolution preview of the processed reference image. - `documentIds` (array of string, required) — IDs of knowledge documents attached to this avatar. - `createdAt` (string, required) — format date-time. When the avatar was created. - `updatedAt` (string, required) — format date-time. When the avatar was last updated. - `status` (string, required) — one of `PROCESSING` Other responses: `409` ### DELETE /v1/avatars/{id} Delete avatar Delete an avatar. Parameters: - `id` (path, string, required) — format uuid ## Avatar Videos ### POST /v1/avatar_videos Generate avatar video from audio or text Start an asynchronous task to generate a video of an avatar speaking. Provide `speech` with `type: "audio"` (audio file) or `type: "text"` (text script for TTS). Poll `GET /v1/tasks/:id` to check progress and retrieve t… Request body: - `model` (string, required) — one of `gwm1_avatars`. The model to use for avatar video generation. - `avatar` (object, required) — The avatar configuration for the session. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — one of `game-character`, `music-superstar`, `game-character-man`, `cat-character`, `influencer`, `tennis-coach`, `human-resource`, `fashion-designer`, `cooking-teacher`. ID of a preset avatar. - `speech` (object, required) — The speech source for avatar video generation. Either an audio file or text script. - `type` (string, required) — one of `audio` - `audio` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. Response 200: - `id` (string, required) — format uuid. The ID of the avatar video task. Use `GET /v1/tasks/:id` to poll for status and output. ## Knowledge ### GET /v1/documents List documents List knowledge documents for the authenticated user with cursor-based pagination. Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. - `sort` (query, string, required) — one of `createdAt`, `updatedAt`; default `createdAt`. Field to sort results by. - `order` (query, string, required) — one of `asc`, `desc`; default `desc`. Sort direction. Response 200: - `data` (array of object, required) — The list of items for the current page. - `id` (string, required) — format uuid. The unique identifier of the document. - `name` (string, required) — The name of the document. - `type` (string, required) — one of `text`, `file`. The type of document. - `usedBy` (array of object, required) — Avatars that use this document. - `id` (string, required) — format uuid. The avatar ID. - `name` (string, required) — The avatar name. - `imageUrl` (string or null, required) — URL to the avatar image, or null if not yet processed. - `createdAt` (string, required) — format date-time. When the document was created. - `updatedAt` (string, required) — format date-time. When the document was last updated. - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ### POST /v1/documents Create document Create a new knowledge document. Documents can be attached to avatars to provide additional context during conversations. Request body: - `name` (string, required) — max length 255. A descriptive name for the document. - `content` (string, required) — max length 200000. The markdown or plain text content of the document. Response 200: - `id` (string, required) — format uuid. The unique identifier of the document. - `name` (string, required) — The name of the document. - `type` (string, required) — one of `text`, `file`. The type of document. - `usedBy` (array of object, required) — Avatars that use this document. Always empty for newly created documents. - `id` (string, required) — format uuid. The avatar ID. - `name` (string, required) — The avatar name. - `imageUrl` (string or null, required) — URL to the avatar image, or null if not yet processed. - `content` (string, required) — The full content of the document. - `createdAt` (string, required) — format date-time. When the document was created. - `updatedAt` (string, required) — format date-time. When the document was last updated. ### GET /v1/documents/{id} Get document Get details of a specific knowledge document. Parameters: - `id` (path, string, required) — format uuid. The document ID. Response 200: - `id` (string, required) — format uuid. The unique identifier of the document. - `name` (string, required) — The name of the document. - `type` (string, required) — one of `text`, `file`. The type of document. - `usedBy` (array of object, required) — Avatars that use this document. - `id` (string, required) — format uuid. The avatar ID. - `name` (string, required) — The avatar name. - `imageUrl` (string or null, required) — URL to the avatar image, or null if not yet processed. - `content` (string, required) — The full content of the document. - `createdAt` (string, required) — format date-time. When the document was created. - `updatedAt` (string, required) — format date-time. When the document was last updated. ### PATCH /v1/documents/{id} Update document Update a knowledge document. At least one of `name` or `content` must be provided. Parameters: - `id` (path, string, required) — format uuid. The document ID. Request body: - `name` (string) — max length 255. A new name for the document. - `content` (string) — max length 200000. New markdown or plain text content for the document. ### DELETE /v1/documents/{id} Delete document Delete a knowledge document. This also removes it from all avatars it was attached to. Parameters: - `id` (path, string, required) — format uuid. The document ID. ## Realtime Sessions ### POST /v1/realtime_sessions Create realtime session Create a new realtime session with the specified model configuration. The returned ID is also the conversation ID used later to fetch transcripts and recordings from the avatar conversation endpoints. Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/realtime_sessions — model `gwm1_avatars` - `model` (string, required) — one of `gwm1_avatars`. The realtime session model type. - `avatar` (object, required) — The avatar configuration for the session. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — one of `game-character`, `music-superstar`, `game-character-man`, `cat-character`, `influencer`, `tennis-coach`, `human-resource`, `fashion-designer`, `cooking-teacher`. ID of a preset avatar. - `maxDuration` (integer) — 10–1800; default `300`. Maximum session duration in seconds. - `personality` (string) — max length 10000. Override the avatar personality for this session. If not provided, uses the avatar default. - `startScript` (string) — max length 2000. Override the avatar start script for this session. If not provided, uses the avatar default. - `tools` (array of object) — max 20 items; default `[]`. Tools available to the avatar during the session. - `type` (string, required) — one of `client_event` - `name` (string, required) — max length 64. The tool name. Must start with a letter or underscore, followed by alphanumeric characters or underscores. - `description` (string, required) — max length 1024. A description of when and how the tool should be used. Be specific so the avatar understands the right context to invoke it. - `parameters` (array of object) — max 20 items; default `[]` - `name` (string, required) — max length 64. The parameter name. - `description` (string, required) — max length 1024. A description of the parameter. - `required` (boolean) — default `true`. Whether the parameter is required. - `type` (string, required) — one of `string` - `enum` (array of string) — max 20 items. Allowed values for the parameter. - `integration` (object) — External integration. Runway renders the avatar; the integration owns conversation or audio. - `type` (string, required) — one of `elevenlabs` - `signedUrl` (string, required) — format uri. ConvAI signed WebSocket URL (~15 min lifetime). Must be a wss:// or https:// URL that resolves to a public host. - `livekit` (object) — Use integration with type "livekit" instead. - `url` (string, required) — format uri. WebSocket URL of the external LiveKit server the avatar worker should join. Must be a wss:// or https:// URL that resolves to a public host. - `token` (string, required) — max length 2048. LiveKit access token granting the avatar worker publish rights in the external room. - `roomName` (string, required) — max length 256. Name of the external LiveKit room. - `agentIdentity` (string) — max length 256. The participant identity of the customer agent already in the room. When provided, the avatar worker trusts audio published by this identity. Response 200: - `id` (string, required) — format uuid. The ID of the created realtime session. This same value is later used as the conversation ID in the avatar conversation endpoints. ### GET /v1/realtime_sessions/{id} Get realtime session Get the status of a realtime session. This endpoint uses the same ID that the avatar conversation endpoints later expose as the conversation ID. Parameters: - `id` (path, string, required) — format uuid. The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints. Response 200: - `id` (string, required) — format uuid. The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints. - `createdAt` (string, required) — format date-time. When the session was created. - `status` (string, required) — one of `NOT_READY` - `queued` (boolean) — When true, the session is waiting in a queue for available capacity. When false or absent, the session is actively being provisioned. ### DELETE /v1/realtime_sessions/{id} Cancel realtime session Cancel an active realtime session. Parameters: - `id` (path, string, required) — format uuid. The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints. ## Task management Endpoints for managing tasks that have been submitted. ### GET /v1/tasks/{id} Get task detail Return details about a task. Consumers of this API should not expect updates more frequent than once every five seconds for a given task. Parameters: - `id` (path, string, required) — format uuid. The ID of a previously-submitted task that has not been canceled or deleted. Response 200: - `id` (string, required) — format uuid. The ID of the task being returned. - `createdAt` (string, required) — format date-time. The timestamp that the task was submitted at. - `status` (string, required) — one of `PENDING` - `estimatedCost` (object, required) — Estimated cost, computed against current pricing. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `404` ### DELETE /v1/tasks/{id} Cancel or delete a task Tasks that are running, pending, or throttled can be canceled by invoking this method. Invoking this method for other tasks will delete them. The output data associated with a deleted task will be deleted from persisten… Parameters: - `id` (path, string, required) — format uuid. The ID of a previously-submitted task that has not been canceled or deleted. ## Start generating These endpoints all kick off tasks to create generations. ### POST /v1/image_to_video Image to video This endpoint will start a new task to generate a video from an image. Request body: one of 16 shapes, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/image_to_video — model `gen4.5` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `promptImage` (string or array of object, required) - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`. The position of the image in the output video. "first" will use the image as the first frame of the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `ratio` (string, required) — one of `1280:720`, `720:1280`, `1104:832`, `960:960`, `832:1104`, `1584:672`. The resolution of the output video. - `duration` (integer, required) — 2–10. The number of seconds of duration for the output video. Must be an integer from 2 to 10. - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `outputFormat` (string) — one of `mp4`, `prores`, `png_sequence`, `hdr10`, `hlg`, `sdr_rec709_10bit`, `hdr_pq_12bit_master`, `hdr_prores`, `hdr_png_sequence`, `hdr_exr_sequence`, `hdr_exr_acescg_sequence_1_3`, `hdr_exr_acescg_sequence_2_0`. The container/encoding of the output. `mp4` (default) returns an H.264 .mp4. `prores` returns a ProRes .mov. `png_sequence` returns a .zip of PNG frames (plus a separate .wav artifact when the output has audio). `hdr10`… - `proresProfile` (string) — one of `422`, `4444`, `422 Proxy`, `422 LT`, `422 HQ`, `4444 XQ`. The ProRes profile to use. Only valid when `outputFormat` is `prores` or `hdr_prores`. For `prores`, any profile is accepted and the default is `4444`. For `hdr_prores`, only `422`, `422 HQ` and `4444` are available and… - `model` (string, required) — one of `gen4.5` #### POST /v1/image_to_video — model `gen4_turbo` - `promptText` (string) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `promptImage` (string or array of object, required) - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`. The position of the image in the output video. "first" will use the image as the first frame of the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `ratio` (string, required) — one of `1280:720`, `720:1280`, `1104:832`, `832:1104`, `960:960`, `1584:672`. The resolution of the output video. - `duration` (integer) — 2–10. The number of seconds of duration for the output video. - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `model` (string, required) — one of `gen4_turbo` #### POST /v1/image_to_video — model `veo3.1` - `promptText` (string) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `promptImage` (string or array of object, required) — You may specify an image to use as the first frame of the output video, or an array with a first frame and optionally a last frame. This model does not support generating with only a last frame. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame of the video, "last" will use the image as the last frame of the video. - `ratio` (string, required) — one of `1280:720`, `720:1280`, `1080:1920`, `1920:1080`. The resolution of the output video. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Audio inclusion affects pricing. - `negativePrompt` (string) — max length 1000. Text describing what should not appear in the output video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (number) — one of `4`, `6`, `8`. The number of seconds of duration for the output video. - `model` (string, required) — one of `veo3.1` #### POST /v1/image_to_video — model `veo3.1_fast` - `promptText` (string) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `promptImage` (string or array of object, required) — You may specify an image to use as the first frame of the output video, or an array with a first frame and optionally a last frame. This model does not support generating with only a last frame. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame of the video, "last" will use the image as the last frame of the video. - `ratio` (string, required) — one of `1280:720`, `720:1280`, `1080:1920`, `1920:1080`. The resolution of the output video. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Audio inclusion affects pricing. - `negativePrompt` (string) — max length 1000. Text describing what should not appear in the output video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (number) — one of `4`, `6`, `8`. The number of seconds of duration for the output video. - `model` (string, required) — one of `veo3.1_fast` #### POST /v1/image_to_video — model `hailuo3` - `promptImage` (string or array of unknown, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `promptText` (string, required) — max length 6000. A non-empty text prompt describing what should appear in the output. - `resolution` (string) — one of `768p`, `2k`, `768P`, `2K`. The output resolution. Hailuo 3.0 supports 768p and 2k. - `duration` (integer) — 5–15. The number of seconds of duration for the output video. - `ratio` (string) — one of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. The aspect ratio of the output video. Use adaptive only when image or video references are provided; text-only requests require a concrete ratio. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `hailuo3` #### POST /v1/image_to_video — model `happyhorse_1_0` - `promptText` (string) — max length 2500. A string up to 2500 characters (measured in UTF-16 code units) describing motion or changes in the output video. - `promptImage` (string or array of object, required) - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`. The position of the image in the output video. "first" will use the image as the first frame of the video. - `resolution` (string) — one of `720p`, `1080p`, `720P`, `1080P`. Output quality tier. Output aspect ratio follows the input image. - `duration` (integer) — 3–15. The number of seconds of duration for the output video. - `model` (string, required) — one of `happyhorse_1_0` #### POST /v1/image_to_video — model `seedance2` - `promptImage` (string or array of object, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image. - `promptText` (string) — max length 3500. An optional text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`, `2206:946`, `1920:1080`, `1664:1248`, `1440:1440`, `1248:1664`, `1080:1920`, `3840:1646`, `3840:2160`, `3840:2880`, `3840:3840`, `2880:3840`, `2160:3840`. The resolution of the output video. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2` #### POST /v1/image_to_video — model `seedance2_fast` - `promptImage` (string or array of object, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image. - `promptText` (string) — max length 3500. An optional text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`. The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_fast` #### POST /v1/image_to_video — model `seedance2_mini` - `promptImage` (string or array of object, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image. - `promptText` (string) — max length 3500. An optional text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`. The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_mini` #### POST /v1/image_to_video — model `gemini_omni_flash` - `promptImage` (string or array of object, required) — An image to use as the first frame of the output video. Gemini Omni Flash only supports a first frame. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`. The position of the image in the output video. "first" will use the image as the first frame of the video. - `promptText` (string) — max length 4000. An optional text prompt describing how the video should evolve from the first frame. - `ratio` (string) — one of `1280:720`, `720:1280`. The aspect ratio of the output video: `1280:720` (landscape) or `720:1280` (portrait). - `duration` (integer) — 3–10. The duration of the output video in seconds, as a whole number from 3 to 10. - `model` (string, required) — one of `gemini_omni_flash` #### POST /v1/image_to_video — model `seedance2_5` - `promptImage` (string or array of object, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image. - `promptText` (string) — max length 15000. An optional text prompt up to 15000 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `854:480`, `752:560`, `640:640`, `560:752`, `480:854`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`, `2206:946`, `1920:1080`, `1664:1248`, `1440:1440`, `1248:1664`, `1080:1920`. The resolution of the output video. Seedance 2.5 supports 480p, 720p, and 1080p. - `referenceAudio` (array of object) — max 10 items. An optional array of audio references. The total combined duration must not exceed 30 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_5` #### POST /v1/image_to_video — model `grok_imagine_1_5` - `promptImage` (string or array of object, required) - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`. The position of the image in the output video. "first" will use the image as the first frame of the video. - `resolution` (string) — one of `480p`, `720p`, `1080p`. The output resolution. Output aspect ratio follows the input image. - `promptText` (string) — max length 2500. An optional text prompt describing motion or changes in the output video. - `duration` (integer) — 1–15. The number of seconds of duration for the output video. - `model` (string, required) — one of `grok_imagine_1_5` #### POST /v1/image_to_video — model `wan3` - `promptImage` (string or array of unknown, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `promptText` (string, required) — max length 20000. A non-empty text prompt describing what should appear in the output. - `audio` (boolean) — Whether to generate audio with the video. - `duration` (integer) — 2–30. The number of seconds of duration for the output video. - `ratio` (string) — one of `832:480`, `720:544`, `624:624`, `544:720`, `480:832`, `1280:720`, `1104:832`, `960:960`, `832:1104`, `720:1280`, `1920:1080`, `1648:1248`, `1440:1440`, `1248:1648`, `1080:1920`, `auto_480p`, `auto_720p`, `auto_1080p`. The resolution of the output video, as `:`. Keyframe image-to-video requests must use `auto_480p`, `auto_720p`, or `auto_1080p` because their aspect ratio follows the first frame. - `referenceVideos` (array of object) — max 5 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 5 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `wan3` #### POST /v1/image_to_video — model `gemini_omni_flash_1.1` - `promptImage` (string or array of object, required) — An image to use as the first frame, or an array containing a first frame and optional last frame. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame of the video, "last" will use the image as the last frame of the video. - `promptText` (string, required) — max length 4000. A non-empty text prompt describing how the video should evolve between the provided frames. - `ratio` (string) — one of `640:360`, `360:640`, `1280:720`, `720:1280`, `1920:1080`, `1080:1920`, `3840:2160`, `2160:3840`. The resolution and aspect ratio of the output video. - `duration` (string or integer) — The duration of the output video in seconds. Use "auto" to let the model choose a duration. Numeric durations must be between 3 and 10 seconds. - `model` (string, required) — one of `gemini_omni_flash_1.1` #### POST /v1/image_to_video — model `wan3_prime` - `promptImage` (string or array of unknown, required) — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed. - `promptText` (string, required) — max length 20000. A non-empty text prompt describing what should appear in the output. - `audio` (boolean) — Whether to generate audio with the video. - `duration` (integer) — 2–30. The number of seconds of duration for the output video. - `ratio` (string) — one of `832:480`, `720:544`, `624:624`, `544:720`, `480:832`, `1280:720`, `1104:832`, `960:960`, `832:1104`, `720:1280`, `1920:1080`, `1648:1248`, `1440:1440`, `1248:1648`, `1080:1920`, `auto_480p`, `auto_720p`, `auto_1080p`. The resolution of the output video, as `:`. Keyframe image-to-video requests must use `auto_480p`, `auto_720p`, or `auto_1080p` because their aspect ratio follows the first frame. - `referenceVideos` (array of object) — max 5 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 5 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `wan3_prime` #### POST /v1/image_to_video — model `h3_max` - `promptImage` (string or array of object, required) — An image to use as the first frame, or an array with a first frame and optionally a last frame. A last frame requires a first frame. Each image must be at least 256 pixels on both sides. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `position` (string, required) — one of `first`, `last`. The position of the image in the output video. "first" will use the image as the first frame of the video, "last" will use the image as the last frame of the video. - `promptText` (string, required) — max length 6000. A non-empty text prompt describing what should appear in the output. - `resolution` (string) — one of `480p`, `768p`. The output resolution. MiniMax H3 Max supports 480p and 768p. - `promptExpansionMode` (string) — one of `disabled`, `balanced`, `quality`. How the model rewrites the prompt before generating. disabled keeps the prompt as written. balanced (the default) does a short rewrite. quality spends extra time rewriting for a stronger result. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Identical results also need promptExpansionMode set to disabled; balanced and quality rewrite the prompt and will not repeat. - `duration` (integer) — 5–15. The number of seconds of duration for the output video. - `model` (string, required) — one of `h3_max` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/text_to_video Text to video This endpoint will start a new task to generate a video from a text prompt. Request body: one of 15 shapes, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/text_to_video — model `gen4.5` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `ratio` (string, required) — one of `1280:720`, `720:1280`. The resolution of the output video. - `duration` (integer, required) — 2–10. The number of seconds of duration for the output video. Must be an integer from 2 to 10. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `outputFormat` (string) — one of `mp4`, `prores`, `png_sequence`, `hdr10`, `hlg`, `sdr_rec709_10bit`, `hdr_pq_12bit_master`, `hdr_prores`, `hdr_png_sequence`, `hdr_exr_sequence`, `hdr_exr_acescg_sequence_1_3`, `hdr_exr_acescg_sequence_2_0`. The container/encoding of the output. `mp4` (default) returns an H.264 .mp4. `prores` returns a ProRes .mov. `png_sequence` returns a .zip of PNG frames (plus a separate .wav artifact when the output has audio). `hdr10`… - `proresProfile` (string) — one of `422`, `4444`, `422 Proxy`, `422 LT`, `422 HQ`, `4444 XQ`. The ProRes profile to use. Only valid when `outputFormat` is `prores` or `hdr_prores`. For `prores`, any profile is accepted and the default is `4444`. For `hdr_prores`, only `422`, `422 HQ` and `4444` are available and… - `model` (string, required) — one of `gen4.5` #### POST /v1/text_to_video — model `veo3.1` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `ratio` (string, required) — one of `1280:720`, `720:1280`, `1080:1920`, `1920:1080`. The resolution of the output video. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Audio inclusion affects pricing. - `negativePrompt` (string) — max length 1000. Text describing what should not appear in the output video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (number) — one of `4`, `6`, `8`. The number of seconds of duration for the output video. - `model` (string, required) — one of `veo3.1` #### POST /v1/text_to_video — model `veo3.1_fast` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `ratio` (string, required) — one of `1280:720`, `720:1280`, `1080:1920`, `1920:1080`. The resolution of the output video. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Audio inclusion affects pricing. - `negativePrompt` (string) — max length 1000. Text describing what should not appear in the output video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (number) — one of `4`, `6`, `8`. The number of seconds of duration for the output video. - `model` (string, required) — one of `veo3.1_fast` #### POST /v1/text_to_video — model `hailuo3` - `promptText` (string, required) — max length 6000. A non-empty text prompt describing what should appear in the output. - `resolution` (string) — one of `768p`, `2k`, `768P`, `2K`. The output resolution. Hailuo 3.0 supports 768p and 2k. - `duration` (integer) — 5–15. The number of seconds of duration for the output video. - `ratio` (string) — one of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. The aspect ratio of the output video. Use adaptive only when image or video references are provided; text-only requests require a concrete ratio. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `hailuo3` #### POST /v1/text_to_video — model `happyhorse_1_0` - `promptText` (string, required) — max length 2500. A non-empty string up to 2500 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `duration` (integer) — 3–15. The number of seconds of duration for the output video. - `ratio` (string) — one of `1280:720`, `720:1280`, `960:960`, `1108:832`, `832:1108`, `1920:1080`, `1080:1920`, `1440:1440`, `1662:1248`, `1248:1662`. The resolution of the output video. - `model` (string, required) — one of `happyhorse_1_0` #### POST /v1/text_to_video — model `seedance2` - `promptText` (string, required) — max length 3500. A non-empty text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`, `2206:946`, `1920:1080`, `1664:1248`, `1440:1440`, `1248:1664`, `1080:1920`, `3840:1646`, `3840:2160`, `3840:2880`, `3840:3840`, `2880:3840`, `2160:3840`. The resolution of the output video. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2` #### POST /v1/text_to_video — model `seedance2_fast` - `promptText` (string, required) — max length 3500. A non-empty text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`. The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_fast` #### POST /v1/text_to_video — model `seedance2_mini` - `promptText` (string, required) — max length 3500. A non-empty text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`. The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_mini` #### POST /v1/text_to_video — model `gemini_omni_flash` - `promptText` (string, required) — max length 4000. A non-empty text prompt describing the video to generate. - `ratio` (string) — one of `1280:720`, `720:1280`. The aspect ratio of the output video: `1280:720` (landscape) or `720:1280` (portrait). - `duration` (integer) — 3–10. The duration of the output video in seconds, as a whole number from 3 to 10. - `model` (string, required) — one of `gemini_omni_flash` #### POST /v1/text_to_video — model `seedance2_5` - `promptText` (string) — max length 15000. An optional text prompt up to 15000 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `854:480`, `752:560`, `640:640`, `560:752`, `480:854`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`, `2206:946`, `1920:1080`, `1664:1248`, `1440:1440`, `1248:1664`, `1080:1920`. The resolution of the output video. Seedance 2.5 supports 480p, 720p, and 1080p. - `references` (array of object) — max 30 items. An optional array of image references (up to 30). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 10 items. An optional array of video references. The combined duration across all video references must not exceed 30 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 10 items. An optional array of audio references. The total combined duration must be less than 30 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_5` #### POST /v1/text_to_video — model `grok_imagine_1_5` - `promptText` (string, required) — max length 2500. A non-empty text prompt describing what should appear in the output. - `resolution` (string) — one of `480p`, `720p`, `1080p`. The output resolution. Requests with image references are capped at 720p. - `duration` (integer) — 1–15. The number of seconds of duration for the output video. - `ratio` (string) — one of `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`. The aspect ratio of the output video. - `references` (array of object) — max 7 items. An optional array of image references. Referenced images can be addressed in the prompt as [Image 1], [Image 2], and so on. See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. Audio references require at least one image reference, and each clip must be between 3 and 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `grok_imagine_1_5` #### POST /v1/text_to_video — model `wan3` - `promptText` (string, required) — max length 20000. A non-empty text prompt describing what should appear in the output. - `audio` (boolean) — Whether to generate audio with the video. - `duration` (integer) — 2–30. The number of seconds of duration for the output video. - `ratio` (string) — one of `832:480`, `720:544`, `624:624`, `544:720`, `480:832`, `1280:720`, `1104:832`, `960:960`, `832:1104`, `720:1280`, `1920:1080`, `1648:1248`, `1440:1440`, `1248:1648`, `1080:1920`, `auto_480p`, `auto_720p`, `auto_1080p`. The resolution of the output video, as `:`. Keyframe image-to-video requests must use `auto_480p`, `auto_720p`, or `auto_1080p` because their aspect ratio follows the first frame. - `references` (array of object) — max 10 items. An optional array of image references (up to 10). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 5 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 5 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `wan3` #### POST /v1/text_to_video — model `gemini_omni_flash_1.1` - `promptText` (string, required) — max length 4000. A non-empty text prompt describing the video to generate. - `ratio` (string) — one of `640:360`, `360:640`, `1280:720`, `720:1280`, `1920:1080`, `1080:1920`, `3840:2160`, `2160:3840`. The resolution and aspect ratio of the output video. - `duration` (string or integer) — The duration of the output video in seconds. Use "auto" to let the model choose a duration. Numeric durations must be between 3 and 10 seconds. - `references` (array of object) — max 5 items - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `model` (string, required) — one of `gemini_omni_flash_1.1` #### POST /v1/text_to_video — model `wan3_prime` - `promptText` (string, required) — max length 20000. A non-empty text prompt describing what should appear in the output. - `audio` (boolean) — Whether to generate audio with the video. - `duration` (integer) — 2–30. The number of seconds of duration for the output video. - `ratio` (string) — one of `832:480`, `720:544`, `624:624`, `544:720`, `480:832`, `1280:720`, `1104:832`, `960:960`, `832:1104`, `720:1280`, `1920:1080`, `1648:1248`, `1440:1440`, `1248:1648`, `1080:1920`, `auto_480p`, `auto_720p`, `auto_1080p`. The resolution of the output video, as `:`. Keyframe image-to-video requests must use `auto_480p`, `auto_720p`, or `auto_1080p` because their aspect ratio follows the first frame. - `references` (array of object) — max 10 items. An optional array of image references (up to 10). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 5 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 5 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `wan3_prime` #### POST /v1/text_to_video — model `h3_max` - `promptText` (string, required) — max length 6000. A non-empty text prompt describing what should appear in the output. - `resolution` (string) — one of `480p`, `768p`. The output resolution. MiniMax H3 Max supports 480p and 768p. - `promptExpansionMode` (string) — one of `disabled`, `balanced`, `quality`. How the model rewrites the prompt before generating. disabled keeps the prompt as written. balanced (the default) does a short rewrite. quality spends extra time rewriting for a stronger result. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Identical results also need promptExpansionMode set to disabled; balanced and quality rewrite the prompt and will not repeat. - `duration` (integer) — 5–15. The number of seconds of duration for the output video. - `model` (string, required) — one of `h3_max` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/video_to_video Video to video This endpoint will start a new task to generate a video from a video. Request body: one of 8 shapes, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/video_to_video — model `aleph2` - `promptText` (string) — max length 1000. A non-empty and optional string describing what should appear in the output. - `keyframes` (array of object) — min 1 items; max 5 items. Timed guidance images placed at specific points in the input video. Up to 5 keyframes. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `seconds` (number, required) — 0–30. Absolute timestamp in seconds from the start of the input video when this guidance image should apply. - `range` (object) — Optional edit window. When set, the edit applies only to this time range and the keyframe timestamp must fall within it. All keyframes must either set a range or none may. - `start_seconds` (integer, required) — minimum 0. Start of the edit window in whole seconds from the start of the input video. - `end_seconds` (integer, required) — greater than 0. End of the edit window (exclusive) in whole seconds from the start of the input video. - `videoUri` (string, required) — The input video to edit. Must be 30 seconds or shorter. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `ratio` (string) - `targetAspectRatio` (string) — one of `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `21:9`. Target aspect ratio for expand/outpaint. Letterboxes the input video and keyframes before generation. - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `outputFormat` (string) — one of `mp4`, `prores`, `png_sequence`, `sdr_rec709_10bit`. The container/encoding of the output. `mp4` (default) returns an H.264 .mp4. `prores` returns a ProRes .mov. `png_sequence` returns a .zip of PNG frames. `sdr_rec709_10bit` returns a 10-bit Rec.709 HEVC .mp4 for SDR gra… - `proresProfile` (string) — one of `422`, `4444`, `422 Proxy`, `422 LT`, `422 HQ`, `4444 XQ`. The ProRes profile to use. Only valid when `outputFormat` is `prores`. Defaults to `4444`. Note: generated content contains no transparency — the alpha channel in `4444` / `4444 XQ` outputs is present but fully opaque;… - `model` (string, required) — one of `aleph2` #### POST /v1/video_to_video — model `hailuo3` - `promptVideo` (string, required) — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds. - `promptText` (string, required) — max length 6000. A non-empty text prompt describing what should appear in the output. - `resolution` (string) — one of `768p`, `2k`, `768P`, `2K`. The output resolution. Hailuo 3.0 supports 768p and 2k. - `duration` (integer) — 5–15. The number of seconds of duration for the output video. - `ratio` (string) — one of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. The aspect ratio of the output video. Use adaptive only when image or video references are provided; text-only requests require a concrete ratio. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 2 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `hailuo3` #### POST /v1/video_to_video — model `seedance2` - `promptVideo` (string, required) — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds. - `promptText` (string) — max length 3500. An optional text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`, `2206:946`, `1920:1080`, `1664:1248`, `1440:1440`, `1248:1664`, `1080:1920`, `3840:1646`, `3840:2160`, `3840:2880`, `3840:3840`, `2880:3840`, `2160:3840`. The resolution of the output video. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2` #### POST /v1/video_to_video — model `seedance2_fast` - `promptVideo` (string, required) — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds. - `promptText` (string) — max length 3500. An optional text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`. The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_fast` #### POST /v1/video_to_video — model `seedance2_mini` - `promptVideo` (string, required) — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds. - `promptText` (string) — max length 3500. An optional text prompt up to 3500 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. - `ratio` (string) — one of `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`. The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only. - `references` (array of object) — max 9 items. An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 3 items. An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 3 items. An optional array of audio references. The total combined duration must not exceed 15 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_mini` #### POST /v1/video_to_video — model `gemini_omni_flash` - `videoUri` (string, required) — The input video to edit. The output is 720p, with the orientation (landscape or portrait) matched to the input. The output duration matches the input, up to 10 seconds. The input must be at most 10 seconds. - `promptText` (string, required) — max length 4000. A non-empty instruction describing the edit to apply. - `references` (array of object) — max 5 items. An optional array of image references to guide the edit. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `model` (string, required) — one of `gemini_omni_flash` #### POST /v1/video_to_video — model `seedance2_5` - `promptVideo` (string, required) — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 30 seconds. - `promptText` (string) — max length 15000. An optional text prompt up to 15000 characters describing what should appear in the output. - `audio` (boolean) — default `true`. Whether to generate audio for the video. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `mode` (string) — one of `reference`, `extend`, `edit`; default `reference`. How the input video is used. `reference` (the default) generates a new video conditioned on the input video and accepts `duration` and `ratio`. `extend` continues the input video, requires `promptText`, and matches the… - `duration` (integer or string) — Seconds of video to generate, or `auto` to let the model choose. `auto` is billed at the variant maximum up front; unused credits are refunded after the generation finishes. Defaults to 5. - `ratio` (string) — one of `992:432`, `854:480`, `752:560`, `640:640`, `560:752`, `480:854`, `1470:630`, `1280:720`, `1112:834`, `960:960`, `834:1112`, `720:1280`, `2206:946`, `1920:1080`, `1664:1248`, `1440:1440`, `1248:1664`, `1080:1920`. The resolution of the output video. Seedance 2.5 supports 480p, 720p, and 1080p. - `references` (array of object) — max 30 items. An optional array of image references (up to 30). See [our docs](/assets/inputs#images) on image inputs for more information. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `referenceVideos` (array of object) — max 9 items. An optional array of video references. The combined duration across all video references must not exceed 30 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information. - `type` (string, required) — one of `video` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `referenceAudio` (array of object) — max 10 items. An optional array of audio references. The total combined duration must be less than 30 seconds. - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `seedance2_5` #### POST /v1/video_to_video — model `gemini_omni_flash_1.1` - `videoUri` (string, required) — The input video to use as a reference, extend, or edit. Reference and edited videos may be up to 10 seconds and extended videos up to 30 seconds. - `promptText` (string, required) — max length 4000. A non-empty prompt describing the output or extension. - `mode` (string) — one of `reference`, `extend`, `edit`; default `reference`. How the input video is used. `reference` generates a new video guided by the input, `extend` continues it, and `edit` transforms it according to the prompt. - `ratio` (string) — one of `640:360`, `360:640`, `1280:720`, `720:1280`, `1920:1080`, `1080:1920`, `3840:2160`, `2160:3840`. The resolution and aspect ratio of the output video. - `duration` (string or integer) — The duration in seconds. In reference mode, this is the output video length. In extend mode, this is the amount of footage added to the input video. Use "auto" to let the model choose a duration. - `references` (array of object) — max 5 items. An optional array of image references to guide the output. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `model` (string, required) — one of `gemini_omni_flash_1.1` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/text_to_image Text/Image to Image This endpoint will start a new task to generate images from text and/or image(s) Request body: one of 10 shapes, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/text_to_image — model `gen4_image_turbo` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `ratio` (string, required) — one of `1024:1024`, `1080:1080`, `1168:880`, `1360:768`, `1440:1080`, `1080:1440`, `1808:768`, `1920:1080`, `1080:1920`, `2112:912`, `1280:720`, `720:1280`, `720:720`, `960:720`, `720:960`, `1680:720`. The resolution of the output image. - `referenceImages` (array of object, required) — min 1 items; max 3 items. An array of one to three images to be used as references for the generated image output. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `tag` (string) — max length 16. A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation). - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `model` (string, required) — one of `gen4_image_turbo` #### POST /v1/text_to_image — model `gen4_image` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `ratio` (string, required) — one of `1024:1024`, `1080:1080`, `1168:880`, `1360:768`, `1440:1080`, `1080:1440`, `1808:768`, `1920:1080`, `1080:1920`, `2112:912`, `1280:720`, `720:1280`, `720:720`, `960:720`, `720:960`, `1680:720`. The resolution of the output image. - `referenceImages` (array of object) — max 3 items. An array of up to three images to be used as references for the generated image output. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `tag` (string) — max length 16. A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation). - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `model` (string, required) — one of `gen4_image` #### POST /v1/text_to_image — model `gpt_image_2` - `promptText` (string, required) — max length 32000. A non-empty string up to 32,000 characters describing the desired image. - `ratio` (string, required) — one of `2048:880`, `1920:1088`, `1920:1280`, `1920:1440`, `1920:1536`, `1920:1920`, `1536:1920`, `1440:1920`, `1280:1920`, `1088:1920`, `2912:1248`, `2560:1440`, `2560:1712`, `2560:1920`, `2560:2048`, `2560:2560`, `2048:2560`, `1920:2560`, `1712:2560`, `1440:2560`, `3840:1648`, `3840:2160`, `3504:2336`, `3264:2448`, `3200:2560`, `2880:2880`, `2560:3200`, `2448:3264`, `2336:3504`, `2160:3840`, `auto`. The resolution of the output image, expressed as `:`. Use `auto` to let the model choose. - `quality` (string) — one of `low`, `medium`, `high`, `auto`. Rendering quality. Higher qualities consume more credits. Defaults to `high`. - `background` (string) — one of `transparent`, `opaque`, `auto`. Background treatment. Defaults to `auto`, which lets the model pick. Use `transparent` to generate a PNG with an alpha-channel background. - `referenceImages` (array of object) — max 16 items. An array of up to 16 images to be used as references for the generated image output. No two images may share the same tag. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `tag` (string) — max length 16. A tag to identify the reference image. This may be used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation… - `outputCount` (integer) — 1–10. The number of images to generate (1-10). Increasing this number will affect the number of credits consumed by the generation. - `model` (string, required) — one of `gpt_image_2` #### POST /v1/text_to_image — model `gemini_image3_pro` - `promptText` (string, required) — max length 5500. This should describe in detail what should appear in the output. - `ratio` (string, required) — one of `1344:768`, `768:1344`, `1024:1024`, `1184:864`, `864:1184`, `1536:672`, `832:1248`, `1248:832`, `896:1152`, `1152:896`, `2048:2048`, `1696:2528`, `2528:1696`, `1792:2400`, `2400:1792`, `1856:2304`, `2304:1856`, `1536:2752`, `2752:1536`, `3168:1344`, `4096:4096`, `3392:5056`, `5056:3392`, `3584:4800`, `4800:3584`, `3712:4608`, `4608:3712`, `3072:5504`, `5504:3072`, `6336:2688`. The resolution of the output image. - `referenceImages` (array of object) — max 14 items. An array of up to 14 images to be used as references for the generated image output. Up to five of those images can pass `subject: "human"` to maintain character consistency, and up to nine of those images can pass `sub… - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `tag` (string) — max length 16. A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation). - `subject` (string) — one of `object`, `human`; default `object`. Whether this is a reference of a human subject (for character consistency) or an object that appears in the output. - `outputCount` (number) — one of `1`, `4`. The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. Up to four images can be generated at once. - `model` (string, required) — one of `gemini_image3_pro` #### POST /v1/text_to_image — model `gemini_image3.1_flash` - `promptText` (string, required) — max length 5500. This should describe in detail what should appear in the output. - `ratio` (string, required) — one of `512:512`, `416:624`, `624:416`, `432:592`, `592:432`, `448:576`, `576:448`, `384:672`, `672:384`, `768:336`, `256:1024`, `1024:256`, `176:1408`, `1408:176`, `1024:1024`, `832:1248`, `1248:832`, `864:1184`, `1184:864`, `896:1152`, `1152:896`, `768:1344`, `1344:768`, `1536:672`, `512:2048`, `2048:512`, `352:2816`, `2816:352`, `2048:2048`, `1696:2528`, `2528:1696`, `1792:2400`, `2400:1792`, `1856:2304`, `2304:1856`, `1536:2752`, `2752:1536`, `3168:1344`, `1024:4096`, `4096:1024`, … (56 total). The resolution of the output image. - `referenceImages` (array of object) — max 14 items. An array of up to 14 images to be used as references for the generated image output. Up to five of those images can pass `subject: "human"` to maintain character consistency, and up to nine of those images can pass `sub… - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `tag` (string) — max length 16. A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation). - `subject` (string) — one of `object`, `human`; default `object`. Whether this is a reference of a human subject (for character consistency) or an object that appears in the output. - `outputCount` (number) — one of `1`, `4`. The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. Up to four images can be generated at once. - `model` (string, required) — one of `gemini_image3.1_flash` #### POST /v1/text_to_image — model `muse_image` - `promptText` (string, required) — max length 4000. A non-empty text prompt describing what should appear in the output image. - `ratio` (string, required) — one of `2352:1008`, `2016:1152`, `1920:1280`, `1792:1344`, `1600:1600`, `1344:1792`, `1280:1920`, `1152:2016`, `auto`. The resolution of the output image, expressed as `:`. Use `auto` to let the model choose the framing from the prompt. - `outputFormat` (string) — one of `webp`, `png`, `jpeg`. The file format of the output image. Defaults to png. - `referenceImages` (array of object) — max 10 items. Up to 10 images to guide the generation. When provided, the model edits and combines them as your prompt describes instead of generating from the prompt alone. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `outputCount` (integer) — 1–10. The number of images to generate. Each image costs 1 credit. - `model` (string, required) — one of `muse_image` #### POST /v1/text_to_image — model `seedream5_pro` - `promptText` (string, required) — max length 4000. A non-empty string up to 4,000 characters describing the desired image. - `ratio` (string, required) — one of `1024:1024`, `1184:896`, `896:1184`, `1376:768`, `768:1376`, `1296:864`, `864:1296`, `2048:2048`, `2304:1728`, `1728:2304`, `2720:1530`, `1530:2720`, `2496:1664`, `1664:2496`, `auto_1k`, `auto_2k`. The resolution of the output image, expressed as `:`. Use `auto_1k` or `auto_2k` to let the model pick aspect ratio at a fixed resolution tier. - `outputFormat` (string) — one of `png`, `jpeg`. The file format of the output image. Defaults to png. - `referenceImages` (array of object) — max 10 items. An array of reference images for multi-image fusion and interactive editing. Reference by upload order in prompt text (Figure 1, Figure 2, etc.). - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `outputCount` (integer) — 1–4. The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. - `grounding` (boolean) — When true, enable live web search so the model can use current brand, trend, or event context. Default false for deterministic output. - `model` (string, required) — one of `seedream5_pro` #### POST /v1/text_to_image — model `seedream5_lite` - `promptText` (string, required) — max length 4000. A non-empty string up to 4,000 characters describing the desired image. - `ratio` (string, required) — The resolution of the output image, expressed as `:`. Also accepts freeform sizes whose width*height is between 3686400 and 16777216 pixels. - `outputFormat` (string) — one of `png`, `jpeg`. The file format of the output image. Defaults to png. - `referenceImages` (array of object) — max 14 items. An array of reference images for multi-image fusion and interactive editing. Reference by upload order in prompt text (Figure 1, Figure 2, etc.). - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `outputCount` (integer) — 1–4. The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. - `grounding` (boolean) — When true, enable live web search so the model can use current brand, trend, or event context. Default false for deterministic output. - `model` (string, required) — one of `seedream5_lite` #### POST /v1/text_to_image — model `grok_imagine_image_2` - `promptText` (string, required) — max length 2500. A non-empty text prompt describing what should appear in the output image. - `ratio` (string, required) — one of `1024:1024`, `1280:720`, `720:1280`, `1152:864`, `864:1152`, `1248:832`, `832:1248`, `1248:576`, `576:1248`, `1280:576`, `576:1280`, `1408:704`, `704:1408`, `2048:2048`, `2816:1584`, `1584:2816`, `2368:1776`, `1776:2368`, `2496:1664`, `1664:2496`, `2912:1344`, `1344:2912`, `3200:1440`, `1440:3200`, `2912:1456`, `1456:2912`, `auto_1k`, `auto_2k`. The resolution of the output image, expressed as `:`. 2K ratios cost 2 additional credits per image. Use `auto_1k` or `auto_2k` to pick a resolution tier and let the model choose the framing from the prom… - `quality` (string) — one of `low`, `medium`. How much rendering effort the model spends on the output. Defaults to `medium`; `low` is faster and costs 2 fewer credits per image. - `edit` (boolean) — When true with exactly one reference image, edit that image directly instead of using it as a loose visual reference. With several reference images the prompt describes how they should be edited or combined. Requires at… - `referenceImages` (array of object) — max 3 items. Up to 3 images to guide the generation. Reference them from `promptText` to describe how each should be used. Each adds 1 credit to the generation. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `outputCount` (integer) — 1–4. The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. - `model` (string, required) — one of `grok_imagine_image_2` #### POST /v1/text_to_image — model `gemini_2.5_flash` - `promptText` (string, required) — max length 5500. This should describe in detail what should appear in the output. - `ratio` (string, required) — one of `1344:768`, `768:1344`, `1024:1024`, `1184:864`, `864:1184`, `1536:672`, `832:1248`, `1248:832`, `896:1152`, `1152:896`. The resolution of the output image. - `referenceImages` (array of object) — max 3 items. An array of up to three images to be used as references for the generated image output. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `tag` (string) — max length 16. A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation). - `model` (string, required) — one of `gemini_2.5_flash` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/image_upscale Image upscale Upscale an image with Magnific precision upscaling. Each input dimension must be between 300px and 8000px. Output width and height are the input dimensions multiplied by `scaleFactor` (default 2). Output width times hei… Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/image_upscale — model `magnific_precision_upscaler_v2` - `imageUri` (string, required) — Image to upscale. See [image inputs](/assets/inputs#images) for URL, upload, and file size limits. - `scaleFactor` (number) — one of `2`, `4`, `8`, `16`. Multiplies each input dimension to produce output width and height. Defaults to 2. - `sharpen` (integer) — 0–100. Sharpness intensity from 0 (none) to 100. - `smartGrain` (integer) — 0–100. Grain and texture enhancement from 0 to 100. - `ultraDetail` (integer) — 0–100. Fine detail enhancement from 0 to 100. - `flavor` (string) — one of `sublime`, `photo`, `photo_denoiser`. Optimization preset: `sublime` (illustration), `photo` (photographic), or `photo_denoiser` (noisy photos). - `model` (string, required) — one of `magnific_precision_upscaler_v2` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/video_upscale Video upscale This endpoint starts a task to upscale a video. Set `model` to choose the upscaler. Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/video_upscale — model `magnific_video_upscaler_creative` - `videoUri` (string, required) — Video to upscale. See [video inputs](/assets/inputs#videos) for URL, upload, and file size limits. Maximum duration is 30 seconds. - `resolution` (string) — one of `720p`, `1k`, `2k`, `4k`. Target output resolution from 720p to 4k. Defaults to `2k`. - `creativity` (integer) — 0–100. How much AI-generated detail to add during upscaling, from 0 (faithful) to 100. - `sharpen` (integer) — 0–100. Sharpness intensity from 0 (none) to 100. - `smartGrain` (integer) — 0–100. Grain and texture enhancement from 0 to 100. - `flavor` (string) — one of `vivid`, `natural`. Processing style: `vivid` for enhanced color and detail, `natural` for faithful reproduction. - `fpsBoost` (boolean) — Whether to increase the output frame rate. - `model` (string, required) — one of `magnific_video_upscaler_creative` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/video_to_hdr Video to HDR This endpoint starts a task to upconvert an SDR video to true HDR with Ruby, Runway's HDR grading model. The output keeps the source's own pixels — luma and color are extended into the HDR range, nothing is re-synthesiz… Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/video_to_hdr — model `ruby` - `videoUri` (string, required) — The SDR input video to upconvert. Must be 30 seconds or shorter. - `outputFormat` (string) — one of `hdr10`, `hlg`, `hdr_prores`, `hdr_exr_sequence`, `hdr_exr_acescg_sequence_1_3`, `hdr_exr_acescg_sequence_2_0`. The HDR delivery profile of the output. `hdr10` (default) returns an HEVC Main 10, BT.2020 + PQ .mp4; `hlg` returns an HEVC Main 10, BT.2020 + HLG .mp4; `hdr_prores` returns a BT.2020 + PQ ProRes .mov editorial mezzanin… - `proresProfile` (string) — one of `422`, `4444`, `422 HQ`. The ProRes tier of the `hdr_prores` mezzanine. Only valid when `outputFormat` is `hdr_prores`. Defaults to `422 HQ`. - `model` (string, required) — one of `ruby` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/character_performance Control a character This endpoint will start a new task to control a character's facial expressions and body movements using a reference video. Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/character_performance — model `act_two` - `seed` (integer) — 0–4294967295. If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar resu… - `character` (object, required) — The character to control. You can either provide a video or an image. A visually recognizable face must be visible and stay within the frame. - `type` (string, required) — one of `image` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `reference` (object, required) — The reference video containing the performance to apply to the character. - `type` (string, required) — one of `video` - `uri` (string, required) — A video of a person performing in the manner that you would like your character to perform. The video must be between 3 and 30 seconds in duration. See [our docs](/assets/inputs#videos) on video inputs for more informat… - `bodyControl` (boolean) — A boolean indicating whether to enable body control. When enabled, non-facial movements and gestures will be applied to the character in addition to facial expressions. - `expressionIntensity` (integer) — 1–5; default `3`. An integer between 1 and 5 (inclusive). A larger value increases the intensity of the character's expression. - `ratio` (string) — one of `1280:720`, `720:1280`, `960:960`, `1104:832`, `832:1104`, `1584:672`. The resolution of the output video. - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. - `model` (string, required) — one of `act_two` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/sound_effect Generate sound effects This endpoint will start a new task to generate sound effects from a text description. Request body: one of 2 shapes, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/sound_effect — model `seed_audio` - `promptText` (string, required) — max length 2048. A non-empty text prompt. For text-to-speech, the words to speak. For text-to-audio, a scene description that can include voice direction, dialogue, music, and sound effects. - `referenceAudios` (array of string) — max 3 items. Up to three reference audio clips. When provided, reference them in promptText as @Audio1, @Audio2, and @Audio3 in order. - `speechRate` (integer) — -50–100. Relative speech speed. Negative is slower, positive is faster; 0 is normal. - `loudnessRate` (integer) — -50–100. Relative output loudness. Negative is quieter, positive is louder; 0 is normal. - `pitchRate` (integer) — -12–12. Pitch shift in semitones. Negative lowers, positive raises; 0 is unchanged. - `sampleRate` (number) — one of `8000`, `16000`, `24000`, `32000`, `44100`, `48000`. Output sample rate in Hz. - `outputFormat` (string) — one of `wav`, `mp3`, `ogg_opus`. Output audio container/format. - `model` (string, required) — one of `seed_audio` #### POST /v1/sound_effect — model `eleven_text_to_sound_v2` - `promptText` (string, required) — max length 3000. A text description of the sound effect to generate. - `duration` (number) — 0.5–30. The duration of the sound effect in seconds, between 0.5 and 30 seconds. If not provided, the duration will be determined automatically based on the text description. - `loop` (boolean) — default `false`. Whether the output sound effect should be designed to loop seamlessly. - `model` (string, required) — one of `eleven_text_to_sound_v2` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/speech_to_speech Speech to speech This endpoint will start a new task to convert speech from one voice to another in audio or video. Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/speech_to_speech — model `eleven_multilingual_sts_v2` - `removeBackgroundNoise` (boolean) — Whether to remove background noise from the generated speech. - `media` (object, required) - `type` (string, required) — one of `audio` - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `voice` (object, required) — The voice to use for the generated speech. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — one of `Maya`, `Arjun`, `Serene`, `Bernard`, `Billy`, `Mark`, `Clint`, `Mabel`, `Chad`, `Leslie`, `Eleanor`, `Elias`, `Elliot`, `Grungle`, `Brodie`, `Sandra`, `Kirk`, `Kylie`, `Lara`, `Lisa`, `Malachi`, `Marlene`, `Martin`, `Miriam`, `Monster`, `Paula`, `Pip`, `Rusty`, `Ragnar`, `Xylar`, `Maggie`, `Jack`, `Katie`, `Noah`, `James`, `Rina`, `Ella`, `Mariah`, `Frank`, `Claudia`, … (49 total). The preset voice ID to use for the generated speech. - `model` (string, required) — one of `eleven_multilingual_sts_v2` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/text_to_speech Text to speech This endpoint will start a new task to generate speech from text. Request body: one of 3 shapes, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/text_to_speech — model `seed_audio` - `promptText` (string, required) — max length 2048. A non-empty text prompt. For text-to-speech, the words to speak. For text-to-audio, a scene description that can include voice direction, dialogue, music, and sound effects. - `voice` (object) — The voice to use for text-to-speech generation. If omitted, a default voice is used. - `type` (string, required) — one of `reference-audio` - `audioUri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `speechRate` (integer) — -50–100. Relative speech speed. Negative is slower, positive is faster; 0 is normal. - `loudnessRate` (integer) — -50–100. Relative output loudness. Negative is quieter, positive is louder; 0 is normal. - `pitchRate` (integer) — -12–12. Pitch shift in semitones. Negative lowers, positive raises; 0 is unchanged. - `sampleRate` (number) — one of `8000`, `16000`, `24000`, `32000`, `44100`, `48000`. Output sample rate in Hz. - `outputFormat` (string) — one of `wav`, `mp3`, `ogg_opus`. Output audio container/format. - `model` (string, required) — one of `seed_audio` #### POST /v1/text_to_speech — model `eleven_multilingual_v2` - `promptText` (string, required) — max length 1000. A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output. - `voice` (object, required) — The voice to use for the generated speech. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — one of `Maya`, `Arjun`, `Serene`, `Bernard`, `Billy`, `Mark`, `Clint`, `Mabel`, `Chad`, `Leslie`, `Eleanor`, `Elias`, `Elliot`, `Grungle`, `Brodie`, `Sandra`, `Kirk`, `Kylie`, `Lara`, `Lisa`, `Malachi`, `Marlene`, `Martin`, `Miriam`, `Monster`, `Paula`, `Pip`, `Rusty`, `Ragnar`, `Xylar`, `Maggie`, `Jack`, `Katie`, `Noah`, `James`, `Rina`, `Ella`, `Mariah`, `Frank`, `Claudia`, … (49 total). The preset voice ID to use for the generated speech. - `model` (string, required) — one of `eleven_multilingual_v2` #### POST /v1/text_to_speech — model `eleven_v3` - `promptText` (string, required) — max length 5000. The text to convert to speech. You can include expressive audio tags like [laughs] or [whispers] in the script. - `voice` (object, required) — The voice to use for the generated speech. - `type` (string, required) — one of `runway-preset` - `presetId` (string, required) — one of `Maya`, `Arjun`, `Serene`, `Bernard`, `Billy`, `Mark`, `Clint`, `Mabel`, `Chad`, `Leslie`, `Eleanor`, `Elias`, `Elliot`, `Grungle`, `Brodie`, `Sandra`, `Kirk`, `Kylie`, `Lara`, `Lisa`, `Malachi`, `Marlene`, `Martin`, `Miriam`, `Monster`, `Paula`, `Pip`, `Rusty`, `Ragnar`, `Xylar`, `Maggie`, `Jack`, `Katie`, `Noah`, `James`, `Rina`, `Ella`, `Mariah`, `Frank`, `Claudia`, … (49 total). The preset voice ID to use for the generated speech. - `stability` (number) — 0–1. Voice stability (0–1). Lower values allow broader emotional range; higher values are steadier. - `similarityBoost` (number) — 0–1. How closely the output tracks the original speaker (0–1). Maps to ElevenLabs similarity_boost. - `style` (number) — 0–1. Style exaggeration (0–1). Higher values amplify the speaker style. - `speed` (number) — 0.7–1.2. Speech speed multiplier (0.7–1.2). 1.0 is default; values below slow down and above speed up. - `useSpeakerBoost` (boolean) — Boost similarity to the original speaker at a small latency cost. - `languageCode` (string) — max length 5. ISO 639-1 language code to enforce pronunciation and normalization. - `applyTextNormalization` (string) — one of `auto`, `on`, `off`. Text normalization mode: 'auto', 'on', or 'off' (e.g. spelling out numbers). - `seed` (integer) — 0–4294967295. Optional seed for more deterministic output (0–4294967295). Not guaranteed. - `model` (string, required) — one of `eleven_v3` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/voice_dubbing Voice dubbing This endpoint will start a new task to dub audio content to a target language. Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/voice_dubbing — model `eleven_voice_dubbing` - `audioUri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `targetLang` (string, required) — one of `en`, `hi`, `pt`, `zh`, `es`, `fr`, `de`, `ja`, `ar`, `ru`, `ko`, `id`, `it`, `nl`, `tr`, `pl`, `sv`, `fil`, `ms`, `ro`, `uk`, `el`, `cs`, `da`, `fi`, `bg`, `hr`, `sk`, `ta`. The target language code to dub the audio to (e.g., "es" for Spanish, "fr" for French). - `disableVoiceCloning` (boolean) — Whether to disable voice cloning and use a generic voice instead. - `dropBackgroundAudio` (boolean) — Whether to remove background audio from the dubbed output. - `numSpeakers` (integer) — greater than 0. The number of speakers in the audio. If not provided, it will be detected automatically. - `model` (string, required) — one of `eleven_voice_dubbing` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/voice_isolation Voice isolation This endpoint will start a new task to isolate the voice from the background audio. Audio duration must be greater than 4.6 seconds and less than 3600 seconds. Request body: one of 1 shape, selected by `model`. Only the fields listed under a given `model` are valid. #### POST /v1/voice_isolation — model `eleven_voice_isolation` - `audioUri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `model` (string, required) — one of `eleven_voice_isolation` Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ## Model Router ### POST /v1/generate/video Routed video generation Start a video generation task using a saved Model Router config instead of naming a model. Request body: - `configId` (string, required) — The slug of a saved Model Router config to route this request with. - `dryRun` (boolean) — When true, run the full routing pipeline and return the decision and estimated cost without generating. No task is created, nothing is billed, and no asset is produced. - `input` (object, required) — Model-agnostic video generation input. Fields are optional; the router selects a model and maps these options to it. - `promptText` (string) — max length 20000. A text prompt describing the desired video. - `negativePrompt` (string) — max length 1000. A text description of what to avoid in the output. - `referenceImages` (array of object) — max 4 items. Optional image inputs. Each entry requires a `role`. At most one `first` and one `last` are allowed; multiple `reference` images are allowed. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `role` (string, required) — one of `first`, `last`, `reference`. How the image is used. `first` is the starting frame; `last` is an end frame; `reference` is additional image context. - `referenceVideos` (array of object) — max 2 items. Optional video inputs. Each entry requires a `role`. Use `source` for video-to-video; use `reference` for additional context videos (only models that support them remain eligible). At most one `source` is allowed. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `role` (string, required) — one of `source`, `reference`. How the video is used. `source` is the primary video-to-video input; `reference` is additional video context. - `referenceAudio` (array of object) — max 1 items. Optional audio inputs for the generation. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `keyframes` (array of object) — max 5 items. Timed guidance images for video restyle. Requires a source video; unsupported models are excluded. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `seconds` (number, required) — 0–30 - `range` (object) - `start_seconds` (integer, required) — minimum 0 - `end_seconds` (integer, required) — greater than 0 - `duration` (integer) — 2–30. Desired duration of the output video, in seconds. Unsupported values exclude models; with a source video, V2V duration support applies. - `aspectRatio` (string) — one of `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. Desired aspect ratio. Models that do not support the requested aspect are excluded. - `resolution` (string) — one of `480p`, `720p`, `1080p`, `4k`. Desired output resolution tier. Models that do not support the requested tier are excluded. - `audio` (boolean) — Whether to generate native audio with the video. When true, only models that output audio remain eligible; when false, silent models and models with an audio toggle remain eligible (always-on native-audio models are exc… - `seed` (integer) — 0–4294967295. A seed for reproducible generation. Random if omitted. - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. Response 200: - `dryRun` (boolean, required) — one of `false` - `id` (string, required) — format uuid. The ID of the created task. Poll GET /v1/tasks/:id for the result. - `routing` (object, required) — Metadata describing which model the router selected and why. - `model` (string, required) — The public name of the model the router selected. - `provider` (string, required) — The provider of the selected model. - `configId` (string, required) — The slug of the router config that was applied to this request. - `resolvedSettings` (object, required) — The resolved config settings the router used for this request. - `optimizeFor` (string, required) — one of `cost`, `latency`, `quality`. The single optimization preference the config selected, used as the soft weighting when scoring eligible models. - `priceCeiling` (number or null, required) — The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling. - `resolvedInput` (object, required) — Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options. - `duration` (number, required) — Duration in seconds used for routing display (request value or router default). - `ratio` (string, required) — Concrete output ratio derived from aspectRatio (e.g. "1280:720"), or the router default. - `resolution` (string, required) — Resolution tier from the request, or the router default when omitted. - `estimatedCost` (object, required) — Estimated cost, computed against current pricing. - `credits` (number, required) — Estimated cost of the generation in credits. - `capacityFallback` (object) — Present only when the config enables fallback.onCapacity and capacity affected this request. - `skipped` (array of string, required) — Eligible models that were considered for this request but not selected because this account is at its concurrency limit for them. - `allExhausted` (boolean, required) — True when every eligible model was at its concurrency limit, so the best-ranked model was used and the task will queue. Other responses: `400`, `404`, `429` ### POST /v1/generate/image Routed image generation Start an image generation task using a saved Model Router config instead of naming a model. Request body: - `configId` (string, required) — The slug of a saved Model Router config to route this request with. - `dryRun` (boolean) — When true, run the full routing pipeline and return the decision and estimated cost without generating. No task is created, nothing is billed, and no asset is produced. - `input` (object, required) — Model-agnostic image generation input. The router selects a model and maps these options to it. - `promptText` (string, required) — max length 32000. A text prompt describing the desired image. - `referenceImages` (array of object) — max 16 items. Optional reference images for models that support them. Tags are assigned per model when omitted. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `aspectRatio` (string) — one of `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `2:3`, `3:2`, `4:5`, `5:4`. Desired aspect ratio. Models that do not support the requested aspect are excluded. - `resolution` (string) — one of `1k`, `2k`, `4k`. Desired megapixel tier. Models that do not support the requested tier are excluded. - `outputCount` (integer) — 1–10. Number of images to generate (1-10). Models that cannot produce the exact count are excluded and cost scales with this value. - `seed` (integer) — 0–4294967295. A seed for reproducible generation. Only gen4_image and gen4_image_turbo accept this field. - `contentModeration` (object) — Settings that affect the behavior of the content moderation system. - `publicFigureThreshold` (string) — one of `auto`, `low`. When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures. Response 200: - `dryRun` (boolean, required) — one of `false` - `id` (string, required) — format uuid. The ID of the created task. Poll GET /v1/tasks/:id for the result. - `routing` (object, required) — Metadata describing which model the router selected and why. - `model` (string, required) — The public name of the model the router selected. - `provider` (string, required) — The provider of the selected model. - `configId` (string, required) — The slug of the router config that was applied to this request. - `resolvedSettings` (object, required) — The resolved config settings the router used for this request. - `optimizeFor` (string, required) — one of `cost`, `latency`, `quality`. The single optimization preference the config selected, used as the soft weighting when scoring eligible models. - `priceCeiling` (number or null, required) — The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling. - `resolvedInput` (object, required) — Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options. - `ratio` (string, required) — Concrete output ratio derived from aspectRatio and resolution for the selected model. - `aspectRatio` (string, required) — Aspect ratio used for routing display. - `resolution` (string, required) — Megapixel tier used for routing display. - `estimatedCost` (object, required) — Estimated cost, computed against current pricing. - `credits` (number, required) — Estimated cost of the generation in credits. - `capacityFallback` (object) — Present only when the config enables fallback.onCapacity and capacity affected this request. - `skipped` (array of string, required) — Eligible models that were considered for this request but not selected because this account is at its concurrency limit for them. - `allExhausted` (boolean, required) — True when every eligible model was at its concurrency limit, so the best-ranked model was used and the task will queue. Other responses: `400`, `404`, `429` ### POST /v1/generate/audio Routed audio generation Start an audio generation task using a saved Model Router config instead of naming a model. Set input.type to speech to speak promptText verbatim, or audio to generate audio described by promptText. Request body: - `configId` (string, required) — The slug of a saved Model Router config to route this request with. - `dryRun` (boolean) — When true, run the full routing pipeline and return the decision and estimated cost without generating. No task is created, nothing is billed, and no asset is produced. - `input` (object, required) — Model-agnostic audio generation input. The router selects a model and maps these options to it. - `type` (string, required) — one of `speech`, `audio`. How promptText is interpreted: `speech` speaks it verbatim as a script; `audio` treats it as a description of the desired audio, which may combine speech, music, ambience, and sound effects. - `promptText` (string, required) — max length 5000. For `speech`, the words to speak. For `audio`, a description of the desired output. - `voice` (object) — The voice to speak with. When omitted, models that support a default voice remain eligible. - `type` (string, required) — one of `preset` - `presetId` (string, required) — one of `Maya`, `Arjun`, `Serene`, `Bernard`, `Billy`, `Mark`, `Clint`, `Mabel`, `Chad`, `Leslie`, `Eleanor`, `Elias`, `Elliot`, `Grungle`, `Brodie`, `Sandra`, `Kirk`, `Kylie`, `Lara`, `Lisa`, `Malachi`, `Marlene`, `Martin`, `Miriam`, `Monster`, `Paula`, `Pip`, `Rusty`, `Ragnar`, `Xylar`, `Maggie`, `Jack`, `Katie`, `Noah`, `James`, `Rina`, `Ella`, `Mariah`, `Frank`, `Claudia`, … (49 total). A Runway preset voice id. Choosing a preset routes only to models that support preset voices. - `referenceAudios` (array of object) — max 3 items. Optional reference audio clips guiding `audio` generation, for models that support them. Reference each clip in promptText as @Audio1, @Audio2, and @Audio3 in order. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information. - `duration` (number) — 0.5–30. Desired output duration in seconds for `audio` generation. Models that cannot honor an explicit duration are excluded. - `loop` (boolean) — When true, the `audio` output is designed to loop seamlessly. Models without loop support are excluded. Response 200: - `dryRun` (boolean, required) — one of `false` - `id` (string, required) — format uuid. The ID of the created task. Poll GET /v1/tasks/:id for the result. - `routing` (object, required) — Metadata describing which model the router selected and why. - `model` (string, required) — The public name of the model the router selected. - `provider` (string, required) — The provider of the selected model. - `configId` (string, required) — The slug of the router config that was applied to this request. - `resolvedSettings` (object, required) — The resolved config settings the router used for this request. - `optimizeFor` (string, required) — one of `cost`, `latency`, `quality`. The single optimization preference the config selected, used as the soft weighting when scoring eligible models. - `priceCeiling` (number or null, required) — The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling. - `resolvedInput` (object, required) — Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options. - `type` (string, required) — one of `speech`, `audio`. The prompt mode the router routed for. - `voice` (string, required) — one of `preset`, `reference-audio`, `default`, `none`. How the selected model resolves the voice: the requested preset or reference-audio clone, the model default for voiceless speech, or none for general audio. - `estimatedCost` (object, required) — Estimated cost, computed against current pricing. - `credits` (number, required) — Estimated cost of the generation in credits. - `capacityFallback` (object) — Present only when the config enables fallback.onCapacity and capacity affected this request. - `skipped` (array of string, required) — Eligible models that were considered for this request but not selected because this account is at its concurrency limit for them. - `allExhausted` (boolean, required) — True when every eligible model was at its concurrency limit, so the best-ranked model was used and the task will queue. Other responses: `400`, `404`, `429` ### GET /v1/routers List Model Routers List Model Router configurations for the authenticated organization with cursor-based pagination. Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. Response 200: - `data` (array of object, required) — The list of items for the current page. - `id` (string, required) — format uuid. The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests. - `slug` (string, required) — Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier. - `name` (string, required) — max length 255. Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests. - `description` (string or null, required) — An optional Model Router description. - `version` (integer, required) — greater than 0. Current settings version. Increments when settings change; name and description updates do not create a new version. - `settings` (object, required) - `schemaVersion` (number, required) — one of `1`. Settings JSON schema version used when this snapshot was written. - `models` (object) — When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update). - `mode` (string, required) — one of `allow_new_except`, `allowlist_only` - `ids` (array of string, required) - `maxCreditsPerGeneration` (object) — Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded. - `video` (integer) — greater than 0 - `image` (integer) — greater than 0 - `audio` (integer) — greater than 0 - `optimizeFor` (string) — one of `cost`, `latency`, `quality`. Soft preference among eligible models: cost, latency, or quality. - `fallback` (object) — Opt-in behavior for what routing should do when the preferred model cannot start immediately. - `onCapacity` (boolean) — When true, if the account is at its concurrency limit on the preferred model, routing skips it and picks the next-best eligible model instead of queueing. If every eligible model is at its limit, the original best-ranke… - `createdAt` (string, required) — format date-time. When the Model Router was created. - `updatedAt` (string, required) — format date-time. When the Model Router was last updated. - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ### POST /v1/routers Create Model Router Create a Model Router configuration. Request body: - `slug` (string, required) — Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier. - `name` (string) — max length 255. Optional human-readable display name for this router. Defaults to the slug when omitted. - `description` (string) — max length 2000. An optional Model Router description. - `settings` (object) — Model Router routing preferences. Defaults to cost-optimized allow-all when omitted. Modality is implied by the generate endpoint used with this Model Router. - `schemaVersion` (number) — one of `1`. Settings JSON schema version. Omit on write to use the current version; responses and stored snapshots always include it. - `models` (object) — When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update). - `mode` (string, required) — one of `allow_new_except`, `allowlist_only` - `ids` (array of string, required) - `maxCreditsPerGeneration` (object) — Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded. - `video` (integer) — greater than 0 - `image` (integer) — greater than 0 - `audio` (integer) — greater than 0 - `optimizeFor` (string) — one of `cost`, `latency`, `quality`. Soft preference among eligible models: cost, latency, or quality. - `fallback` (object) — Opt-in behavior for what routing should do when the preferred model cannot start immediately. - `onCapacity` (boolean) — When true, if the account is at its concurrency limit on the preferred model, routing skips it and picks the next-best eligible model instead of queueing. If every eligible model is at its limit, the original best-ranke… Response 200: - `id` (string, required) — format uuid. The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests. - `slug` (string, required) — Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier. - `name` (string, required) — max length 255. Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests. - `description` (string or null, required) — An optional Model Router description. - `version` (integer, required) — greater than 0. Current settings version. Increments when settings change; name and description updates do not create a new version. - `settings` (object, required) - `schemaVersion` (number, required) — one of `1`. Settings JSON schema version used when this snapshot was written. - `models` (object) — When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update). - `mode` (string, required) — one of `allow_new_except`, `allowlist_only` - `ids` (array of string, required) - `maxCreditsPerGeneration` (object) — Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded. - `video` (integer) — greater than 0 - `image` (integer) — greater than 0 - `audio` (integer) — greater than 0 - `optimizeFor` (string) — one of `cost`, `latency`, `quality`. Soft preference among eligible models: cost, latency, or quality. - `fallback` (object) — Opt-in behavior for what routing should do when the preferred model cannot start immediately. - `onCapacity` (boolean) — When true, if the account is at its concurrency limit on the preferred model, routing skips it and picks the next-best eligible model instead of queueing. If every eligible model is at its limit, the original best-ranke… - `createdAt` (string, required) — format date-time. When the Model Router was created. - `updatedAt` (string, required) — format date-time. When the Model Router was last updated. ### GET /v1/routers/{id} Retrieve Model Router Retrieve a Model Router configuration by ID. Parameters: - `id` (path, string, required) — format uuid. The Model Router's primary key ID (UUID). Response 200: - `id` (string, required) — format uuid. The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests. - `slug` (string, required) — Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier. - `name` (string, required) — max length 255. Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests. - `description` (string or null, required) — An optional Model Router description. - `version` (integer, required) — greater than 0. Current settings version. Increments when settings change; name and description updates do not create a new version. - `settings` (object, required) - `schemaVersion` (number, required) — one of `1`. Settings JSON schema version used when this snapshot was written. - `models` (object) — When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update). - `mode` (string, required) — one of `allow_new_except`, `allowlist_only` - `ids` (array of string, required) - `maxCreditsPerGeneration` (object) — Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded. - `video` (integer) — greater than 0 - `image` (integer) — greater than 0 - `audio` (integer) — greater than 0 - `optimizeFor` (string) — one of `cost`, `latency`, `quality`. Soft preference among eligible models: cost, latency, or quality. - `fallback` (object) — Opt-in behavior for what routing should do when the preferred model cannot start immediately. - `onCapacity` (boolean) — When true, if the account is at its concurrency limit on the preferred model, routing skips it and picks the next-best eligible model instead of queueing. If every eligible model is at its limit, the original best-ranke… - `createdAt` (string, required) — format date-time. When the Model Router was created. - `updatedAt` (string, required) — format date-time. When the Model Router was last updated. ### PATCH /v1/routers/{id} Update Model Router Update a Model Router configuration. Settings changes append a new version; name and description updates do not. Settings are merged with the current snapshot - omitted fields keep their existing values. Parameters: - `id` (path, string, required) — format uuid. The Model Router's primary key ID (UUID). Request body: - `name` (string) — max length 255. Display name. The slug is immutable and cannot be changed after creation. - `description` (string or null) - `settings` (object) — Nested merge: omitted settings fields keep their current values. When models is present, omitted models.mode or models.ids are preserved (sending only optimizeFor does not clear the model allowlist or credit ceiling). - `schemaVersion` (number) — one of `1`. Settings JSON schema version. Omit on write to use the current version; responses and stored snapshots always include it. - `models` (object) — When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update). - `mode` (string, required) — one of `allow_new_except`, `allowlist_only` - `ids` (array of string, required) - `maxCreditsPerGeneration` (object) — Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded. - `video` (integer) — greater than 0 - `image` (integer) — greater than 0 - `audio` (integer) — greater than 0 - `optimizeFor` (string) — one of `cost`, `latency`, `quality`. Soft preference among eligible models: cost, latency, or quality. - `fallback` (object) — Opt-in behavior for what routing should do when the preferred model cannot start immediately. - `onCapacity` (boolean) — When true, if the account is at its concurrency limit on the preferred model, routing skips it and picks the next-best eligible model instead of queueing. If every eligible model is at its limit, the original best-ranke… Response 200: - `id` (string, required) — format uuid. The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests. - `slug` (string, required) — Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier. - `name` (string, required) — max length 255. Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests. - `description` (string or null, required) — An optional Model Router description. - `version` (integer, required) — greater than 0. Current settings version. Increments when settings change; name and description updates do not create a new version. - `settings` (object, required) - `schemaVersion` (number, required) — one of `1`. Settings JSON schema version used when this snapshot was written. - `models` (object) — When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update). - `mode` (string, required) — one of `allow_new_except`, `allowlist_only` - `ids` (array of string, required) - `maxCreditsPerGeneration` (object) — Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded. - `video` (integer) — greater than 0 - `image` (integer) — greater than 0 - `audio` (integer) — greater than 0 - `optimizeFor` (string) — one of `cost`, `latency`, `quality`. Soft preference among eligible models: cost, latency, or quality. - `fallback` (object) — Opt-in behavior for what routing should do when the preferred model cannot start immediately. - `onCapacity` (boolean) — When true, if the account is at its concurrency limit on the preferred model, routing skips it and picks the next-best eligible model instead of queueing. If every eligible model is at its limit, the original best-ranke… - `createdAt` (string, required) — format date-time. When the Model Router was created. - `updatedAt` (string, required) — format date-time. When the Model Router was last updated. ### DELETE /v1/routers/{id} Delete Model Router Delete a Model Router configuration. Deleted Model Routers cannot be used for generation. Parameters: - `id` (path, string, required) — format uuid. The Model Router's primary key ID (UUID). ### GET /v1/routers/{id}/requests List Model Router requests Paginated routing history for live Model Router requests (successful routes and failures). Playground dry runs are not recorded. Parameters: - `id` (path, string, required) — format uuid. The Model Router's primary key ID (UUID). - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. Response 200: - `data` (array of object, required) — The list of items for the current page. - `id` (string, required) — format uuid - `requestId` (string, required) - `status` (string, required) — one of `routed`, `no_eligible_model`, `router_config_not_found`, `invalid_request`, `error`. How the routing attempt ended: routed (model selected), no_eligible_model (hard filters emptied the pool), router_config_not_found (same condition as the generate error of that name), invalid_request, or error. - `model` (string or null, required) - `provider` (string or null, required) - `reason` (string or null, required) — Free-text explanation of the pick. Written by the ranker, so treat it as prose for humans and group on reasonCode instead. - `reasonCode` (string or null, required) — Why the model won: lowest_cost, best_latency, best_quality, only_eligible_model, or filter_order_fallback (ranking was unavailable, so hard-filter order stood). Null when the request never reached ranking. - `estimatedCredits` (number or null, required) - `taskId` (string or null, required) - `createdAt` (string, required) — format date-time - `pipeline` (array of object, required) — Ordered routing story: hard-filter stages with surviving model ids, a capacity step when concurrency limits affected the pool, then rank step when selection reached ranking. - `type` (string, required) — one of `filter` - `filter` (string, required) — one of `capability`, `prompt_length`, `input_support`, `allow_deny`, `price`. Hard-filter stage that ran: capability (modality/feature fit), prompt_length (prompt within model limits), input_support (requested inputs/assets), allow_deny (router model allowlist/denylist), or price (credit ceiling). - `models` (array of string, required) — Model IDs of the models that remained eligible after this filter stage. - `emptiedBy` (array of string, required) — The filter(s) that reduced the eligible pool to zero. - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ## Organization ### GET /v1/organization/webapp/usage List linked workspace usage List per-generation credit-usage rows for the linked Runway workspaces you administer, newest first. Unlike `/v1/organization/usage` (this API project's own usage), this reports usage from the workspace linked to this A… Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. - `from` (query, string, required) — format date-time. Start of the time window (inclusive), ISO-8601 datetime. - `to` (query, string, required) — format date-time. End of the time window (exclusive), ISO-8601 datetime. A `cursor` can only narrow this window, never extend it past `to`. - `organizationId` (query, string) — format uuid. Organization to report on. Optional when this API project is linked to a single organization; required when it is linked to more than one. - `workspaceIds` (query, string) — Restrict results to these workspace IDs, as a comma-separated list. Defaults to every workspace you administer in the organization. Response 200: - `data` (array of object, required) — The list of items for the current page. - `timestamp` (string, required) — format date-time. When the generation was charged. - `email` (string, required) — Email of the user who generated. - `workspaceId` (integer, required) — ID of the owning workspace. - `workspaceName` (string, required) — Name of the owning workspace. - `tool` (string, required) — Model/task display name for the generation. - `credits` (number, required) — Credits charged for this generation. - `type` (string, required) — one of `charge`, `refund`. Whether the row is a credit charge for a generation or a task refund (negative credits). - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ### GET /v1/organization/webapp/audit_logs List linked workspace audit logs List audit log entries for the linked Runway workspaces you administer, newest first. Authorized via the account link between this API project and the workspace. Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. - `organizationId` (query, string) — format uuid. Organization to report on. Optional when this API project is linked to a single organization; required when it is linked to more than one. - `workspaceIds` (query, string) — Restrict results to these workspace IDs, as a comma-separated list of up to 50 IDs. Defaults to every workspace you administer in the organization. - `actions` (query, string) — Restrict results to these audit log actions, as a comma-separated list of up to 50 actions. Allowed values: `UserLogin`, `PasswordChanged`, `EmailChangeRequested`, `EmailChanged`, `UserRegistered`, `UserAccountDeleted`,… - `actorEmails` (query, string) — Restrict results to entries performed by the users with these emails, as a comma-separated list of up to 50 emails. - `from` (query, string) — format date-time. Start of the time window (inclusive), ISO-8601 datetime. - `to` (query, string) — format date-time. End of the time window (exclusive), ISO-8601 datetime. Response 200: - `data` (array of object, required) — The list of items for the current page. - `eventId` (string, required) — format uuid. Unique identifier of the entry. - `timestamp` (string, required) — format date-time. When the action occurred. - `action` (string, required) — one of `UserLogin`, `PasswordChanged`, `EmailChangeRequested`, `EmailChanged`, `UserRegistered`, `UserAccountDeleted`, `WorkspaceCreated`, `WorkspaceDeleted`, `MemberInvited`, `MemberRemoved`, `MemberRoleChanged`, `InviteAccepted`, `TeamSettingsUpdated`, `InviteLinkToggled`, `UserGroupCreated`, `UserGroupUpdated`, `UserGroupDeleted`, `UserGroupArchived`, `UserGroupRestored`, `UserGroupMemberAdded`, `UserGroupMemberRemoved`, `SSOLogin`, `SSOUserProvisioned`, `SSOConfigCreated`, `SSOUserAutoAddedToTeam`, `SSODomainRegistrationCloned`, `AssetCreated`, `AssetUpdated`, `AssetDeleted`, `AssetDownloaded`, `AssetShared`, `AssetUnshared`, `CommentCreated`, `CommentEdited`, `CommentDeleted`, `CommentAgentCallRun`, `CommentRemovedByModerator`, `CommentRestoredByModerator`, `CommentRemovalReasonChanged`, `PermissionGranted`, … (85 total). The action performed. - `actorUsername` (string or null, required) — Username of the user who performed the action. - `actorEmail` (string or null, required) — Email of the user who performed the action. - `actorDeleted` (boolean, required) — Whether the acting user has since been deleted. - `workspaceId` (integer, required) — ID of the owning workspace. - `workspaceName` (string, required) — Name of the owning workspace. - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ### GET /v1/organization/webapp/audit_logs/{eventId} Get a linked workspace audit log entry Get a single audit log entry, including its metadata and forensic details, for a linked Runway workspace you administer. Authorized via the account link between this API project and the workspace. Parameters: - `eventId` (path, string, required) — format uuid. The `eventId` of an entry returned by the list endpoint. - `organizationId` (query, string) — format uuid. Organization to report on. Optional when this API project is linked to a single organization; required when it is linked to more than one. Response 200: - `eventId` (string, required) — format uuid. Unique identifier of the entry. - `timestamp` (string, required) — format date-time. When the action occurred. - `action` (string, required) — one of `UserLogin`, `PasswordChanged`, `EmailChangeRequested`, `EmailChanged`, `UserRegistered`, `UserAccountDeleted`, `WorkspaceCreated`, `WorkspaceDeleted`, `MemberInvited`, `MemberRemoved`, `MemberRoleChanged`, `InviteAccepted`, `TeamSettingsUpdated`, `InviteLinkToggled`, `UserGroupCreated`, `UserGroupUpdated`, `UserGroupDeleted`, `UserGroupArchived`, `UserGroupRestored`, `UserGroupMemberAdded`, `UserGroupMemberRemoved`, `SSOLogin`, `SSOUserProvisioned`, `SSOConfigCreated`, `SSOUserAutoAddedToTeam`, `SSODomainRegistrationCloned`, `AssetCreated`, `AssetUpdated`, `AssetDeleted`, `AssetDownloaded`, `AssetShared`, `AssetUnshared`, `CommentCreated`, `CommentEdited`, `CommentDeleted`, `CommentAgentCallRun`, `CommentRemovedByModerator`, `CommentRestoredByModerator`, `CommentRemovalReasonChanged`, `PermissionGranted`, … (85 total). The action performed. - `actorUsername` (string or null, required) — Username of the user who performed the action. - `actorEmail` (string or null, required) — Email of the user who performed the action. - `actorDeleted` (boolean, required) — Whether the acting user has since been deleted. - `workspaceId` (integer, required) — ID of the owning workspace. - `workspaceName` (string, required) — Name of the owning workspace. - `metadata` (object, required) — Action-specific details. - `Workspace` (unknown) - `Invited member` (unknown) - `Removed member` (unknown) - `Target member` (unknown) - `Member email` (unknown) - `Previous role` (unknown) - `New role` (unknown) - `Role` (unknown) - `Login method` (unknown) - `Platform` (unknown) - `Application` (unknown) - `Plan` (unknown) - `Amount` (unknown) - `New User` (unknown) - `Group name` (unknown) - `Model` (unknown) - `Operation` (unknown) - `Asset name` (unknown) - `Comment ID` (unknown) - `Comment target type` (unknown) - `Comment target ID` (unknown) - `Mentions` (unknown) - `Agent tagged` (unknown) - `Agent session ID` (unknown) - `Outcome` (unknown) - `Error code` (unknown) - `Reason` (unknown) - `Tag name` (unknown) - `Tag color` (unknown) - `Workspace ID` (unknown) - `Workspace name` (unknown) - `Workspace picture` (unknown) - `Workspace description` (unknown) - `Default task name template` (unknown) - `Setting` (unknown) - `Previous value` (unknown) - `New value` (unknown) - `Shared with workspace` (unknown) - `Shared with projects` (unknown) - `Hard spend cap` (unknown) - `Spend cap` (unknown) - `API account` (unknown) - `API project ID` (unknown) - `Direction` (unknown) - `Amount received` (unknown) - `resourceType` (string or null, required) — Type of the affected resource, if any. Currently one of `account_link`, `agent_custom_skill`, `asset`, `brand_kit`, `generation`, `invite_link`, `membership`, `organization`, `permission`, `promotion`, `session`, `share… - `resourceId` (string or null, required) — ID of the affected resource, if any. - `clientIpAddress` (string, required) — IP address of the client that performed the action. - `userAgent` (string or null, required) — User-Agent header of the client request. - `requestId` (string or null, required) — Request ID for correlation with other logs. Other responses: `404` ### GET /v1/organization Get organization information Get usage tier and credit balance information about the organization associated with the API key used to make the request. Response 200: - `tier` (object, required) — Limits associated with the organization's tier. - `maxMonthlyCreditSpend` (integer, required) — minimum 0. The maximum number of credits that can be purchased in a month. - `models` (object, required) — An object containing model-specific limits. Each key represents a model. - `creditBalance` (integer, required) — minimum 0. The number of credits remaining in the organization account. - `usage` (object, required) — Usage data for the organization. - `models` (object, required) ### POST /v1/organization/usage Query credit usage Fetch credit usage data broken down by model and day for the organization associated with the API key used to make the request. Up to 90 days of data can be queried at a time. Request body: - `startDate` (string) — format date. The start date of the usage data in ISO-8601 format (YYYY-MM-DD). If unspecified, it will default to 30 days before the current date. All dates are in UTC. - `beforeDate` (string) — format date. The end date of the usage data in ISO-8601 format (YYYY-MM-DD), not inclusive. If unspecified, it will default to thirty days after the start date. Must be less than or equal to 90 days after the start date. All dates a… Response 200: - `results` (array of object, required) - `date` (string, required) — format date. The date of the usage data in ISO-8601 format (YYYY-MM-DD). All dates are in UTC. - `usedCredits` (array of object, required) — The credits used per model for the given date. - `model` (string, required) — one of `gen4.5`, `gen3a_turbo`, `gen4_turbo`, `gen4_image`, `gen4_image_turbo`, `gpt_image_2`, `act_two`, `gen4_aleph`, `veo3`, `veo3.1`, `veo3.1_fast`, `gemini_2.5_flash`, `gemini_image3_pro`, `gemini_image3.1_flash`, `seedream5_pro`, `seedream5_lite`, `gemini_omni_flash`, `gemini_omni_flash_1.1`, `eleven_multilingual_v2`, `seed_audio`, `eleven_v3`, `eleven_text_to_sound_v2`, `eleven_voice_isolation`, `eleven_voice_dubbing`, `eleven_multilingual_sts_v2`, `eleven_scribe_v2`, `gwm1_avatars`, `gwm1_avatar_async_audio_to_video`, `gwm1_avatar_async_text_to_video`, `voice_processing`, `seedance2`, `seedance2_5`, `seedance2_fast`, `seedance2_mini`, `hailuo3`, `h3_max`, `wan3`, `wan3_prime`, `grok_imagine_1_5`, `grok_imagine_image_2`, … (60 total). The model that credits were spent on. - `amount` (integer, required) — The net number of credits spent on the model. May be negative if refunds exceeded charges on this day. - `models` (array of string, required) — The list of models with usage during the queried time range. - `apiKeys` (array of string) — Reserved for future use. - `resultsByApiKey` (array of object) — Reserved for future use. - `date` (string, required) — format date - `usedCredits` (array of object, required) - `apiKeyId` (string, required) — format uuid - `amount` (integer, required) ## Uploads Endpoints for uploading media files. ### POST /v1/uploads Upload a file Uploads a temporary media file that can be referenced in API generation requests. The uploaded files will be automatically expired and deleted after a period of time. It is strongly recommended to use our SDKs for this… Request body: - `filename` (string, required) — max length 255. The filename of the file to upload. Must have a valid extension and be a supported media type (image, video, or audio). - `type` (string, required) — one of `ephemeral`. The type of upload to create Response 200: - `uploadUrl` (string, required) — format uri. The URL to upload your media file to with a POST request. - `fields` (object, required) — Fields that must be included in the file upload request as form data. - `runwayUri` (string, required) — The Runway upload URI to use in other API generation requests Other responses: `429` ## Recipes ### POST /v1/recipes/ad_localization Localize an ad image Localize an existing ad image for a target language, preserving visual creative while adapting on-screen messaging. Request body: - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `referenceImage` (object, required) — Reference ad image to localize. See [our docs](/assets/inputs#images) on image inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `targetLanguage` (string, required) — one of `ar`, `zh`, `zh-Hant`, `nl`, `en`, `fr`, `de`, `hi`, `id`, `it`, `ja`, `ko`, `pl`, `pt`, `ru`, `es`, `sv`, `th`, `tr`, `uk`, `vi`, `el`. Target language for the localized ad. Use ISO-style codes (e.g. "ja" for Japanese, "es" for Spanish). Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/recipes/marketing_stock_image Create a marketing stock image Generate a polished marketing stock image from a text brief and optional brand logo image. Request body: - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `prompt` (string, required) — max length 3500. Marketing image brief. Describe the subject, audience, channel, desired mood, setting, and any constraints. - `referenceImage` (object) — Optional brand logo image to guide the generated marketing stock image. See [our docs](/assets/inputs#images) on image inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `outputCount` (integer) — 1–4; default `4`. The number of images to generate (1-4). Defaults to 4. Increasing this number affects credits consumed. - `quality` (string) — one of `low`, `medium`, `high`; default `high`. GPT Image 2 rendering quality (`low`, `medium`, or `high`). Lower settings are faster and use fewer credits; `high` (default) is slowest and highest fidelity. Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/recipes/product_ad Create a product ad video Generate a cinematic product ad from product images, optional style references, product info, and creative direction. Request body: - `version` (string, required) — one of `2026-06`, `2026-07`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-07") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `productImages` (array of object, required) — min 1 items; max 10 items. Product images (1-10). Multiple angles of the same product. All images inform product analysis and reference generation; only the first image is used as the primary product reference in the storyboard grid. See [our doc… - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `styleImages` (array of object) — max 4 items. Optional style reference images (0-4). Defines the visual treatment (lighting, palette, mood). Treated as a moodboard when multiple are provided. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `productInfo` (string) — max length 2500; default ``. Optional product description and specifications to inform creative direction and which product elements to highlight. - `userConcept` (string) — max length 3500; default ``. Optional creative direction describing brand voice, product framing, scene specifics, lighting, camera motion, and narrative. - `ratio` (string) — one of `1280:720`, `720:1280`, `960:960`, `834:1112`, `1920:1080`, `1080:1920`, `1440:1440`, `1248:1664`. The resolution of the output video. - `duration` (integer) — 4–15. Duration of the output video in seconds (4-15). Defaults to 10 seconds. - `audio` (boolean) — default `false`. Whether to generate audio for the video. Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/recipes/product_campaign_image Create product campaign images Generate four fashion campaign images from a product image and style brief. Request body: - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `image` (object, required) — Product image to preserve across the generated campaign. See [our docs](/assets/inputs#images) on image inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `prompt` (string, required) — max length 3500. Style / creative brief for the fashion campaign, e.g. "High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K". Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/recipes/product_swap Swap a product in a reference video Replace the product in a reference video with a new product, preserving camera motion, lighting, and scene composition. Request body: - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `referenceVideo` (object, required) — Reference video containing the product to swap. Duration must be between 1.8 and 15 seconds. See [our docs](/assets/inputs#videos) on video inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information. - `originalProductImage` (object, required) — Image of the original product being swapped out. See [our docs](/assets/inputs#images) on image inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `newProductImages` (array of object, required) — min 1 items; max 10 items. Reference images of the new product (1-10). Supply multiple angles when the reference video shows the product from different views - optionally label each with `view` ("front", "side", or "back"). A single pre-composed… - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `view` (string) — one of `front`, `side`, `back`. Optional view label for this reference (front, side, or back). Omit when supplying a single reference sheet or when view labels are unknown. - `duration` (integer) — 4–15. Duration of the output video in seconds (4-15). Defaults to 10 seconds. - `resolution` (string) — one of `720p`, `1080p`. Output video resolution. Defaults to 720p. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/recipes/multi_shot_video Create a multi-shot video Generate a multi-cut video from a story prompt (auto mode) or a custom shot list (custom mode). Request body: one of 2 shapes, selected by `mode`. Only the fields listed under a given `mode` are valid. #### POST /v1/recipes/multi_shot_video — mode `auto` - `mode` (string, required) — one of `auto`. Workflow mode. `auto` decomposes a story prompt into exactly 5 shots. - `prompt` (string, required) — max length 2500. Story prompt for auto mode. - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `firstFrame` (object) — Optional image used as the first frame of the output video. See [our docs](/assets/inputs#images) on image inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `ratio` (string) — one of `1280:720`, `720:1280`, `960:960`, `1920:1080`, `1080:1920`, `1440:1440`. Output dimensions as width:height. 720p ratios (`1280:720`, `720:1280`, `960:960`) use the standard tier; 1080p ratios (`1920:1080`, `1080:1920`, `1440:1440`) use the pro tier. Defaults to `1280:720`. - `duration` (number) — one of `5`, `10`, `15`. Total duration of the output video in seconds. Defaults to 10 seconds. - `audio` (boolean) — default `true`. Whether to generate audio for the video. #### POST /v1/recipes/multi_shot_video — mode `custom` - `mode` (string, required) — one of `custom`. Workflow mode. `custom` polishes a user-provided shot list of 3-5 shots. - `shots` (array of object, required) — min 3 items; max 5 items. Shot list for custom mode (3-5 shots). Per-shot durations must sum to `duration`. - `prompt` (string, required) — max length 512. Shot description prompt. - `duration` (integer, required) — 1–15. Duration of this shot in seconds. - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `firstFrame` (object) — Optional image used as the first frame of the output video. See [our docs](/assets/inputs#images) on image inputs. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `ratio` (string) — one of `1280:720`, `720:1280`, `960:960`, `1920:1080`, `1080:1920`, `1440:1440`. Output dimensions as width:height. 720p ratios (`1280:720`, `720:1280`, `960:960`) use the standard tier; 1080p ratios (`1920:1080`, `1080:1920`, `1440:1440`) use the pro tier. Defaults to `1280:720`. - `duration` (number) — one of `5`, `10`, `15`. Total duration of the output video in seconds. Defaults to 10 seconds. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ### POST /v1/recipes/product_ugc Create a product UGC video Generate a vertical user-generated content ad from a character image, product image, product details, and optional creative direction. Request body: - `version` (string, required) — one of `2026-06`, `unsafe-latest`. Workflow version. Use a dated version (e.g. "2026-06") to pin behavior, or "unsafe-latest" to track the newest stable version (may break without notice). - `characterImage` (object, required) — Image of the character who will appear on camera in the UGC video. Aspect ratio (width / height) must be between 0.4 and 4. See [our docs](/assets/inputs#images) for image input requirements. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `productImage` (object, required) — Image of the product being promoted. Aspect ratio (width / height) must be between 0.4 and 4. See [our docs](/assets/inputs#images) for image input requirements. - `uri` (string, required) — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information. - `productInfo` (string) — max length 2500; default ``. Product details and creative brief - what the product is, key benefits, and any specifics the script should reference. - `userConcept` (string) — max length 3500; default ``. Optional creative direction for the UGC video - tone, voice register, specific message, or an entire dialog script. - `duration` (integer) — 4–15. Duration of the output video in seconds (4-15). Defaults to 15 seconds. - `ratio` (string) — one of `720:1280`, `1080:1920`. The resolution of the output video. - `audio` (boolean) — default `true`. Whether to generate audio for the video. Response 200: - `id` (string, required) — format uuid. The ID of the task that was created. Use this to retrieve the task later. - `estimatedCost` (object, required) — The maximum credits this task may charge. The final amount may be lower after the task completes. - `credits` (number, required) — Estimated cost of the generation in credits. Other responses: `400`, `429` ## Voices ### GET /v1/voices List voices List custom voices for the authenticated organization with cursor-based pagination. Parameters: - `cursor` (query, string) — max length 1000. Cursor from a previous response for fetching the next page of results. - `limit` (query, integer, required) — 1–100; default `50`. The maximum number of items to return per page. Response 200: - `data` (array of object, required) — The list of items for the current page. - `id` (string, required) — format uuid. The unique identifier of the voice. - `name` (string, required) — The name of the voice. - `description` (string or null, required) — A description of the voice, or null if not set. - `createdAt` (string, required) — format date-time. When the voice was created. - `status` (string, required) — one of `PROCESSING` - `hasMore` (boolean, required) — Whether there are more items available after this page. - `nextCursor` (string or null, required) — Cursor to use for fetching the next page, or null if there are no more pages. ### POST /v1/voices Create a voice Create a custom voice from a text description, or clone a voice from an audio sample. Request body: - `name` (string, required) — max length 100. A name for the voice. - `description` (string or null) — An optional description of the voice. - `from` (object, required) - `type` (string, required) — one of `audio` - `audio` (string, required) — Audio sample to clone the voice from. Must be between 10 seconds and 5 minutes long. At most 10MB as a URL or Runway upload URI; at most 5MB as an inline data URI. For best results, use a clear recording with minimal ba… Response 200: - `id` (string, required) — format uuid. The ID of the voice that was created. ### GET /v1/voices/{id} Get a voice Get details about a specific custom voice. Parameters: - `id` (path, string, required) — format uuid. The ID of the voice to retrieve. Response 200: - `id` (string, required) — format uuid. The unique identifier of the voice. - `name` (string, required) — The name of the voice. - `description` (string or null, required) — A description of the voice, or null if not set. - `createdAt` (string, required) — format date-time. When the voice was created. - `status` (string, required) — one of `PROCESSING` ### PATCH /v1/voices/{id} Update a voice Update the name and/or description of a custom voice. Parameters: - `id` (path, string, required) — format uuid. The ID of the voice to update. Request body: - `name` (string) — max length 100. A name for the voice. - `description` (string or null) — An optional description of the voice. Response 200: - `id` (string, required) — format uuid. The unique identifier of the voice. - `name` (string, required) — The name of the voice. - `description` (string or null, required) — A description of the voice, or null if not set. - `createdAt` (string, required) — format date-time. When the voice was created. - `status` (string, required) — one of `PROCESSING` ### DELETE /v1/voices/{id} Delete a voice Delete a custom voice. Parameters: - `id` (path, string, required) — format uuid. The ID of the voice to delete. ### POST /v1/voices/preview Preview a voice Generate a short audio preview of a voice from a text description. Use this to audition a voice before creating it. Request body: - `prompt` (string, required) — max length 1000. A text description of the desired voice characteristics. Must be at least 20 characters. - `model` (string, required) — one of `eleven_ttv_v3`, `eleven_multilingual_ttv_v2`. The voice design model to use. Prefer eleven_ttv_v3 (latest); eleven_multilingual_ttv_v2 is the previous generation. Response 200: - `url` (string, required) — format uri. A presigned URL to the audio preview. The URL expires after 24 hours. - `durationSecs` (number, required) — Duration of the audio preview in seconds. ## Workflows ### GET /v1/workflows/{id} Get workflow details Returns details about a specific published workflow, including its graph schema. Parameters: - `id` (path, string, required) — format uuid. The ID of the published workflow to run. You can copy this value from the developer portal. Response 200: - `id` (string, required) — format uuid. The globally unique ID of the published workflow. - `name` (string, required) — The name of the published workflow. - `description` (string or null, required) — The description of the published workflow. - `version` (integer, required) — minimum 1. A monotonically increasing version number. Each workflow version for the same published workflow has a unique version number. - `createdAt` (string, required) — format date-time. When this version was published - `updatedAt` (string, required) — format date-time. When this version was last updated - `graph` (object, required) — The workflow graph definition. - `nodes` (array of unknown, required) — The list of nodes in the workflow graph. - `edges` (array of unknown, required) — The list of edges connecting nodes in the workflow graph. - `version` (integer, required) — minimum 1. The schema version of the workflow graph format. Other responses: `404` ### POST /v1/workflows/{id} Run a published workflow Start a new task to execute a published workflow. You can optionally provide custom input values via `nodeOutputs` to override the defaults defined in the workflow graph. Parameters: - `id` (path, string, required) — format uuid. The ID of the published workflow to run. You can copy this value from the developer portal. Request body: - `nodeOutputs` (object) — Optional node outputs to override default values. Keys are node IDs from the workflow graph, values are objects mapping output keys to typed values. Response 200: - `id` (string, required) — format uuid. The ID of the workflow invocation that was created. Other responses: `404` ### GET /v1/workflows List published workflows Returns a list of all published workflows for the authenticated user, grouped by source workflow with their published versions. Response 200: - `data` (array of object, required) — A list of published workflows grouped by source workflow. - `name` (string, required) — The name of the published workflow. - `versions` (array of object, required) — The published versions of this workflow, newest first. - `id` (string, required) — format uuid. The globally unique ID of this published workflow version. - `version` (integer, required) — minimum 1. A monotonically increasing version number. Each workflow version for the same published workflow has a unique version number. - `createdAt` (string, required) — format date-time. When this version was published ### GET /v1/workflow_invocations/{id} Get workflow invocation detail Return details about a workflow invocation. Consumers of this API should not expect updates more frequent than once every five seconds for a given workflow invocation. Parameters: - `id` (path, string, required) — format uuid. The ID of a previously-submitted workflow invocation that has not been canceled or deleted. Response 200: - `id` (string, required) — format uuid. The ID of the workflow invocation being returned. - `createdAt` (string, required) — format date-time. The timestamp that the workflow invocation was submitted at. - `status` (string, required) — one of `PENDING` Other responses: `404`