> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciar execução e cobrança

> Execução assíncrona, novas tentativas idempotentes, reservas, cobrança e recuperação de artefatos.

## Visão geral

Esta página explica cotação, reserva, execução assíncrona, cobrança e artefatos. Acompanhe processos longos pelo ID sem manter a conexão HTTP aberta.

## Entender execução e cobrança

`POST /tools/quote` retorna versão de preços, custo mínimo e reserva máxima para a entrada. A cotação é gratuita, sem chamar serviços externos nem reservar fundos.

Mantenha `tool` e `arguments` da cotação e adicione:

* `priceVersion` — Versão de preços da cotação
* `maximumChargeMicros` — Reserva máxima da cotação

Se os preços mudarem ou o limite for insuficiente, a solicitação é recusada antes do processamento. Obtenha e revise outra cotação.

## Reservar e consolidar cobranças

Na aceitação, o máximo é temporariamente reservado do saldo pré-pago em USD. Ao concluir, cobra-se o custo real e devolve-se a parte não utilizada.

| Campo | Significado |
| - | - |
| `reservedMicros` | Máximo reservado na aceitação; mantém o valor original após concluir. |
| `chargedMicros` | Cobrança definitiva após conclusão ou falha. `0` durante o processo indica cobrança pendente. |
| `currency` | `usd`. 1 USD equivale a 1,000,000 micros. |

Falhas e cancelamentos ainda podem cobrar custos externos já incorridos. Nenhuma cobrança automática excede a reserva máxima.

## Consultar o estado

A aceitação retorna HTTP 202 e um ID. Siga `Retry-After: 5` e consulte o mesmo ID a intervalos de pelo menos cinco segundos.

| Estado | Significado | Ação |
| - | - | - |
| `queued` | Na fila | Aguardar pelo menos cinco segundos e consultar |
| `running` | Em processamento | Consultar o mesmo ID |
| `waiting` | Aguardando processamento externo | Consultar o mesmo ID |
| `succeeded` | Concluído e cobrado | Ler `output` e `chargedMicros` |
| `failed` | Falhou; custos incorridos cobrados | Ler `errorCode` e custo definitivo |
| `cancelled` | Cancelamento concluído | Verificar custo definitivo |
| `needs_review` | Resultado ou custo precisa de revisão | Não executar novamente; contatar suporte com o ID |

## Evitar duplicações com idempotência

Uma chave de idempotência evita execuções separadas ao reenviar acidentalmente a solicitação. `POST /tools/{tool}` pago exige `Idempotency-Key`.

A chave tem 8–128 caracteres: letras, números, `.`, `_`, `:` ou `-`. Gere uma por solicitação lógica e salve com o ID de execução.

* Mesma chave API, corpo e chave de idempotência retornam a mesma execução.
* Alterar corpo ou chave API mantendo a chave de idempotência retorna HTTP 409.
* Após falha de conexão, reenvie sem alterar corpo ou chave de idempotência.
* Reenviar um processo `needs_review` com nova chave cria outra execução paga.

> [!WARNING]
>
> Não receber resposta não prova que a execução não foi aceita. Não crie outra chave com resultado desconhecido.

## Cancelar uma execução

`POST /tools/executions/{id}/cancel` solicita parar trabalho ainda não iniciado. A chave criadora ou um `ADMIN` do projeto pode solicitar.

Se o processamento externo já começou, o cancelamento pode não desfazer trabalho ou custos. Verifique `cancelRequested`, o `status` final e `chargedMicros`.

## Obter artefatos

Imagens, áudio e vídeo gerados aparecem em `output.artifacts` com ID, formato, tamanho, hash e validade. O resultado não inclui arquivos completos nem URLs permanentes.

`GET /tools/executions/{id}/artifacts/{artifactId}/download` fornece uma URL válida por até cinco minutos. Arquivos armazenados expiram após 30 dias.

Mesmo temporárias, essas URLs dão acesso a dados privados. Não registre nem publique, e não acrescente a chave Developer Platform.

## Páginas relacionadas

Estas páginas detalham a primeira execução e os endpoints.

* [Primeiros passos](https://docs.noimosai.com/pt/developers/api/getting-started.md)
* [Referência da API](https://docs.noimosai.com/pt/developers/api/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.