`POST /v1/filmmaker/runs`

Usa los campos de solicitud y permisos documentados para este endpoint HTTP.

Ejemplo de solicitud#

curl -X POST 'https://platform.tongai.io/v1/filmmaker/runs' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "message": "A quiet street at blue hour"}'

Configuración

curl --version

Autenticación#

Usa una clave API en tu servidor para tu cuenta, u OAuth para la cuenta de cada cliente. Nunca envíes claves en instrucciones ni argumentos.

filmmaker:runcredits:spend

Parámetros#

Idempotency-KeystringObligatorio

Un UUID, por ejemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

Cuerpo de solicitud#

application/json

messagestringObligatorio

Describe el resultado que quieres crear.

Longitud mínima: 1 caracteres.

Longitud máxima: 32000 caracteres.

attachmentsstring[]Opcional

Usa IDs de recursos propios compatibles con las capacidades de referencia del modelo elegido.

Elementos máximos: 30.

Valor predeterminado: [].

reference_bindingsobject[]Opcional

Elementos máximos: 30.

Mostrar campos anidados

labelstringObligatorio

Usa una etiqueta de referencia numerada, por ejemplo Image1.

assetIdstringObligatorio

Usa el identificador de un recurso de la cuenta autorizada.

Un ID hexadecimal de 24 caracteres.

modestringOpcional

Las ejecuciones guiadas esperan revisión humana en Tong. Las automáticas continúan. Ambas cobran según avanzan y se pausan sin créditos.

Valores permitidos"guided""automatic"

Valor predeterminado: "guided".

conversation_idstringOpcional

Un UUID, por ejemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

model_preferencesobjectOpcional

Mostrar campos anidados

imagestring | nullObligatorio

Usa letras, números, guiones bajos, puntos, dos puntos, barras o guiones.

Longitud mínima: 1 caracteres.

Longitud máxima: 150 caracteres.

videostring | nullObligatorio

Usa letras, números, guiones bajos, puntos, dos puntos, barras o guiones.

Longitud mínima: 1 caracteres.

Longitud máxima: 150 caracteres.

sourceobjectOpcional

Mostrar campos anidados

kindstringObligatorio

Valores permitidos"director""text"

idstringObligatorio

Un ID hexadecimal de 24 caracteres.

Esquema de respuesta#

Respuesta

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

idstringObligatorio

El ID único de la operación guardada.

Un UUID, por ejemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringObligatorio

categorystringObligatorio

channelstringObligatorio

Valores permitidos"api""mcp"

statestringObligatorio

El estado de ejecución actual del trabajo guardado.

Valores permitidos"queued""running""waiting""needs_review""paused""reconciling""succeeded""failed""cancelled"

statusstringObligatorio

El estado general para seguir la operación.

Valores permitidos"accepted""running""needs_review""paused""reconciling""succeeded""failed""cancelled"

stagestringObligatorio

La fase actual de la operación.

Valores permitidos"admission""dispatch""review""generation""reconciliation""complete"

dispatch_statusstringObligatorio

Indica si la herramienta aceptó la solicitud. La confirmación no significa que la generación haya terminado.

Valores permitidos"pending""unknown""acknowledged"

created_atstringObligatorio

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

updated_atstringObligatorio

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

detail_expires_atstring | nullObligatorio

Cuándo caducan los detalles guardados. Un valor null indica que no hay caducidad establecida.

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

detail_expiredbooleanObligatorio

Indica si los detalles guardados han caducado.

timingobjectObligatorio

Marcas de tiempo y tiempos transcurridos para seguir esta operación.

Mostrar campos anidados

dispatch_started_atstring | nullObligatorio

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

acknowledged_atstring | nullObligatorio

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

completed_atstring | nullObligatorio

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

dispatch_acknowledgement_msnumber | nullObligatorio

Mínimo: 0.

end_to_end_msnumber | nullObligatorio

Mínimo: 0.

reviewJSON | nullObligatorio

Información de revisión cuando se requiere intervención humana; en otro caso, null.

resultJSON | nullObligatorio

El resultado de esta herramienta, o null si aún no está disponible.

errorobject | nullObligatorio

