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).
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.
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
- 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. - Call
list_modelsandget_balance, then choose a profile from the returned catalog. Callquote_videofor that profile and duration. - After the user approves the quoted price, call
generate_videowith that exact quote. Keep the request UUID and arguments for any retry. - Poll
get_videountilresultissucceededorfailed. On success,get_video_resultreturnsvideo_urland a temporarydownload_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:
{
"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:
{
"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:
{
"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:
{
"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.
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"}'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:
curl --fail-with-body --silent --show-error \
"$TANGARA_API_URL/profiles" \
-H "Authorization: Bearer $TANGARA_API_KEY" \
-o profiles.json
jq . profiles.jsonBuild the request once. Its UUID identifies this particular generation request:
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:
{
"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:
base_rates— per-second price for each resolution tier ("480","720","1080","1440","2160"). A profile uses the largest tier not above the short side of its delivered video.option_rates— per-second surcharge for an optional capability, per tier. Keys are option IDs such as the LoRA IDspixel-upscaler-x2andingredients.
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:
{
"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.
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:
{
"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:
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:
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:
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:
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:
{
"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:
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.
{
"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.
ingredients:ltx-2.5-ingredients-448p-v1, 768 × 448, 5 seconds. Upload one reference sheet containing the characters, objects and setting. Describe the references and the desired action in the prompt. It is not a first-frame image.pixel-upscaler-x2:ltx-2.5-{480,720,1080,1440,2160}p-pixel-upscaler-v1. These are the landscape IDs. Portrait and square IDs useltx-2.5-{resolution}p-portrait-pixel-upscaler-v1andltx-2.5-{resolution}p-square-pixel-upscaler-v1. All five resolutions support all three shapes in the table above, at the same per-resolution price. REST and MCP select the profile and explicitly passlora_id: "pixel-upscaler-x2". The base video is generated on the matching canvas at half the final linear resolution; the upscale preserves that canvas and crops only padding, without stretching or rotating a landscape video. Creates a smaller video from the prompt and optional start/end images, then automatically runs the creative ×2 upscaler. The profile describes the final dimensions. Fine details may change; this is not a faithful restoration tool. There is no external video upload. Original generated audio is retained.
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:
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.jsonresult 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:
total_ms: submission to terminal result, including queue, retries and storage;nullwhile unfinished.preparation_msandgeneration_ms: sums across all attempts, including failed attempts. They arenullif any attempt has no worker measurement or generation is still underway. An empty queue entry is not a zero-cost result.measured_attemptsandattempts: coverage and per-attempt status, timestamps,artifact_ready_atand optionalexecutionreport.
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:
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.mp4The 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:
wss://tangara.app/api/v1/events
Authorization: Bearer <YOUR_API_KEY>The server sends this notification immediately after connection and whenever your tasks change:
{"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:
{
"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.
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:
{"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:
{
"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.
{
"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.
GET /api/v1/upscalers/catalog(MCPlist_upscalers) lists profiles and prices.- For images, use an owned image asset or
POST /api/v1/assets. For videos, prepare a direct private upload withPOST /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. POST /api/v1/upscalers/quote(MCPquote_upscale) accepts onlyprofile_idandasset_id; measured server metadata determines the price.- After user authorization,
POST /api/v1/upscalers/tasks(MCPupscale_media) accepts the same fields plus a newclient_request_idUUID and the exactexpected_priceobject. Reuse all inputs and the UUID on uncertain retries. - Poll
GET /api/v1/upscalers/tasks/{id}(MCPget_upscale), then request/api/v1/upscalers/tasks/{id}/result(MCPget_upscale_result) for a privatedownload_url. The URL expires; request it again when needed.
{
"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.