Submit a generation

tong_generation_submit

Submit the configured action using your Tong account and credits. Follow the saved operation until it finishes.

POST/v1/tools/tong_generation_submit/operations

Request example#

curl -X POST 'https://platform.tongai.io/v1/tools/tong_generation_submit/operations' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "input": {    "params": {      "id": "000000000000000000000001"    },    "body": {      "quoteId": "fixture-image-quote-token",      "prompt": "A quiet street at blue hour",      "operation": "TEXT_TO_IMAGE",      "inputAssetIds": [],      "parameters": {        "textToImageModel": "tong_ea55aff4f3b5c8aba3a35569",        "ratio": "16:9"      }    }  }}'

Configuration

curl --version

Permissions#

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

Request body#

REST requests wrap the tool arguments in input. MCP calls send the same arguments directly.

paramsobjectRequired

Show nested fields

idstringRequired

A 24-character hexadecimal ID.

Example"000000000000000000000001"

bodyobjectRequired

Show nested fields

quoteIdstringRequired

Use the quote submission value returned for this exact configuration.

Minimum length: 1 characters.

Maximum length: 120 characters.

Example"fixture-image-quote-token"

promptstringRequired

Describe the result you want to create.

Minimum length: 1 characters.

Maximum length: 5000 characters.

Example"A quiet street at blue hour"

operationstringRequired

Select the workflow supported by the chosen model.

Allowed values"TEXT_TO_IMAGE""IMAGE_EDIT""CHARACTER_RECREATE""CHARACTER_RECREATE_SPICY""TEXT_TO_VIDEO""IMAGE_TO_VIDEO""CHARACTER_TO_VIDEO""CHARACTER_TO_VIDEO_SPICY""FIRST_LAST_TO_VIDEO"

Example"TEXT_TO_IMAGE"

inputAssetIdsstring[]Required

Maximum items: 120.

Example[]

parametersobjectRequired

Show nested fields

directorRequiredReferenceCountintegerOptional

Minimum: 1.

Maximum: 20.

referenceDirectionobjectOptional

Show nested fields

versionnumberRequired

Allowed values1

capabilityRevisionstringRequired

Minimum length: 1 characters.

Maximum length: 100 characters.

keepVideoSoundbooleanOptional

seedintegerOptional

Minimum: 0.

Maximum: 2147483647.

automaticShotsbooleanOptional

automaticDurationbooleanOptional

outputResolutionstringOptional

Allowed values"720p-SR""1080p-SR""1440p-SR"

bitratestringOptional

Allowed values"standard""high"

returnLastFramebooleanOptional

documentUrlstringOptional

Format: uri.

Maximum length: 2048 characters.

subjectSequenceintegerOptional

Minimum: 0.

Maximum: 999.

subjectsobject[]Optional

Maximum items: 6.

Show nested fields

idstringRequired

Use a numbered subject label, for example Subject1.

namestringRequired

Minimum length: 1 characters.

Maximum length: 80 characters.

descriptionstringOptional

Maximum length: 500 characters.

assetIdsstring[]Required

Minimum items: 1.

Maximum items: 4.

shotsobject[]Optional

Minimum items: 1.

Maximum items: 6.

Show nested fields

idstringRequired

Minimum length: 1 characters.

Maximum length: 80 characters.

promptstringRequired

Describe the result you want to create.

Minimum length: 1 characters.

Maximum length: 1800 characters.

durationSecondsintegerRequired

Minimum: 1.

Maximum: 15.

referencesobject[]Required

Use owned asset IDs that satisfy the selected model’s reference capabilities.

Maximum items: 120.

Show nested fields

idstringRequired

Minimum length: 1 characters.

Maximum length: 80 characters.

assetIdstringRequired

Use the identifier of an asset owned by the authorized account.

A 24-character hexadecimal ID.

fieldstringRequired

Minimum length: 1 characters.

Maximum length: 80 characters.

labelstringRequired

Use a numbered reference label, for example Image1.

autoEnhancePromptbooleanOptional

promptEnhancementIdstringOptional

A 24-character hexadecimal ID.

negativePromptModestringOptional

Allowed values"REPLACE"

cameraMotionstringOptional

Allowed values"AUTO""ORBIT_RIGHT""ORBIT_LEFT""PUSH_IN""PULL_BACK""RISE"

qualityPresetstringOptional

Allowed values"REALISTIC""DRAFT"

casualPhoneFinishbooleanOptional

recreateReferenceRolesstring[]Optional

Minimum items: 2.

Maximum items: 20.

characterVideoReferenceRolesstring[]Optional

Minimum items: 1.

Maximum items: 30.

imageModelstringOptional

Minimum length: 1 characters.

Maximum length: 150 characters.

textToImageModelstringOptional

Minimum length: 1 characters.

Maximum length: 150 characters.

Example"tong_ea55aff4f3b5c8aba3a35569"

videoModelstringOptional

Minimum length: 1 characters.

Maximum length: 150 characters.

durationSecondsintegerOptional

Minimum: 2.

Maximum: 30.

resolutionstringOptional

Allowed values"480p""720p""768p""1080p""2k""4k"

ratiostringOptional

Allowed values"21:9""16:9""4:3""1:1""3:4""9:16""adaptive"

Example"16:9"

videoStylestringOptional

Allowed values"NATURAL_PHONE""CINEMATIC""FOLLOW_PROMPT"

generateAudiobooleanOptional

