Skip to main content
Use tools/list after connecting with OAuth. It returns the tool descriptions and input schemas for the authenticated account. Call a tool with tools/call, passing its exact name and an arguments object. Tool calls derive the caller from the OAuth token and recheck the active account. Resource ownership, visibility, moderation, account eligibility, and credit rules still apply. Provide only the documented arguments.

​
Available tools

These tools cover the current MCP surface. For additional reviewed workflows, see the GraphQL API reference.

​
Account-specific defaults

Generation schemas and omitted arguments use the current account’s defaults. Call tools/list again when account status changes. Defaults fill absent fields; they do not replace explicit values, including false, empty arrays, or invalid values. Omit optional fields instead of sending null, except where the tool explicitly permits a nullable modelId. Each quality/resolution pair in the table lists outputQuality then resolution. If a free account explicitly selects a video quality that cannot use the default SD, omitted resolution becomes HD. For edit_motion, explicit ultraS uses FHD on either account type. Valid explicit overrides remain supported; quality changes can alter duration and reference limits. width and height are aspect-ratio components where exposed, with supported pairs (9,16), (3,4), (1,1), (4,3), and (16,9). Supply both dimensions when overriding a ratio.

​
Submit once, then read

1

Prepare the inputs

Discover models and elements, or upload/import media. For create_image, read the image prompt resource described in Generation.
2

Submit and save the receipt

Review the requested work and its credit effects. Generation calls return taskId, contentId, status, and terminal. Save the receipt immediately.
3

Follow the existing task

Call get_generation_result with taskId until terminal. Use spaced reads and a bounded waiting policy. A client timeout does not cancel the task. Model creation instead uses get_model_status with modelId.
4

Retrieve completed outputs

Successful content completion exposes permitted temporary output URLs. Inspect and download the media while those URLs are valid; read the result again when you need fresh URLs.
Generation, Live mutations, model creation, and billing actions are non-idempotent. They may consume credits or charge a saved payment method. Do not repeat a successful submission or automatically retry an uncertain result. Reconcile the existing task, account history, room, or payment first.
Successful tools return public JSON in both structuredContent and a text content block. Tool failures return isError: true and text describing the failure. Inspect the MCP tool result even when the HTTP request succeeds. The retryable completion of an already prepared upload is a specific exception: use the same uploadId as documented in Uploads and Live.