↗ tangara.docs Open studio
TANGARA API v1

AI video generation API and MCP

Turn a prompt and optional model-supported image, video or audio references into an MP4. Upload references once, reuse their IDs, and follow generation until the finished video is ready to download.

REST URL: https://tangara.app/api/v1 · MCP URL: https://tangara.app/mcp · Authentication: Bearer API key

Use REST from your application or connect an AI client through MCP. Both use the same models, prices, account balance and video history.

Generation is asynchronous: creating a task returns its ID immediately. A compatible GPU worker processes it when available. A queued task is saved even if you disconnect.

Get your API key

Sign in at tangara.app, open your account menu and select API key. Copy the key into an environment variable on your server or computer. The same key also authenticates the MCP endpoint described below. When Google sign-in is enabled, it opens the same Tangara account. Linking Google preserves your API key, balance and history. REST continues to use the personal Bearer key, and MCP accepts either that key or an OAuth access token issued to a custom connector. Google tokens are never accepted as Tangara API credentials. The examples below use Bash, curl, jq and Python 3 (only to generate UUIDs).

bash
export TANGARA_API_URL='https://tangara.app/api/v1'
export TANGARA_API_KEY='tgapi_REPLACE_WITH_YOUR_KEY'

curl --fail-with-body --silent --show-error \
  "$TANGARA_API_URL/me" \
  -H "Authorization: Bearer $TANGARA_API_KEY"

Your key grants access to your own images, videos and balance. It has the same active-task limit as the website. It is not a GPU worker or administrator key. Keep it on the server side; do not put it in browser JavaScript, URLs or Git. No session cookie, login request or Origin header is needed for this API.

New accounts receive a key immediately. Existing accounts receive one when opening API key. Regenerating it invalidates the previous key and closes its WebSockets. Password reset also rotates the key. Fetch the new key from your account afterwards.

MCP

Server URL: https://tangara.app/mcp · Transport: Streamable HTTP · Authentication: OAuth access token, or Authorization: Bearer <your personal API key>.

Claude and ChatGPT cannot send a static header, so they connect to the same URL as a custom connector and authorize through OAuth; the browser opens a Tangara consent page where you sign in and choose Allow. An MCP client that supports custom headers can use your personal API key instead. Both credentials reach the same account and tools.

The endpoint is stateless, checks the credential on every request, and is only available on the public website listener. Regenerating an API key revokes that key's MCP access immediately. The URL is also shown under Account → API key → MCP.

Tool Purpose
list_models Descriptions, input requirements, available LoRAs, resolutions, durations and tariffs
quote_video Calculate the total price without creating or charging a task
generate_video Queue a video using the user's accepted quote; charges when paid generation is enabled
list_videos Search and page through your private tasks
get_video Read a task's status and generation settings
get_video_result Obtain a temporary signed download URL for a completed video
list_images Find IDs of your uploaded and generated images, usable as video inputs
upload_image Upload a private PNG/JPEG/WebP image and return its asset ID for video inputs
prepare_reference_upload Prepare a create-only signed storage PUT for a private Seedance video/audio reference
complete_reference_upload Verify an uploaded reference and measure its duration before it can be used
get_reference_input Retrieve owned reference metadata for reuse
get_balance Read your balance and first 50 raw ledger entries
list_transactions Page through your top-ups, charges and refunds with linked videos and all-time totals

OAuth for custom connectors

Without a token, /mcp answers 401 with WWW-Authenticate: Bearer realm="Tangara MCP", resource_metadata="…", which is where a connector starts. Nothing has to be registered in advance.

Document URL
Protected resource metadata https://tangara.app/.well-known/oauth-protected-resource
Authorization server metadata https://tangara.app/.well-known/oauth-authorization-server
Endpoint Purpose
POST /oauth/register Dynamic client registration (RFC 7591). Public clients only: token_endpoint_auth_method must be none. Redirect URIs must be HTTPS, or plain HTTP on 127.0.0.1/localhost for native apps; up to eight, no fragments.
GET /oauth/authorize Starts the browser flow. Requires response_type=code, a PKCE S256 code_challenge and scope=mcp; redirect_uri must exactly match a registered URI.
POST /oauth/token grant_type=authorization_code with code_verifier, or grant_type=refresh_token. Form-encoded.
POST /oauth/revoke Revokes an access or refresh token (RFC 7009). client_id is optional because the token identifies its own connection. Revoking either credential ends that whole connection; repeating a revocation still returns 200.

The user signs in with their normal Tangara account and approves the client on the consent page. Credentials are opaque and independent of browser sessions and API keys:

Credential Lifetime
Authorization code 5 minutes, single use, bound to the client and redirect_uri
Access token 1 hour
Refresh token 30 days; each exchange rotates both tokens

One approval creates one connection, listed under Account → API key → MCP → Connected apps. Disconnecting it stops every token issued from that approval at once, and replaying a spent refresh token revokes the connection. A wrong code_verifier does not consume the code, so a client can retry a mistyped exchange.

bash
curl --fail-with-body --silent --show-error \
  "https://tangara.app/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id="$TANGARA_OAUTH_CLIENT_ID" \
  -d code="$TANGARA_OAUTH_CODE" \
  -d redirect_uri="$TANGARA_OAUTH_REDIRECT_URI" \
  -d code_verifier="$TANGARA_OAUTH_CODE_VERIFIER"

Development instances can additionally expose the image/music tools documented under local image and music preview. Discover tools on your instance; their presence here does not mean they are enabled on tangara.app.

Read list_models, then call quote_video with profile_id and duration_seconds. To generate, pass the returned version and amount as expected_price, along with the prompt, profile, duration and a fresh UUID in client_request_id. The amount is an integer string in thousandths of USD, not dollars. The quote alone never authorizes a purchase: obtain the user's authorization before invoking generate_video.

Keep the UUID and all arguments unchanged when retrying after a lost response. The same admission, ownership, charging, refund and idempotency rules apply as in the studio and REST API. Disabled LoRAs are omitted from the model catalog and new requests for them return the lora_unavailable tool error without a charge. Existing accepted requests can still be confirmed by retrying them.

Use upload_image with raw file bytes encoded as standard base64 in data_base64 (no data: prefix), or choose an existing asset with list_images. The upload returns an id for reference_image_id, first_image_id or last_image_id. Images must belong to the account. MCP does not fetch arbitrary external URLs or accept uploaded video files. Completed MP4s are downloaded directly from private object storage, never relayed through MCP or the Go API.