El código de error público si la operación falló; en otro caso, null.

Mostrar campos anidados

codestringObligatorio

billingobjectObligatorio

Uso de créditos y cargos de la cartera. La disponibilidad del resultado y la liquidación son independientes.

Mostrar campos anidados

statusstringObligatorio

Valores permitidos"none""pending""settled""released""reconciling"

usage_creditsstringObligatorio

Una cadena decimal con seis decimales, por ejemplo 1.250000.

wallet_debited_creditsstringObligatorio

Una cadena decimal con seis decimales, por ejemplo 1.250000.

released_creditsstringOpcional

Una cadena decimal con seis decimales, por ejemplo 1.250000.

refunded_creditsstringOpcional

Una cadena decimal con seis decimales, por ejemplo 1.250000.

unfunded_creditsstringOpcional

Una cadena decimal con seis decimales, por ejemplo 1.250000.

pending_creditsstringOpcional

Una cadena decimal con seis decimales, por ejemplo 1.250000.

tokensobjectOpcional

Mostrar campos anidados

inputnumberOpcional

Mínimo: 0.

outputnumberOpcional

Mínimo: 0.

cachednumberOpcional

Mínimo: 0.

cache_writenumberOpcional

Mínimo: 0.

componentsobject[]Opcional

Mostrar campos anidados

idstringOpcional

source_idstringObligatorio

toolstringObligatorio

modelstring | nullObligatorio

channelstringObligatorio

Valores permitidos"api""mcp"

credential_idstringObligatorio

kindstringObligatorio

Valores permitidos"text_pool""reasoning""generation"

usage_creditsstringObligatorio

Una cadena decimal con seis decimales, por ejemplo 1.250000.

wallet_debited_creditsstringObligatorio

Una cadena decimal con seis decimales, por ejemplo 1.250000.

evidence_atstringOpcional

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

updated_atstringOpcional

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

quoteobjectOpcional

La configuración, el precio y los valores de envío cuando hay una cotización.

Mostrar campos anidados

idstringObligatorio

Un UUID, por ejemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

operation_idstringObligatorio

Un UUID, por ejemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringObligatorio

operationstring | nullObligatorio

modelstring | nullObligatorio

configurationobjectObligatorio

submit_valuestringObligatorio

submit_fieldstringObligatorio

quoted_creditsstring | nullObligatorio

Una cadena decimal con seis decimales, por ejemplo 1.250000.

expires_atstring | nullObligatorio

Fecha y hora ISO 8601, por ejemplo 2026-10-22T09:00:00Z.

Errores y límites#

HTTP	Error	Recuperación
`400`	Solicitud no válida`REQUEST_INVALID`	Corrige los campos indicados por el error antes de reintentar.
`401`	Credencial no válida`CREDENTIAL_INVALID`	Comprueba la credencial, su vencimiento y si fue revocada.
`402`	Créditos insuficientes`INSUFFICIENT_CREDITS`	Añade créditos a la cuenta de la credencial y continúa el trabajo guardado.
`403`	Permiso denegado`SCOPE_REQUIRED`	Usa una credencial con los permisos necesarios y acceso al recurso seleccionado.
`404`	Recurso no disponible`RESOURCE_UNAVAILABLE`	Comprueba el ID del recurso y que pertenezca a la cuenta autorizada.
`409`	Conflicto de intención`IDEMPOTENCY_CONFLICT`	Reutiliza una intención solo con su solicitud original. Usa un nuevo UUID para otra acción.
`429`	Límite de solicitudes alcanzado`RATE_LIMITED`	Espera el intervalo de Retry-After antes de reintentar la misma solicitud.
`503`	No disponible temporalmente`DEPENDENCY_UNAVAILABLE`	Espera Retry-After y reintenta con la misma intención. Consulta la operación guardada tras un tiempo de espera.

AutenticaciónLas claves API cobran a la cuenta propietaria. OAuth permite a cada usuario conectado usar sus créditos.Errores y límites de solicitudesComprende los errores, reintenta de forma segura y recupera generaciones fallidas.Solicitudes y registrosUna solicitud aceptada no es una generación terminada. Sigue el trabajo hasta que el resultado esté listo.