`POST /v1/videos/generations`

Use the documented request fields and permissions for this HTTP endpoint.

Request example#

curl -X POST 'https://platform.tongai.io/v1/videos/generations' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "quote_id": "example",  "media_conversation_id": "aaaaaaaaaaaaaaaaaaaaaaaa",  "prompt": "A quiet street at blue hour",  "parameters": {}}'

Configuration

curl --version

Authentication#

Use a server-side API key for your account, or OAuth for each customer’s account. Never send keys in prompts or tool arguments.

generation:writecredits:spend

Parameters#

Idempotency-KeystringRequired

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

Request body#

application/json

quote_idstringRequired

Use letters, numbers or hyphens.

Minimum length: 1 characters.

Maximum length: 120 characters.

media_conversation_idstringRequired

A 24-character hexadecimal ID.

promptstringRequired

Describe the result you want to create.

Minimum length: 1 characters.

Maximum length: 32000 characters.

input_asset_idsstring[]Optional

Maximum items: 30.

Default: [].

parametersobjectRequired

workspace_project_idstringOptional

A 24-character hexadecimal ID.

Response schema#

Response

JSON

{  "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",  "tool": "example",  "category": "example",  "channel": "api",  "state": "queued",  "status": "accepted",  "stage": "admission",  "dispatch_status": "pending",  "created_at": "2026-10-22T09:00:00.000Z",  "updated_at": "2026-10-22T09:00:00.000Z",  "detail_expires_at": "2026-10-22T09:00:00.000Z",  "detail_expired": false,  "timing": {    "dispatch_started_at": "2026-10-22T09:00:00.000Z",    "acknowledged_at": "2026-10-22T09:00:00.000Z",    "completed_at": "2026-10-22T09:00:00.000Z",    "dispatch_acknowledgement_ms": 0,    "end_to_end_ms": 0  },  "review": null,  "result": null,  "error": {    "code": "example"  },  "billing": {    "status": "none",    "usage_credits": "0.000000",    "wallet_debited_credits": "0.000000"  }}

`HTTP 202`

application/json

idstringRequired

The unique ID of the saved operation.

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringRequired

categorystringRequired

channelstringRequired

Allowed values"api""mcp"

statestringRequired

The current execution state of the saved work.

Allowed values"queued""running""waiting""needs_review""paused""reconciling""succeeded""failed""cancelled"

statusstringRequired

The overall status to use when tracking the operation.

Allowed values"accepted""running""needs_review""paused""reconciling""succeeded""failed""cancelled"

stagestringRequired

The current phase of the operation.

Allowed values"admission""dispatch""review""generation""reconciliation""complete"

dispatch_statusstringRequired

Whether the tool accepted the request. An acknowledgement does not mean generation is complete.

Allowed values"pending""unknown""acknowledged"

created_atstringRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

updated_atstringRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

detail_expires_atstring | nullRequired

When stored operation details expire. A null value means no expiry is currently set.

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

detail_expiredbooleanRequired

Whether the stored operation details have expired.

timingobjectRequired

Timestamps and elapsed times for tracking this operation.

Show nested fields

dispatch_started_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

acknowledged_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

completed_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

dispatch_acknowledgement_msnumber | nullRequired

Minimum: 0.

end_to_end_msnumber | nullRequired

Minimum: 0.

reviewJSON | nullRequired

Review information when the operation needs human input; otherwise null.

resultJSON | nullRequired

The output returned by this tool, or null while no output is available.

errorobject | nullRequired

The public error code if the operation failed; otherwise null.

Show nested fields

codestringRequired

billingobjectRequired

Customer credit usage and wallet charges. Output readiness and billing settlement are separate.

Show nested fields

statusstringRequired

Allowed values"none""pending""settled""released""reconciling"

usage_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

wallet_debited_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

released_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

refunded_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

unfunded_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

pending_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

tokensobjectOptional

Show nested fields

inputnumberOptional

Minimum: 0.

outputnumberOptional

Minimum: 0.

cachednumberOptional

Minimum: 0.

cache_writenumberOptional

Minimum: 0.

componentsobject[]Optional

Show nested fields

idstringOptional

source_idstringRequired

toolstringRequired

modelstring | nullRequired

channelstringRequired

Allowed values"api""mcp"

credential_idstringRequired

kindstringRequired

Allowed values"text_pool""reasoning""generation"

usage_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

wallet_debited_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

evidence_atstringOptional

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

updated_atstringOptional

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

quoteobjectOptional

The quoted configuration, price and submission values, when a quote is available.

Show nested fields

idstringRequired

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

operation_idstringRequired

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringRequired

operationstring | nullRequired

modelstring | nullRequired

configurationobjectRequired

submit_valuestringRequired

submit_fieldstringRequired

quoted_creditsstring | nullRequired

A decimal string with six decimal places, for example 1.250000.

expires_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

Errors and limits#

HTTP	Error	Recovery
`400`	Invalid request`REQUEST_INVALID`	Correct the fields identified by the error before trying again.
`401`	Invalid credential`CREDENTIAL_INVALID`	Check the credential, its expiry and whether it has been revoked.
`402`	Insufficient credits`INSUFFICIENT_CREDITS`	Add credits to the account that owns the credential, then continue the saved work.
`403`	Permission denied`SCOPE_REQUIRED`	Use a credential with the required scopes and access to the selected resource.
`404`	Resource unavailable`RESOURCE_UNAVAILABLE`	Check the resource ID and that it belongs to the authorized account.
`409`	Intent conflict`IDEMPOTENCY_CONFLICT`	Reuse an intent only with its original request. Use a new UUID for a different action.
`429`	Rate limited`RATE_LIMITED`	Wait for Retry-After before retrying the same intended request.
`503`	Temporarily unavailable`DEPENDENCY_UNAVAILABLE`	Wait for Retry-After and retry with the same intent. Check the saved operation after a timeout.

AuthenticationAPI keys charge the account that owns the key. OAuth lets each connected user use their own credits.Errors and rate limitsUnderstand error responses, retry safely and recover from failed generations.Requests and logsAn accepted request is not a finished generation. Track the saved job until its output is ready.