Connect and generate

  1. In your MCP client, add https://tangara.app/mcp. Claude and ChatGPT open the Tangara consent page; approve it to connect. A client with custom header support can use your Tangara account key as a Bearer token instead — never a Runpod or Stripe key.
  2. Call list_models and get_balance, then choose a profile from the returned catalog. Call quote_video for that profile and duration.
  3. After the user approves the quoted price, call generate_video with that exact quote. Keep the request UUID and arguments for any retry.
  4. Poll get_video until result is succeeded or failed. On success, get_video_result returns video_url and a temporary download_url. Open the studio URL while signed into the same account to see the video.

MCP uses the same queue, balance and private video history as the website. A successful submission means the task was queued; it does not mean the MP4 is already ready. An expired download URL can be refreshed with another get_video_result call. Generation failures refund the Tangara balance.

For example, call quote_video with these arguments:

json
{
  "profile_id": "ltx-2.5-1080p-v3",
  "duration_seconds": 5
}

Then pass the approved quote's exact version and amount into generate_video. Replace both placeholders below with those returned values, and generate a new UUID once for this video:

json
{
  "client_request_id": "22222222-2222-4222-8222-222222222222",
  "prompt": "A hummingbird hovering beside a red flower in morning light.",
  "profile_id": "ltx-2.5-1080p-v3",
  "duration_seconds": 5,
  "audio": true,
  "seed": 42,
  "expected_price": {
    "version": "VERSION_FROM_QUOTE",
    "amount": "AMOUNT_FROM_QUOTE"
  }
}

For a LoRA, choose its profile from list_models and include the corresponding lora_id. Ingredients also requires an owned reference_image_id from upload_image or list_images; omit start/end frames. Pixel Upscaler includes the base generation and upscale pass in one quoted task. The current model catalog is the source of truth for available choices.

Image and music generation

Images offer GPT Image 1.5, GPT Image 2, GPT Image 2.5 and Nano Banana. Select the image model and exact profile from the catalog. Generated images remain private to the account. Tasks use the same durable queue and private storage across all interfaces. Paid admission is disabled by default and separately enabled for a verified deployment. Development preview uses MEDIA_PREVIEW_ENABLED=true with APP_ENV=development, BILLING_CHARGING_ENABLED=false and DEMO_MODE=false. The worker needs the gpu-media image, MEDIA_MODELS_ENABLED=1 and verified model caches. Inference uses the shared GPU sequentially with video tasks; it still consumes provider resources even though the preview does not debit users.

Paid admission is separately gated by MEDIA_GENERATION_ENABLED=true, real workers, balance charging enabled and a complete published media tariff. The current media tariff is $0.40 per image or music task (10–120 seconds), including model switching; dimensions do not change the image price. Always read the current quote and accept its exact amount/version before creating work. Preview and paid admission cannot be enabled together.

The browser, REST and MCP create the same durable tasks with the same immutable settings and request IDs. REST uses the instance's /api/v1 base URL and the same Bearer key. Browser pages are /create/image, /create/music and /create/speech. Each catalog model has its own enabled flag; an unmeasured speech tariff does not disable images or music.

MCP tool (when enabled) REST route Purpose
list_media_models GET /media/catalog Inspect availability, profiles, limits and pricing status
quote_image (paid mode) POST /media/image/quote Quote a profile_id; no task or charge
quote_music (paid mode) POST /media/music/quote Quote profile_id and duration_seconds; no task or charge
generate_image POST /media/image Create a private PNG image
quote_speech (when priced) POST /media/speech/quote Quote profile_id and exact prompt text; no task or charge
generate_speech (when enabled) POST /media/speech Chatterbox text-to-speech with explicit language and optional private voice reference
generate_music POST /media/music Create private instrumental music or a song as WAV
list_media GET /media/tasks?kind=image , kind=music or kind=speech Private history, 50 per page; optional offset and search
get_media GET /media/tasks/{id} Accepted settings, progress and measured attempt timings
get_media_result GET /media/tasks/{id}/result Temporary signed download and account-only studio link

During preview, list_media_models returns enabled, preview: true, generation_paused, models, charging_enabled: false and pricing_status: "unmeasured". Preview tasks have price: null. These flags must not be interpreted as a measured zero-dollar price. Existing video history and get_video remain restricted to videos.

Current image models: GPT Image 1.5, GPT Image 2, GPT Image 2.5 and Nano Banana. Each has its own public model page at /models/{model-key}. FLUX is retired: new quotes and new tasks are rejected, while accepted requests can still be confirmed idempotently and existing private history/results remain available.

GPT Image accepts up to 32,000 Unicode prompt characters and 16 distinct, ordered optional reference images. Upload PNG/JPEG/WebP through POST /api/v1/assets or select existing owned images using MCP list_images. No seed is supported: omit it or send seed: 0. Output is one private opaque PNG. Masks, custom pixel sizes, transparency and multiple output samples are not exposed. References add no separate charge to the published per-request price.

Choose an exact profile_id from list_media_models; its quality, resolution (when present), aspect_ratio, width and height determine the immutable settings and quote. Do not construct profile IDs or infer pixel sizes from the resolution label. GPT Image 1.5 offers square/3:2/2:3 and low/medium/high quality. GPT Image 2 offers seven ratios and 1K/2K/4K at low/medium/high. GPT Image 2.5 additionally offers extra-high (xhigh) and maximum (max) quality. Quality labels are model-specific; matching labels do not guarantee matching results across versions. Image 1.5 has an upstream retirement scheduled for December 1, 2026; discover the available versions before starting new work.

Call quote_image (REST POST /media/image/quote) with the chosen profile, then copy its version and amount into expected_price. Each image has a fixed price for its selected model, format, resolution and quality. Prices use $0.001 precision and match across the site, REST and MCP. Representative 1K square/medium prices are $0.040 for GPT Image 1.5, $0.061 for GPT Image 2 and $0.015 for GPT Image 2.5. Other combinations have their own quotes. Accepted task prices never change.

Example MCP generate_image arguments or POST /media/image body:

json
{
  "client_request_id": "33333333-3333-4333-8333-333333333334",
  "prompt": "Keep the person from image 1 and use the room from image 2.",
  "profile_id": "gpt-image-2.5-1k-medium-1x1-v1",
  "reference_image_ids": ["YOUR_FIRST_IMAGE_UUID", "YOUR_SECOND_IMAGE_UUID"],
  "seed": 0,
  "expected_price": {"version": "VERSION_FROM_QUOTE", "amount": "15"}
}

For text-only generation omit reference_image_ids; the same profile supports both modes. Task details/history expose ordered reference_image_ids and generation_config.reference_image_count. Retry with the same request UUID, profile, prompt, reference IDs/order and accepted quote across any interface. Changed inputs require a new UUID. References are ownership checked and originals remain unchanged. Failed generations are refunded. Retrieve images through Tangara asset IDs under the same account permissions as uploaded images.