seedintegerOptional

Minimum: 0.

Maximum: 2147483647.

promptExtendbooleanOptional

negativePromptstringOptional

Maximum length: 2000 characters.

workspaceProjectIdstring | nullOptional

A 24-character hexadecimal ID.

characterProfileIdstringOptional

A 24-character hexadecimal ID.

annotationsobject[]Optional

Maximum items: 8.

Show nested fields

xnumberRequired

Minimum: 0.

Maximum: 1.

ynumberRequired

Minimum: 0.

Maximum: 1.

radiusnumberRequired

Minimum: 0.02.

Maximum: 0.5.

commentstringRequired

Minimum length: 1 characters.

Maximum length: 500 characters.

filmSceneobjectOptional

Show nested fields

projectIdstringRequired

Use the identifier of a project owned by the authorized account.

A 24-character hexadecimal ID.

shotIdstringRequired

Use letters, numbers, underscores or hyphens.

Minimum length: 1 characters.

Maximum length: 120 characters.

revisionintegerRequired

Minimum: 0.

Maximum: 9007199254740991.

filmReferenceobjectOptional

Show nested fields

projectIdstringRequired

Use the identifier of a project owned by the authorized account.

A 24-character hexadecimal ID.

entityIdstringRequired

Use letters, numbers, underscores or hyphens.

Minimum length: 1 characters.

Maximum length: 120 characters.

revisionintegerRequired

Minimum: 0.

Maximum: 9007199254740991.

Request headers#

HTTP

Authorization: Bearer $TONG_API_KEYContent-Type: application/jsonIdempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03

Keep one UUID for each intended action and reuse it after a timeout or retry. A different input with the same UUID is rejected.

Response fields#

An accepted request is not a finished generation. Track the saved job until its output is ready.

Response

Accepted means the request was saved. Read its operation to follow execution.

JSON

{  "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",  "tool": "tong_generation_submit",  "category": "generation",  "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": null,  "detail_expired": false,  "timing": {    "dispatch_started_at": null,    "acknowledged_at": null,    "completed_at": null,    "dispatch_acknowledgement_ms": null,    "end_to_end_ms": null  },  "review": null,  "result": null,  "error": null,  "billing": {    "status": "pending",    "usage_credits": "0.000000",    "wallet_debited_credits": "0.000000"  }}

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.

Requests and logsAn accepted request is not a finished generation. Track the saved job until its output is ready.Credits and billingFollow quoted prices, actual usage and settled customer credits.

MCP call#

JSON

{  "jsonrpc": "2.0",  "id": 1,  "method": "tools/call",  "params": {    "name": "tong_generation_submit",    "arguments": {      "params": {        "id": "000000000000000000000001"      },      "body": {        "quoteId": "fixture-image-quote-token",        "prompt": "A quiet street at blue hour",        "operation": "TEXT_TO_IMAGE",        "inputAssetIds": [],        "parameters": {          "textToImageModel": "tong_ea55aff4f3b5c8aba3a35569",          "ratio": "16:9"        }      }    },    "_meta": {      "io.tongai/idempotency-key": "45be69f1-c266-4a09-a82c-bf3c6303eb03"    }  }}

REST requests wrap the tool arguments in input. MCP calls send the same arguments directly.

Response

JSON

{  "jsonrpc": "2.0",  "id": 1,  "result": {    "structuredContent": {      "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",      "tool": "tong_generation_submit",      "category": "generation",      "channel": "mcp",      "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": null,      "detail_expired": false,      "timing": {        "dispatch_started_at": null,        "acknowledged_at": null,        "completed_at": null,        "dispatch_acknowledgement_ms": null,        "end_to_end_ms": null      },      "review": null,      "result": null,      "error": null,      "billing": {        "status": "pending",        "usage_credits": "0.000000",        "wallet_debited_credits": "0.000000"      }    },    "content": [      {        "type": "text",        "text": "{\"id\":\"e8aa0a87-6cd9-42eb-975a-b72bf43218c8\",\"tool\":\"tong_generation_submit\",\"category\":\"generation\",\"channel\":\"mcp\",\"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\":null,\"detail_expired\":false,\"timing\":{\"dispatch_started_at\":null,\"acknowledged_at\":null,\"completed_at\":null,\"dispatch_acknowledgement_ms\":null,\"end_to_end_ms\":null},\"review\":null,\"result\":null,\"error\":null,\"billing\":{\"status\":\"pending\",\"usage_credits\":\"0.000000\",\"wallet_debited_credits\":\"0.000000\"}}"      }    ]  }}

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.

Errors and rate limitsUnderstand error responses, retry safely and recover from failed generations.IdempotencyKeep one UUID for each intended action and reuse it after a timeout or retry. A different input with the same UUID is rejected.

Reuse a generationPrepare an owned source for the next step in this workflow.Quote a generationGet a quote for the exact model, inputs and configuration before submitting the action.Quote an alternativeGet a quote for the exact model, inputs and configuration before submitting the action.Generate an alternativeSubmit the configured action using your Tong account and credits. Follow the saved operation until it finishes.Retry a generationSubmit the configured action using your Tong account and credits. Follow the saved operation until it finishes.Get enhanced promptRead the selected owned resource or current workflow state without starting a new generation.

Submit a generation

Request example#

Permissions#

Request body#

Request headers#

Response fields#

MCP call#

Response

Errors and limits#

Related tools#