Preparar locais

tong_locations_prepare

Prepare uma fonte da sua conta para a próxima etapa deste fluxo.

POST/v1/tools/tong_locations_prepare/operations

Exemplo de solicitação#

curl -X POST 'https://platform.tongai.io/v1/tools/tong_locations_prepare/operations' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "input": {    "params": {      "id": "aaaaaaaaaaaaaaaaaaaaaaaa"    },    "body": {      "revision": 0    }  }}'

Configuração

curl --version

Permissões#

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

locations:write

Corpo da solicitação#

As solicitações REST envolvem os argumentos em input. As chamadas MCP enviam os mesmos argumentos diretamente.

paramsobjectObrigatório

Mostrar campos aninhados

idstringObrigatório

Um ID hexadecimal de 24 caracteres.

Exemplo"aaaaaaaaaaaaaaaaaaaaaaaa"

bodyobjectObrigatório

Mostrar campos aninhados

revisionintegerObrigatório

Mínimo: 0.

Máximo: 9007199254740991.

Exemplo0

Cabeçalhos da solicitação#

HTTP

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

Mantenha um UUID por ação e reutilize após timeout ou nova tentativa. Entradas diferentes com o mesmo UUID são rejeitadas.

Campos de resposta#

Uma solicitação aceita não é uma geração concluída. Acompanhe o trabalho até o resultado estar pronto.

Resposta

Aceita significa que a solicitação foi salva. Consulte a operação para acompanhar a execução.

JSON

{  "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",  "tool": "tong_locations_prepare",  "category": "locations",  "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"  }}

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.

Solicitações e registrosUma solicitação aceita não é uma geração concluída. Acompanhe o trabalho até o resultado estar pronto.Créditos e cobrançaAcompanhe os preços cotados, o uso real e os créditos liquidados.

Chamada MCP#

JSON

{  "jsonrpc": "2.0",  "id": 1,  "method": "tools/call",  "params": {    "name": "tong_locations_prepare",    "arguments": {      "params": {        "id": "aaaaaaaaaaaaaaaaaaaaaaaa"      },      "body": {        "revision": 0      }    },    "_meta": {      "io.tongai/idempotency-key": "45be69f1-c266-4a09-a82c-bf3c6303eb03"    }  }}

As solicitações REST envolvem os argumentos em input. As chamadas MCP enviam os mesmos argumentos diretamente.

Resposta

JSON

{  "jsonrpc": "2.0",  "id": 1,  "result": {    "structuredContent": {      "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",      "tool": "tong_locations_prepare",      "category": "locations",      "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_locations_prepare\",\"category\":\"locations\",\"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\"}}"      }    ]  }}

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.

Erros e limites de requisiçõesEntenda os erros, tente novamente com segurança e recupere gerações com falha.IdempotênciaMantenha um UUID por ação e reutilize após timeout ou nova tentativa. Entradas diferentes com o mesmo UUID são rejeitadas.

Cotar locaisObtenha uma cotação para o modelo, entradas e configuração exatos antes de enviar a ação.Gerar locaisEnvie a ação configurada usando sua conta e créditos Tong. Acompanhe a operação salva até terminar.Selecionar localSalve o resultado selecionado ou a decisão de revisão deste fluxo.Atribuir localAnexe um recurso da sua conta a este fluxo com os identificadores selecionados.Anexar localAnexe um recurso da sua conta a este fluxo com os identificadores selecionados.

Preparar locais

Exemplo de solicitação#

Permissões#

Corpo da solicitação#

Cabeçalhos da solicitação#

Campos de resposta#

Chamada MCP#

Resposta

Erros e limites#

Ferramentas relacionadas#