`POST /v1/conversations`

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

Request example#

curl -X POST 'https://platform.tongai.io/v1/conversations' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "entrypoint": "assistant",  "mode": "guided"}'

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.

assistant:runcredits:spend

Parameters#

Idempotency-KeystringRequired

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

Request body#

application/json

entrypointstringRequired

Allowed values"assistant""filmmaker"

modestringRequired

Guided runs pause for human review in Tong. Automatic runs continue. Both charge as work proceeds and pause when credits run out.

Allowed values"guided""automatic"

titlestringOptional

Maximum length: 100 characters.

project_idstringOptional

A 24-character hexadecimal ID.

model_preferencesobjectOptional

Show nested fields

imagestring | nullRequired

Use letters, numbers, underscores, periods, colons, slashes or hyphens.

Minimum length: 1 characters.

Maximum length: 150 characters.

videostring | nullRequired

Use letters, numbers, underscores, periods, colons, slashes or hyphens.

Minimum length: 1 characters.

Maximum length: 150 characters.

sourceobjectOptional

Show nested fields

kindstringRequired

Allowed values"director""text"

idstringRequired

A 24-character hexadecimal ID.

Response schema#

Response

JSON

{}

`HTTP 201`

application/json

object

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.