Current music model: ACE-Step 1.5, prompt up to 512 characters, duration 10–120 whole seconds, stereo 48 kHz PCM16 WAV. Use instrumental: true with no lyrics, or instrumental: false and your own lyrics (up to 4,096 characters). Example generate_music arguments or POST /media/music body:

json
{
  "client_request_id": "44444444-4444-4444-8444-444444444444",
  "prompt": "Gentle acoustic guitar, warm vocals, a calm evening atmosphere.",
  "profile_id": "ace-step-1.5-turbo-v1",
  "duration_seconds": 30,
  "instrumental": false,
  "lyrics": "[Verse]\nThe river carries evening light\nAcross the quiet trees tonight",
  "seed": 42
}

Generate a new UUID once per intended task; examples above are placeholders. Keep it and all arguments unchanged after a timeout or lost response. Concurrent browser, REST and MCP retries confirm the original task. Reusing the UUID with changed arguments returns conflict. A new UUID creates new work. Seed is an integer from 0 to 2147483647 and defaults to zero. Image requests do not accept duration, instrumental or lyrics fields. Neither media type accepts video start/end/reference-sheet fields, LoRAs or the video's audio flag. Only image reference profiles accept reference_image_ids; music rejects them. Preview rejects expected_price. Paid generation requires it: first call the matching quote endpoint/tool, show the resulting price and obtain authorization, then add "expected_price": {"version": "VERSION_FROM_QUOTE", "amount": "AMOUNT_FROM_QUOTE"} to the generation arguments. amount is an integer string in thousandths of USD. Keep this exact accepted quote on retries, including after a tariff change. Missing quotes return quote_required; a stale quote on a new task returns price_changed without charging. Obtain a new quote and authorization before submitting changed arguments with a new UUID.

In paid mode the catalog reports preview: false, charging_enabled: true, pricing_status: "available" and a pricing object with media_rates by profile. Image prices use fixed_amount; music prices use fixed_amount + per_second_amount × duration_seconds, with integer thousandths throughout. The full rate table is archived in the immutable tariff snapshot. A paid task saves its accepted price, debits the balance atomically when queued, and refunds terminal generation failures. Concurrent retries create one task and one charge; insufficient funds returns insufficient_funds without admitting work. Paid media uses the same balance-based admission as paid video, without an active-task limit. Billing history links each task with its kind (video, image, music).

Poll get_media until result is succeeded or failed. Completion returns result_asset_id; get_media_result returns download_url, media_url, mime_type and generation_config. Downloads go directly to private object storage. Pending results return result_not_ready. Other users' task/result IDs return not_found. Completed images also appear in list_images and can be reused as private start/end images for video generation.

Disabling media admission rejects new media submissions with media_unavailable and removes the media MCP tools. Existing media tasks and results remain readable through authenticated REST/browser history. Development preview follows the account's uncharged active-task limit. Prices will be published as an immutable tariff only after real inference and full GPU-cycle costs have been measured.

Check the connection with curl

Normal MCP clients initialize the connection automatically. For a manual check, initialize first, then send the initialized notification and discover tools. None of these requests creates a task or spends your balance.

bash
curl --fail-with-body --silent --show-error 'https://tangara.app/mcp' \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"tangara-quickstart","version":"1"}}}'

curl --fail-with-body --silent --show-error 'https://tangara.app/mcp' \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'
bash
curl --fail-with-body --silent --show-error 'https://tangara.app/mcp' \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

MCP tool errors may arrive with HTTP 200 and result.isError: true; inspect that field as well as HTTP errors. A price_changed error requires a fresh quote and approval; an insufficient_funds error requires a top-up. Both leave the queue and balance unchanged. Do not create another UUID simply because a submission response was lost.

Quick start

This example creates a five-second video from text, without sound. No image is required. First check the currently supported profiles:

bash
curl --fail-with-body --silent --show-error \
  "$TANGARA_API_URL/profiles" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -o profiles.json

jq . profiles.json

Build the request once. Its UUID identifies this particular generation request:

bash
jq -n \
  --arg request_id "$(python3 -c 'import uuid; print(uuid.uuid4())')" \
  --arg profile_id "$(jq -r '.default_profile_id' profiles.json)" \
  '{
    client_request_id: $request_id,
    prompt: "A slow camera move through a sunlit forest, leaves moving gently in the breeze.",
    profile_id: $profile_id,
    duration_seconds: 5,
    audio: false,
    seed: 42
  }' > request.json

curl --fail-with-body --silent --show-error \
  -X POST "$TANGARA_API_URL/tasks" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json \
  -o created-task.json

TASK_ID=$(jq -er '.id' created-task.json)
printf 'Task: %s\n' "$TASK_ID"

A new task returns 201 Created. Retrying the same request returns 200 OK with the same task. If the POST times out, resend request.json unchanged; do not regenerate its UUID. See Retries and limits.

A shortened example response:

json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "client_request_id": "22222222-2222-4222-8222-222222222222",
  "result": "in_progress",
  "stage": "queued",
  "progress_percent": null,
  "attempt_count": 0,
  "result_asset_id": null,
  "error_message": null,
  "retry_at": null
}

Continue with Track generation and Download the MP4.

Preview the price

Accepted quotes refer to an immutable tariff grid. Retrieve any historical grid with GET /pricing/{version}, using task.price.version and the same Bearer key. It includes the complete rates, minimum, currency scale and charging mode. New prices create a new version; existing grids and accepted task quotes remain unchanged. archived_at records archive insertion, not the historical launch date.

GET /profiles includes a pricing catalog shared with the website. Amounts and per-second rates are decimal strings in thousandths of USD (unit: "USD", scale: 1000). Calculate the total as max(minimum_amount, fixed_amount + rates[profile_id] × duration_seconds), using integer math. The current video tariff has minimum_amount: "0" and no fixed per-video surcharge. Videos start at 1 second; the price is the selected rate × duration. For 1080p at $0.04 per second: 1 second costs $0.04, 2 seconds $0.08, 5 seconds $0.20, and 10 seconds $0.40. REST, MCP and the website use this same calculation. fixed_amount is an optional decimal string for historical grids; absent means zero. Uploaded audio adds the published audio-to-video per-second surcharge before multiplying by duration. Automatically generated sound has no surcharge. Sound, reference images and aspect ratio (16:9, 9:16, 1:1) do not change the price.

rates is the ready-to-use per-second price of each listed profile. The catalog also shows how it is composed:

