`POST /v1/assets`

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

Ejemplo de solicitud#

curl -X POST 'https://platform.tongai.io/v1/assets?purpose=image' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -F '[email protected]'

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.

assets:write

Parámetros#

purposestringObligatorio

Valores permitidos"image""reference""video""audio_reference""director_document""director_reference""lora_media""motion_video""motion_image""video_edit"

project_idstringOpcional

Un ID hexadecimal de 24 caracteres.

Idempotency-KeystringObligatorio

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

Cuerpo de solicitud#

multipart/form-data

filestringObligatorio

Formato: binary.

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.