`POST /v1/filmmaker/runs`

Use os campos e permissões documentados para este endpoint HTTP.

Exemplo de solicitação#

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"}'

Configuração

curl --version

Autenticação#

Use uma chave API no servidor para sua conta, ou OAuth para a conta de cada cliente. Nunca envie chaves em prompts ou argumentos.

filmmaker:runcredits:spend

Parâmetros#

Idempotency-KeystringObrigatório

Um UUID, por exemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

Corpo da solicitação#

application/json

messagestringObrigatório

Descreva o resultado que deseja criar.

Comprimento mínimo: 1 caracteres.

Comprimento máximo: 32000 caracteres.

attachmentsstring[]Opcional

Use IDs de recursos da sua conta compatíveis com as referências do modelo escolhido.

Máximo de itens: 30.

Padrão: [].

reference_bindingsobject[]Opcional

Máximo de itens: 30.

Mostrar campos aninhados

labelstringObrigatório

Use um rótulo de referência numerado, por exemplo Image1.

assetIdstringObrigatório

Use o identificador de um recurso da conta autorizada.

Um ID hexadecimal de 24 caracteres.

modestringOpcional

Execuções guiadas aguardam revisão humana no Tong. As automáticas continuam. Ambas cobram durante o trabalho e pausam sem créditos.

Valores permitidos"guided""automatic"

Padrão: "guided".

conversation_idstringOpcional

Um UUID, por exemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

model_preferencesobjectOpcional

Mostrar campos aninhados

imagestring | nullObrigatório

Use letras, números, sublinhados, pontos, dois-pontos, barras ou hífens.

Comprimento mínimo: 1 caracteres.

Comprimento máximo: 150 caracteres.

videostring | nullObrigatório

Use letras, números, sublinhados, pontos, dois-pontos, barras ou hífens.

Comprimento mínimo: 1 caracteres.

Comprimento máximo: 150 caracteres.

sourceobjectOpcional

Mostrar campos aninhados

kindstringObrigatório

Valores permitidos"director""text"

idstringObrigatório

Um ID hexadecimal de 24 caracteres.

Esquema de resposta#

Resposta

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

idstringObrigatório

O ID exclusivo da operação salva.

Um UUID, por exemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringObrigatório

categorystringObrigatório

channelstringObrigatório

Valores permitidos"api""mcp"

statestringObrigatório

O estado atual de execução do trabalho salvo.

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

statusstringObrigatório

O status geral para acompanhar a operação.

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

stagestringObrigatório

A fase atual da operação.

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

dispatch_statusstringObrigatório

Indica se a ferramenta aceitou a solicitação. A confirmação não significa que a geração terminou.

Valores permitidos"pending""unknown""acknowledged"

created_atstringObrigatório

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

updated_atstringObrigatório

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

detail_expires_atstring | nullObrigatório

Quando os detalhes salvos expiram. O valor null indica que não há expiração definida.

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

detail_expiredbooleanObrigatório

Indica se os detalhes salvos da operação expiraram.

timingobjectObrigatório

Datas e durações para acompanhar esta operação.

Mostrar campos aninhados

dispatch_started_atstring | nullObrigatório

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

acknowledged_atstring | nullObrigatório

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

completed_atstring | nullObrigatório

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

dispatch_acknowledgement_msnumber | nullObrigatório

Mínimo: 0.

end_to_end_msnumber | nullObrigatório

Mínimo: 0.

reviewJSON | nullObrigatório

Informações de revisão quando a operação exige intervenção humana; caso contrário, null.

resultJSON | nullObrigatório

A saída desta ferramenta, ou null enquanto não houver saída disponível.

errorobject | nullObrigatório

O código de erro público se a operação falhou; caso contrário, null.

Mostrar campos aninhados

codestringObrigatório

billingobjectObrigatório

Uso de créditos e cobranças da carteira. A disponibilidade da saída e a liquidação são independentes.

Mostrar campos aninhados

statusstringObrigatório

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

usage_creditsstringObrigatório

Uma string decimal com seis casas decimais, por exemplo 1.250000.

wallet_debited_creditsstringObrigatório

Uma string decimal com seis casas decimais, por exemplo 1.250000.

released_creditsstringOpcional

Uma string decimal com seis casas decimais, por exemplo 1.250000.

refunded_creditsstringOpcional

Uma string decimal com seis casas decimais, por exemplo 1.250000.

unfunded_creditsstringOpcional

Uma string decimal com seis casas decimais, por exemplo 1.250000.

pending_creditsstringOpcional

Uma string decimal com seis casas decimais, por exemplo 1.250000.

tokensobjectOpcional

Mostrar campos aninhados

inputnumberOpcional

Mínimo: 0.

outputnumberOpcional

Mínimo: 0.

cachednumberOpcional

Mínimo: 0.

cache_writenumberOpcional

Mínimo: 0.

componentsobject[]Opcional

Mostrar campos aninhados

idstringOpcional

source_idstringObrigatório

toolstringObrigatório

modelstring | nullObrigatório

channelstringObrigatório

Valores permitidos"api""mcp"

credential_idstringObrigatório

kindstringObrigatório

Valores permitidos"text_pool""reasoning""generation"

usage_creditsstringObrigatório

Uma string decimal com seis casas decimais, por exemplo 1.250000.

wallet_debited_creditsstringObrigatório

Uma string decimal com seis casas decimais, por exemplo 1.250000.

evidence_atstringOpcional

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

updated_atstringOpcional

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

quoteobjectOpcional

A configuração, o preço e os valores de envio quando há uma cotação.

Mostrar campos aninhados

idstringObrigatório

Um UUID, por exemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

operation_idstringObrigatório

Um UUID, por exemplo e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringObrigatório

operationstring | nullObrigatório

modelstring | nullObrigatório

configurationobjectObrigatório

submit_valuestringObrigatório

submit_fieldstringObrigatório

quoted_creditsstring | nullObrigatório

Uma string decimal com seis casas decimais, por exemplo 1.250000.

expires_atstring | nullObrigatório

Data e hora ISO 8601, por exemplo 2026-10-22T09:00:00Z.

Erros e limites#

HTTP	Erro	Recuperação
`400`	Solicitação inválida`REQUEST_INVALID`	Corrija os campos indicados pelo erro antes de tentar novamente.
`401`	Credencial inválida`CREDENTIAL_INVALID`	Verifique a credencial, a validade e se foi revogada.
`402`	Créditos insuficientes`INSUFFICIENT_CREDITS`	Adicione créditos à conta da credencial e continue o trabalho salvo.
`403`	Permissão negada`SCOPE_REQUIRED`	Use uma credencial com os escopos necessários e acesso ao recurso selecionado.
`404`	Recurso indisponível`RESOURCE_UNAVAILABLE`	Verifique o ID do recurso e se pertence à conta autorizada.
`409`	Conflito de intenção`IDEMPOTENCY_CONFLICT`	Reutilize uma intenção apenas com a solicitação original. Use um novo UUID para outra ação.
`429`	Limite de requisições atingido`RATE_LIMITED`	Aguarde o prazo de Retry-After antes de repetir a mesma solicitação.
`503`	Temporariamente indisponível`DEPENDENCY_UNAVAILABLE`	Aguarde Retry-After e repita com a mesma intenção. Verifique a operação salva após um tempo limite.

AutenticaçãoAs chaves de API cobram da conta proprietária. O OAuth permite que cada usuário conectado use seus créditos.Erros e limites de requisiçõesEntenda os erros, tente novamente com segurança e recupere gerações com falha.Solicitações e registrosUma solicitação aceita não é uma geração concluída. Acompanhe o trabalho até o resultado estar pronto.