So rates[profile] = base_rates[tier] + option_rates[lora_id][tier] (no surcharge without a LoRA). For example, 1080p Pixel Upscaler is 40 + 16 = 56 thousandths of USD per second. GET /pricing/{version} returns the same base_rates / option_rates for structured grids; older archived grids instead list per-profile rates. Set audio: false to receive an MP4 without an audio track; omitting audio uses the catalog default.

Send the catalog's version and the displayed total as a precondition when creating the task:

json
{
  "expected_price": {
    "version": "COPY_pricing.version_FROM_THE_CATALOG",
    "amount": "800"
  }
}

This example total is for a 20-second 1080p video. Include these fields alongside the ordinary task fields; the server calculates the price independently. If the tariff or amount no longer matches, creation returns 409 price_changed and does not queue a task. Refresh the catalog and obtain confirmation of the new price. For older API clients, expected_price is optional; the server still saves a quote.

Accepted tasks return an immutable price object containing version, amount, unit, scale and charging_enabled. Retrying the identical request retains the original task and quote even if the tariff has since changed. Old tasks have price: null.

When charging_enabled is true, the quoted amount is debited atomically when the task enters the queue. Paid queues have max_active_tasks: 0 (no task-count cap); the available balance limits admission. Insufficient funds return 402 insufficient_funds, without creating a task. Retries keep the original charge. A final generation or upload failure refunds the charge to the Tangara balance. Historical free tasks are never charged retroactively. Enabling charging changes the tariff version, so a previously accepted free preview must be refreshed.

Upload and reuse images

Finished videos and generated images receive a poster_asset_id asynchronously, including videos with an uploaded first frame. Fetch this private JPEG through GET /assets/{poster_asset_id}. Use it for lists instead of downloading original images. The longest edge is at most 640 pixels; aspect ratio is preserved. The poster may initially be null. WebSocket task updates announce its arrival. Posters are not user uploads and are excluded from the image library. Existing finished videos and generated images are processed automatically as well. This CPU background work does not use a GPU or change the original files, task price, or generation parameters. REST and MCP task responses share this optional field.

Images are independent of tasks. Upload each image using multipart field file; the response is an asset object with its id. Files are stored in your private library immediately, even if you have not created a video yet. Originals are preserved.

bash
curl --fail-with-body --silent --show-error \
  -X POST "$TANGARA_API_URL/assets" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -F '[email protected]' \
  -o start-image.json

FIRST_IMAGE_ID=$(jq -er '.id' start-image.json)

Example response, 201 Created:

json
{
  "id": "33333333-3333-4333-8333-333333333333",
  "kind": "image",
  "mime_type": "image/png",
  "size_bytes": 248320,
  "width": 1344,
  "height": 768
}

For an end frame, upload a second file the same way:

bash
curl --fail-with-body --silent --show-error \
  -X POST "$TANGARA_API_URL/assets" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -F '[email protected]' \
  -o end-image.json

LAST_IMAGE_ID=$(jq -er '.id' end-image.json)

Accepted inputs: PNG, JPEG or WebP, up to 20 MiB each, 40 megapixels, and at most 16,384 pixels per side. Send file bytes, not base64 or a remote URL. Let curl set the multipart Content-Type and boundary automatically.

Reuse an existing image by selecting its ID from your library:

bash
curl --fail-with-body --silent --show-error \
  "$TANGARA_API_URL/assets?offset=0" \
  -H "Authorization: Bearer $TANGARA_API_KEY" | jq .

The response contains images and has_more, with up to 24 images per page. Increase offset by 24 while has_more is true. The same image ID can be used in multiple videos. Image uploads do not currently have an idempotency key: repeating an upload creates another asset, so keep its returned ID.

Create a video with images

Create a new request that references the previously uploaded IDs:

bash
jq -n \
  --arg request_id "$(python3 -c 'import uuid; print(uuid.uuid4())')" \
  --arg first_image_id "$FIRST_IMAGE_ID" \
  --arg last_image_id "$LAST_IMAGE_ID" \
  --arg profile_id "$(jq -r '.default_profile_id' profiles.json)" \
  '{
    client_request_id: $request_id,
    prompt: "A smooth cinematic transition from the first scene to the final scene.",
    first_image_id: $first_image_id,
    last_image_id: $last_image_id,
    profile_id: $profile_id,
    duration_seconds: 10,
    audio: false,
    seed: 42
  }' > image-request.json

curl --fail-with-body --silent --show-error \
  -X POST "$TANGARA_API_URL/tasks" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @image-request.json \
  -o created-task.json

TASK_ID=$(jq -er '.id' created-task.json)

For a starting image only, omit last_image_id or set it to null. For text-only generation, omit both image fields. An end frame requires a start frame. Only IDs of your own uploaded images are accepted; upload files before creating the task.

Reference sheet for Ingredients

Ingredients uses one reference-sheet image to guide subjects and setting. Select its profile from GET /profiles or MCP list_models; this mode requires lora_id: "ingredients", reference_image_id and a five-second duration. It cannot be combined with start/end frames. Upload the image through the same REST asset route used for frame images:

bash
curl --fail-with-body --silent --show-error \
  -X POST "$TANGARA_API_URL/assets" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -F '[email protected]' \
  -o reference-image.json

REFERENCE_IMAGE_ID=$(jq -er '.id' reference-image.json)

Quote ltx-2.5-ingredients-448p-v1 for five seconds, then submit the accepted quote to POST /tasks or MCP generate_video:

json
{
  "client_request_id": "REPLACE_WITH_A_NEW_UUID",
  "prompt": "The character in the reference sheet walks through a garden.",
  "profile_id": "ltx-2.5-ingredients-448p-v1",
  "duration_seconds": 5,
  "lora_id": "ingredients",
  "reference_image_id": "REPLACE_WITH_REFERENCE_IMAGE_ID",
  "expected_price": {"version": "VERSION_FROM_QUOTE", "amount": "AMOUNT_FROM_QUOTE"}
}

For an MCP-only workflow, call upload_image with {"data_base64":"BASE64_OF_REFERENCE_PNG"}, then pass its returned id as reference_image_id to generate_video. The same uploaded ID also works through REST, and REST uploads work through MCP. Repeating an upload creates another private image; reuse the returned ID for task retries.

Audio-driven video

Upload your own voice or sound track and generate a video matched to it: lip-sync, timing and motion follow the audio, and the delivered MP4 keeps your track unchanged. The model catalog lists this as audio_input only while it is available; otherwise uploads and requests return 503 audio_to_video_unavailable without a charge.

Upload one WAV, MP3 or M4A file with a single audio track, 1–20 seconds, up to 20 MiB:

bash
curl --fail-with-body --silent --show-error \
  -X POST "$TANGARA_API_URL/audio" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -F '[email protected]' \
  -o audio.json

AUDIO_ID=$(jq -er '.id' audio.json)
SECONDS=$(jq -er '(.duration_ms + 999) / 1000 | floor' audio.json)

GET /audio?offset=0 lists your tracks (24 per page, audio and has_more). Create the task with audio_id and duration_seconds equal to the track length rounded up to a whole second. Use a standard (non-LoRA) profile; a first image is optional, a last image is not supported, and sound stays on. Describe who speaks and the setting in the prompt — the words come from your audio.

json
{
  "client_request_id": "REPLACE_WITH_A_NEW_UUID",
  "prompt": "A young woman on a sunny waterfront talks to the camera, relaxed and natural.",
  "profile_id": "ltx-2.5-1080p-portrait-v1",
  "duration_seconds": 4,
  "audio_id": "REPLACE_WITH_AUDIO_ID",
  "first_image_id": "OPTIONAL_START_IMAGE_ID"
}

The price adds the audio-to-video per-second surcharge from option_rates for the profile's resolution tier. Request it with POST /quote and "audio_input": true. Over MCP use list_audio, quote_video with audio_input, and generate_video with audio_id; upload the file through the studio or REST first.

Seedance 2.5 multimodal references

Choose one of two separate models in GET /models / MCP list_models:

Model Inputs Profiles
bytedance/seedance-2-5 Text and up to 30 images seedance-2.5-{480,720}p-{landscape,portrait,square}-v1
bytedance/seedance-2-5-reference Images, video and audio references seedance-2.5-reference-{480,720}p-{landscape,portrait,square}-v1

Both offer 480p at $0.16/second and 720p at $0.30/second, with 4–30 seconds of requested output. The regular model rejects video/audio references before queueing or charging. Only Reference profiles offer paid input-video seconds. GET /profiles also lists all profiles for compatibility with existing clients. The catalog has 43 profiles: 31 existing LTX/Pixel/Ingredients, six regular Seedance and six Seedance Reference profiles. Tasks, history, accepted prices and refunds belong to the Tangara user across website, REST and MCP.

POST /tasks / MCP generate_video accept these optional ordered collections when a matching Reference profile is selected (regular Seedance accepts only images):

Field Maximum Limits Additional input charge
reference_image_ids 30 Existing private image uploads None
reference_video_ids 10 MP4/MOV, 2–30 seconds each, 30 seconds total, 200 MiB each $0.16/s at 480p or $0.30/s at 720p
reference_audio_ids 10 WAV/MP3, 2–30 seconds each, 30 seconds total, 30 MiB each None

Refer to [Image 1], [Video 1], [Audio 1], etc. in the prompt. Order is preserved in task history and worker requests. Omit LTX's first_image_id, last_image_id, reference_image_id, and audio_id. supports_seed is false: omit seed or use zero; nonzero values are rejected before any task or charge. The provider may reject direct references containing human faces.

For video/audio, call POST /references/upload (MCP prepare_reference_upload) with a new id UUID, kind (video or audio), mime_type, size_bytes, lowercase hex sha256 and base64 md5. MIME types are video/mp4, video/quicktime, audio/wav, audio/mpeg. PUT the file directly to the returned upload_url, using its method and headers. Do not send Tangara authorization/cookies to that URL. Browser-managed Host/Content-Length headers should be omitted from manual headers. Storage uploads are create-only: retrying the same signed URL cannot overwrite a committed object. Keep the upload UUID and metadata unchanged after an uncertain response. Uploading does not charge for generation.

After transfer, call POST /references/complete (MCP complete_reference_upload) with { "id": "UPLOAD_UUID" }. Completion verifies object metadata and probes the private object; the API receives no video bytes. The returned asset includes its verified duration_ms, and video width/height. Video must be 24–60 FPS, each side 300–6000 pixels, aspect ratio 0.4–2.5 and 407,696–8,295,044 pixels in total. Repeated completion returns the same owned asset. GET /references/{id} / MCP get_reference_input retrieves its metadata for reuse. Image references use POST /assets or MCP upload_image as before.

Pass the same reference_video_ids to POST /quote / MCP quote_video and to generate_video. The server measures duration from the uploaded assets, never from a caller duration claim. The quote includes the full amount and its input_video_duration_ms / input_video_amount breakdown. Input milliseconds are summed, then rounded upward once to the ledger's $0.001 unit. At 720p, ten seconds of video reference plus five seconds of output costs $4.50, including $3.00 for input. Use the exact returned version and amount in expected_price. Enqueue captures the complete price once; failure refunds input and output.

When reference video is present, the provider preserves its aspect ratio. The accepted config reports aspect_ratio: "adaptive" and zero width/height rather than claiming fixed output geometry. The returned MP4 preserves provider geometry. This interface currently offers numeric output duration; automatic-duration video editing is not available yet. Prompt enhancement is disabled.

Model capabilities: ByteDance.

Generation settings

Field Required Meaning
client_request_id Yes A UUID for this request; keep it unchanged for retries
prompt Yes 1–4000 characters, after trimming surrounding whitespace
profile_id Yes An ID returned by GET /profiles
first_image_id LTX only Your starting image UUID, or null
last_image_id LTX only Your ending image UUID; requires first_image_id
lora_id For LoRA profiles Explicit choice matching the profile's lora_id: ingredients or pixel-upscaler-x2. Omit for standard generation
audio_id No Your uploaded audio track UUID for audio-driven video; see Audio-driven video
reference_image_id For Ingredients Your uploaded reference-sheet image UUID. Cannot be combined with start/end frames
duration_seconds No Integer from 1 to 20; default 5. Respect profile-specific limits; Ingredients requires 5
audio No true to include audio (default); false for a silent MP4
seed No Integer from 0 to 2147483647; default 0

Use /profiles as the source of supported sizes, defaults, duration limits and FPS. The website, Go API and GPU image share internal/generation/contract.json. contract_id identifies that catalog for diagnostics; it is not an authentication key. Do not send width, height, fps or model directly: unknown JSON fields are rejected. Standard and Pixel Upscaler profiles expose aspect_ratio and resolution (the shorter side in pixels), alongside the exact delivered width and height:

Resolution 16:9 landscape 9:16 portrait 1:1 square
480p 854 × 480 480 × 854 480 × 480
720p 1280 × 720 720 × 1280 720 × 720
1080p 1920 × 1080 1080 × 1920 1080 × 1080
1440p 2560 × 1440 1440 × 2560 1440 × 1440
2160p 3840 × 2160 (4K) 2160 × 3840 (4K) 2160 × 2160

Landscape IDs remain ltx-2.5-{resolution}p-v3; portrait IDs use ltx-2.5-{resolution}p-portrait-v1, square IDs use ltx-2.5-{resolution}p-square-v1. The default is unchanged: ltx-2.5-720p-v3. Prefer selecting by metadata from the current catalog rather than constructing IDs. The studio offers aspect ratio and resolution with one standard model and an optional Pixel Upscaler ×2 enhancement. Existing API LoRA requests and recorded tasks retain their semantics.

MCP uses the same native profiles. For example, choose the profile with aspect_ratio: "9:16", resolution: 1080 and no lora_id from list_models, then pass its ID (ltx-2.5-1080p-portrait-v1) to quote_video and generate_video. No additional aspect-ratio field belongs in the request. The model generates on a portrait canvas; stored task settings and delivered MP4 dimensions are 1080 × 1920. Square 2160p is labelled 2160p, not 4K.

LoRAs are an explicit choice. The catalog's loras describes available adapters; filter profiles by lora_id before choosing a resolution. Standard profiles have no lora_id. LoRA profiles also require the matching lora_id in the create request; choosing a profile alone never implicitly enables an adapter. Adapters can be temporarily disabled during a rollout. In that case they and their profiles/prices are omitted from the catalog, and a direct create request returns 503 lora_unavailable without enqueueing a task or charging the account.

The quoted price covers the complete selected workflow: one task, one debit, including both passes for Pixel Upscaler. The same idempotency and failure-refund rules apply. Read the rate for the selected profile from /profiles.

Current profiles use LTX-2.5 at 24 fps. Availability of a profile does not guarantee an online GPU capable of serving it. Standard tasks share a common queue; LoRA tasks are leased only to workers advertising that specific LoRA profile. The response's generation_config records the settings accepted for that task; its width and height describe the delivered MP4. Internally, the LTX adapter rounds each requested dimension up to a multiple of 64 and removes only that grid padding from decoded frames before encoding. Portrait and square formats are generated on their own portrait/square canvases. All older v2 profiles (512p, 768p, 1088p, 1472p, 2176p) remain accepted with their original dimensions for existing integrations and retries, but are no longer listed in the profile catalog. The removed fixed-duration v1 profile remains unavailable for new requests. With audio: false, the delivered MP4 has no audio track; this does not promise less GPU work.

Seeds and reproducibility

seed controls the initial randomness used by the model. Reusing it helps compare generations, but the seed alone does not identify a video. The prompt, input images, resolution, duration, model weights and inference settings also matter.

Tangara passes the requested seed to LTX. We do not currently guarantee identical frames or identical MP4 bytes between runs, even with the same inputs. GPU kernels, hardware and library versions can affect reproducibility; see the PyTorch reproducibility guide.

To request a new variation, choose another seed and a new client_request_id. To retry an interrupted API request, keep the same client_request_id and request body. That returns the existing task instead of running the model again. To obtain exactly the same completed video, download the original task's result.

Track generation

Read the task by its ID:

bash
curl --fail-with-body --silent --show-error \
  "$TANGARA_API_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  -o task.json

jq '{id, result, stage, progress_percent, attempt_count, retry_at, error_message, result_asset_id}' task.json

result is the authoritative completion state:

Result Meaning
in_progress Queued, generating, waiting to retry or uploading
succeeded Ready; result_asset_id identifies the downloadable MP4
failed Final failure; inspect error_message

stage gives more detail: queued, preparing, generating, uploading, completed or failed. progress_percent may be null, meaning unknown. During generation it describes completed model steps, not elapsed time. Even 100% is not a ready video: decoding and upload can still be running. Wait for result == "succeeded" before downloading.

If a generation attempt is interrupted, the same task can return to queued with retry_at set and a higher attempt_count. Keep tracking the same task. An error_message on an in_progress task can describe a previous attempt; it does not by itself mean final failure.

Every task returned by the website API, REST get/list tasks and MCP get_video / list_videos includes timing:

An execution report (version 1) measures monotonic milliseconds inside the worker: preparation_ms covers input preparation before invoking the generator; generation_ms covers the model call, lazy component loading, decoding and MP4 encoding. It excludes cloud upload and server boot. A report with generation_ms: null records a failure before generation was entered; execution: null means no measurement was recorded. These are different cases. first_generation_after_start identifies the first model invocation in this worker process, not whether the model cache was cold. It is null if generation was never entered. GPU provider identities and internal costs remain admin-only.

The accepted price and its immutable version stay attached to the task; consult list_transactions for actual charges and refunds. Duration measurements never recalculate an accepted price.

Poll every 3–5 seconds, or use WebSocket updates. If you set a client-side timeout, save TASK_ID and resume checking it later. Disconnecting or stopping polling does not cancel the task. When no compatible GPU is online, the task remains queued; the API does not start a GPU server automatically.

To resume without a saved task ID, GET /tasks?offset=0 returns your newest tasks, active_count, max_active_tasks, has_more and generation_paused. Task pages contain up to 50 entries. Images and tasks are shared with your website account. Increase offset by 50 while has_more is true. Add search to find a case-insensitive literal substring in your prompts, including older pages: GET /tasks?search=neon&offset=0. Searches are limited to 200 characters and always remain scoped to your account. Active task counts apply to the whole account, regardless of the search.

Download the MP4

After result becomes succeeded, read result_asset_id from the task response:

bash
RESULT_ASSET_ID=$(jq -er 'select(.result == "succeeded") | .result_asset_id // empty' task.json)

curl --fail --show-error --location \
  --proto '=https' --proto-redir '=https' \
  "$TANGARA_API_URL/assets/$RESULT_ASSET_ID?download=1" \
  -H "Authorization: Bearer $TANGARA_API_KEY" \
  --output video.mp4

The API responds with 307 Temporary Redirect to a short-lived signed R2 URL. Use an up-to-date curl: it strips Authorization when following a redirect to a different host. Do not use --location-trusted. In another HTTP client, explicitly ensure the Tangara key is not forwarded to R2. R2 receives only its signed URL.

Video bytes are downloaded directly from storage. If the temporary URL expires, request /assets/{id} again to receive a fresh one. Keep the permanent asset ID, not the signed URL. ?download=1 adds a download filename; omit it for viewing.

WebSocket updates

Connect from a server or native client to:

text
wss://tangara.app/api/v1/events
Authorization: Bearer <YOUR_API_KEY>

The server sends this notification immediately after connection and whenever your tasks change:

json
{"type":"tasks_changed"}

It is an invalidation notification, not a task snapshot. On each notification, fetch your task with GET /tasks/{id}, or refresh the task list. Multiple changes may be combined into one notification. Reconnect with backoff and re-fetch state after every reconnect so an interrupted connection does not lose progress. Use a WebSocket library that automatically responds to protocol ping frames. The server checks authorization during updates and periodically while connected.

The connection is bound to the key's owner; you do not send a user ID. A revoked key closes the connection. Standard browser WebSocket cannot set an Authorization header: the Tangara website uses its HttpOnly session cookie at /api/events. Never put a personal API key in the WebSocket URL or public frontend code.

Retries and limits

Create one UUID per intended video and persist it together with the exact request body before the first POST. After a timeout or transient server failure, repeat that body with that UUID. This also works if the task was created but its response was lost, or if the account's active-task limit has since been reached.

Changing the prompt, images or settings with an already-used UUID returns 409. A new intended video needs a new UUID. Keep optional fields unchanged on retries: omitting audio and explicitly sending audio: true are different request bodies.

The website and API share an active-task limit. GET /me provides max_active_tasks; GET /tasks also provides active_count. A 429 task_limit means wait for an active task to finish before creating another one. Do not create replacement tasks because generation is slow or an attempt is retrying.

There is currently no public task cancellation, task editing or asset deletion endpoint. Uploading an image again creates a separate asset.

Errors

API errors use JSON with a machine-readable code and readable error:

json
{
  "code": "task_limit",
  "error": "Your active generation limit has been reached"
}
HTTP status Typical reason What to do
400 Invalid prompt, settings, image reference or file Correct the request; check field names and ownership
401 Missing, malformed or revoked API key Copy the current key from your account
402 Insufficient available balance Add funds before submitting a new video
404 Missing resource or another user's resource Check the ID and account
409 Same request UUID with different parameters Retry the original body or use a new UUID for a new video
413 Image too large Use a file within the upload limits
415 JSON Content-Type missing Send Content-Type: application/json for JSON bodies
429 Active-task limit reached Wait for an existing task to finish
500, 503 Transient service/storage failure Retry with backoff; preserve the task request UUID

Errors from a proxy or expired storage URL may not use the API's JSON format. If curl fails, inspect its HTTP status and error body instead of assuming that an empty output file is a successful upload, task or video.

Endpoint reference

Model catalog

GET /models returns {"models": [...]}. Each model entry contains the same profiles and prices as /profiles, plus display_name, description, max_prompt_length, supports_audio, image_inputs and image_constraints. Every image input names its create-request field, whether it is required, its description and any prerequisite field. A LoRA's image_inputs replaces the model's image inputs when present; otherwise it inherits them. LoRA entries also describe their purpose and any specific prompt or price guidance. Profile-level duration limits override the model's duration limits. Catalog descriptions are English; the studio translates the same description keys into its selected language.

The catalog describes choices and constraints, while model-specific code handles conditioning, form behavior and inference. It is not an executable workflow format.

REST routes

All paths below are relative to https://tangara.app/api/v1 and require your key.

Method Path Purpose
GET /me Your account and task limit
GET /profiles Supported generation profiles
GET /models Described model capabilities and current profiles/prices
POST /quote Total price for output and any reference_video_ids; no charge
POST /references/upload Prepare a direct, create-only video/audio reference upload
POST /references/complete Verify a reference upload and measure its duration
GET /references/{id} Retrieve owned reference metadata
POST /assets Upload one original image
POST /audio Upload one audio track for audio-driven video
GET /audio Your audio tracks
GET /assets Your image library
GET /assets/{id} Retrieve an image or video
POST /tasks Create a video task
GET /tasks Your tasks and queue counts
GET /tasks/{id} Task state and result
GET /tasks/{id}/result Signed download URL for a completed video
GET /events WebSocket invalidations
GET /billing Your balance and raw ledger (offset pagination)
GET /billing/transactions Your payment history, linked videos and all-time totals
GET /pricing/{version} The immutable tariff used by a generation
POST /billing/checkout Create a real Stripe Checkout Session
GET /billing/checkout/{id} Read its state

Checkout accepts integer amount_cents ($5–$500) and a UUID request_id. Repeat the same request after a lost response to reuse its session. Follow the returned Stripe URL to pay. Funds are credited only after server verification of a paid live Stripe session; a browser redirect does not prove payment. If payments are not configured, the endpoint returns 503 payments_unavailable. No simulated payment endpoint exists. GET /billing reports availability and charging mode.

Checkout optionally accepts tolt_referral (the ID supplied by Tolt's browser script, not an affiliate's public link code). If the account has no saved referral, the first valid ID is retained; later IDs cannot replace it. Omit this field when there is no referral: subsequent top-ups use the account's saved attribution. Each checkout keeps its original referral snapshot on retries. Malformed IDs are ignored, and the field changes neither price nor payment confirmation. Top-ups reuse one Stripe Customer per Tangara account and remain one-time payments.

Personal payment history

GET /billing/transactions and MCP list_transactions return the same account-only history. Both require your personal Bearer API key. The account is taken from the key; a user_id parameter is not supported. These operations only read data.

sh
curl 'https://tangara.app/api/v1/billing/transactions?kind=capture' \
  -H "Authorization: Bearer $TANGARA_API_KEY"

Optional parameters (also MCP arguments):

Parameter Meaning
kind credit for top-ups, capture for generation charges, refund for returns to your Tangara balance. Omit for all three.
before Copy the string next_before from the previous response to get older entries. Omit for the newest page.

The response contains unit: "USD", scale: 1000, snapshot timestamp at, summary, and entries. Amounts and totals are exact integer strings in thousandths of USD: "640" means $0.64, not $640 or 640 cents.

summary contains all-time credited, charged, refunded, and net_spent (charged - refunded) for your account. Filters and pagination do not change their scope. Read the current available/reserved balance with get_balance or GET /billing.

Each entry has id, sequence (a string), kind, positive amount, reason, and created_at. A refund's original_entry_id identifies its original charge. Generation entries also include task with id, profile_id, generation_config (duration, resolution, audio, seed and optional LoRA), current result/stage, and the original tariff_version when available. Use get_video or GET /tasks/{id} for the full task, and GET /pricing/{version} for its tariff. Top-ups have no task. Provider references and checkout URLs are not returned.

Charges appear when a task enters the queue, so the number of charges can be greater than the number of completed videos. Failed-generation refunds return money to the Tangara balance, not to a bank card. Internal reserves/releases are excluded to avoid counting a charge twice. Free tasks have no charge entry.

Pages contain up to 50 entries, newest first. When next_before is present, keep the same kind and pass that cursor for the next page; when absent, history is exhausted. New transactions do not shift older pages. Each response has its own snapshot, so all-time totals and current task status can change between pages.

MCP tool-call parameters for the first page of charges:

json
{"name":"list_transactions","arguments":{"kind":"capture"}}

For the next page, add "before":"<next_before from the response>" to the arguments. To ask an AI client in plain language: “Show my Tangara payment history, match charges to videos, and show any refunds.” Reading history does not authorize generation, checkout or a refund.

Speech: Chatterbox Multilingual V3

Check models.speech.enabled in list_media_models before offering generation. Supported language codes and the two profiles are published there. The standard profile uses the built-in voice; the profile with voice_reference: true requires audio_id. Upload WAV, MP3 or M4A (1–20 seconds, up to 20 MiB) through POST /audio, or select an owned upload from list_audio. A clear recording of one speaker, in the output language, is recommended.

generate_speech / POST /media/speech accepts:

json
{
  "client_request_id": "<new UUID; preserve it for retries>",
  "profile_id": "chatterbox-multilingual-v3-v1",
  "prompt": "The exact text to speak.",
  "language_id": "en",
  "seed": 42,
  "exaggeration": 0.5,
  "cfg_weight": 0.5,
  "expected_price": {"version": "<quote version>", "amount": "<quote amount>"}
}

prompt is 1–4,000 Unicode characters after trimming outer whitespace. language_id is required. Expressiveness (exaggeration) accepts 0–2 and guidance (cfg_weight) accepts 0–1; both default to 0.5. To use a voice reference, select chatterbox-multilingual-v3-reference-v1 and add the private audio_id. Do not supply music duration/lyrics, image references, video audio flags or LoRAs.

For paid generation, call quote_speech / POST /media/speech/quote with the same profile_id and exact prompt. Price uses per_thousand_characters_amount × character_count / 1000, rounded up once to the ledger's $0.001 precision. No fixed speech fee or cold-start surcharge. Never substitute the image/music rate. Supply the accepted price on generation; preview omits expected_price and never represents a measured free tariff.

Use get_media, list_media with kind: "speech", and get_media_result for status, history and private download. Successful speech is mono 24 kHz PCM16 WAV, with Chatterbox's built-in watermark. Long text is processed in bounded chunks; reaching the model's output limit fails the task instead of publishing a silently truncated result. Voice conditioning is reset between tasks. Accepted text, language, voice asset, conditioning settings, seed and price are immutable.

The initial measured speech tariff is $0.26 per 1,000 Unicode characters for both speech profiles. It uses the exact trimmed text length, with one upward rounding to $0.001 for the whole request and no fixed fee. Always obtain a fresh quote instead of hard-coding this rate; previous requests retain their accepted immutable tariff.

Saved generation-time estimates

Video, image, music and speech tasks returned by create/get/list operations now include estimated_generation_seconds (integer or null) and generation_estimate (object or null). The website and MCP generate_video, generate_image, generate_music, generate_speech, get_video, get_media, list_videos and list_media use the same stored fields.

json
{
  "estimated_generation_seconds": 66,
  "generation_estimate": {
    "seconds": 66,
    "version": "generation-v1/2026-10-06",
    "source": "benchmark",
    "method": "exact",
    "sample_count": 2
  }
}

The example is illustrative. source is benchmark or recent_history; method is exact, interpolated or scaled. An exact length match is still an approximation. The estimate is captured once when a task is accepted, survives retries and is retained after completion for comparison with timing.generation_ms. It excludes waiting, startup and upload; it is not an ETA, countdown, quote or timeout. null means unknown, including old tasks. Do not send these output-only fields in generation requests. See the estimated backlog section in docs/monitoring.md for admin/launcher aggregation.

Nano Banana images

list_media_models / GET /api/v1/media/catalog includes the additional nano-banana image model alongside the GPT Image versions. Its profiles have kind: image, a specific aspect_ratio, and optional_references: true: use the same profile with zero to three ordered private reference_image_ids. All ten supported aspect ratios are available. seed must be zero because this model offers no seed control. Outputs are private PNG images and appear in the existing image history and list_images, ready to reuse as references.

Call quote_image / POST /api/v1/media/image/quote with the selected profile, then pass the returned immutable expected_price to generate_image / POST /api/v1/media/image. The price is $0.045 per image, including reference inputs. Failed generations receive the same automatic refund as other media. Retries must retain the same client_request_id and body; they do not pay twice.

Upscalers

Upscale existing private images or videos without a prompt. The same account, API key, balance and task ownership rules apply. Failed jobs are refunded.

  1. GET /api/v1/upscalers/catalog (MCP list_upscalers) lists profiles and prices.
  2. For images, use an owned image asset or POST /api/v1/assets. For videos, prepare a direct private upload with POST /api/v1/references/upload, kind: "upscale_video", then complete it through /references/complete. Video bytes go directly to private object storage. MP4/MOV up to 500 MiB and 80 seconds are accepted at upload; the chosen output profile may be shorter.
  3. POST /api/v1/upscalers/quote (MCP quote_upscale) accepts only profile_id and asset_id; measured server metadata determines the price.
  4. After user authorization, POST /api/v1/upscalers/tasks (MCP upscale_media) accepts the same fields plus a new client_request_id UUID and the exact expected_price object. Reuse all inputs and the UUID on uncertain retries.
  5. Poll GET /api/v1/upscalers/tasks/{id} (MCP get_upscale), then request /api/v1/upscalers/tasks/{id}/result (MCP get_upscale_result) for a private download_url. The URL expires; request it again when needed.
json
{
  "profile_id": "real-esrgan-2x-v1",
  "asset_id": "OWNED_IMAGE_UUID"
}

Image profiles: real-esrgan-2x-v1, real-esrgan-4x-v1. Output is PNG at exactly 2× or 4× both input dimensions, up to 40 MP and 16,384 pixels per side. Each started 1024×1024 input pixels is billed once: $0.011 for ×2, $0.017 for ×4.

Video profiles: p-video-upscale-{target}-{fps}fps-v1, where target is 720p, 1080p, 2k or 4k, and fps is 30 or 60. The original aspect ratio and sound are preserved; increasing FPS requests frame interpolation. At 30 FPS, rates are $0.013/$0.026/$0.052/$0.104 per second, respectively; 60 FPS doubles these rates. Measured input duration rounds up once to whole seconds. Maximum length at 30 FPS: 80/40/20/10 seconds; at 60 FPS: 40/20/10/5 seconds. A clip exceeding its profile's limit is rejected before debit, not truncated. Always use the live catalog and quote rather than hard-coding commercial prices.