> ## 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.

# Referência da API

> URL base, endpoints, respostas, erros e limites de uso.

## Visão geral

Esta página resume conexão, endpoints, respostas, erros e limites comuns da API Developer Platform. Obtenha esquemas e preços atuais por ferramenta com `GET /tools`.

## URL base e cabeçalhos

Acrescente todos os caminhos a esta URL base.

```text theme={null}
https://api.noimosai.com/noimosToolBridge
```

Autentique com uma chave Developer Platform. Inclua Content-Type ao enviar JSON.

```http theme={null}
Authorization: Bearer nmp_...
Content-Type: application/json
```

A execução paga também exige este cabeçalho.

```http theme={null}
Idempotency-Key: request-unique-id
```

## Endpoints

Estes são os principais endpoints públicos.

| Método e caminho | Permissão necessária | Uso |
| - | - | - |
| `GET /tools/project` | `project:read` | Consultar organização e projeto da chave |
| `GET /tools/usage` | `usage:read` | Consultar solicitações consolidadas e custos do mês atual em UTC |
| `GET /tools` | `tools:read` | Obter ferramentas, esquemas, exemplos, disponibilidade e preços |
| `POST /tools/quote` | `tools:read` | Estimar gratuitamente a reserva máxima para a entrada |
| `POST /tools/upload` | `tools:execute` | Armazenar entradas explícitas de forma privada no projeto |
| `POST /tools/{tool}` | `tools:execute` | Reservar o limite e registrar trabalho pago |
| `GET /tools/executions` | `executions:read` | Listar execuções do projeto |
| `GET /tools/executions/{id}` | `executions:read` | Obter estado, resultados e custo definitivo |
| `POST /tools/executions/{id}/cancel` | `tools:execute` | Solicitar cancelamento |
| `GET /tools/executions/{id}/artifacts/{artifactId}/download` | `executions:read` | Obter URL temporária de arquivo gerado |

Filtre `GET /tools/executions` com `limit`, `before`, `status` e `tool`. `limit` aceita 1–100; o padrão é 20.

## Catálogo de ferramentas

`data` de `GET /tools` inclui versão de preços, moeda, disponibilidade de execução e ferramentas do catálogo.

Cada ferramenta fornece:

* `name` — Nome usado na URL e no corpo de execução
* `description` e `category` — Uso e classificação
* `available` — Se os serviços externos necessários estão configurados e disponíveis
* `inputSchema` e `example` — JSON Schema de entrada e exemplo
* `models` — Modelos selecionáveis com exemplos, disponibilidade e preços por modelo
* `price` — Custo mínimo, unidade de cobrança e descrição de preços

`available: true` não garante execução. Também se aplicam `executionEnabled`, permissões, saldo e limites mensais.

## Formato das respostas

Respostas bem-sucedidas geralmente contêm o resultado em `data`.

```json theme={null}
{
  "data": {}
}
```

Erros contêm status e mensagem em `error`.

```json theme={null}
{
  "error": {
    "status": "PERMISSION_DENIED",
    "message": "platform_api_key_scope_required"
  }
}
```

Todas as respostas usam `Cache-Control: no-store`. Não salve chaves, resultados ou URLs temporárias em caches compartilhados.

## Tratar erros

Verifique a causa conforme o status antes de tentar novamente.

| HTTP | Significado | Ação |
| - | - | - |
| `200` | Consulta bem-sucedida ou mesma execução concluída | Processar `data` |
| `202` | Trabalho assíncrono aceito | Salvar ID e esperar pelo menos cinco segundos |
| `400` | Entrada, cotação ou estado inválido | Verificar catálogo e cotação |
| `401` | Falha de autenticação | Verificar Authorization, validade e revogação |
| `403` | Permissão negada | Verificar permissões da chave e do projeto |
| `404` | Endpoint, operação ou artefato indisponível | Verificar caminho, disponibilidade e validade |
| `409` | Chave de idempotência usada em outra solicitação | Verificar corpo e chave originais; evitar outra execução |
| `429` | Limite de solicitações, saldo ou teto mensal atingido | Verificar limite e saldo correspondentes |
| `503` | Execução ou serviço externo temporariamente indisponível | Verificar aceitação do trabalho pago antes de reenviar |

## Limites de uso

Considere estes limites no cliente.

| Recurso | Limite |
| - | - |
| Solicitação JSON normal | 64 KiB em UTF-8 |
| Arquivo enviado | 12 MiB |
| Formatos aceitos | JPEG, PNG, WAV, MP3, MP4 |
| Solicitações | 120 por chave API em cada janela fixa de um minuto |
| Intervalo de consulta | Pelo menos cinco segundos |
| Etapas por execução | Até 20 |
| Retenção de arquivos gerados | 30 dias |
| Validade de URL de download | Até cinco minutos |

Contam catálogo, cotações, uploads, execuções, consultas e novas tentativas. Evite consultas frequentes demais para prevenir respostas 429.

## Enviar arquivos de entrada

Para imagens, áudio ou vídeo locais, envie tipo MIME e dados Base64 a `POST /tools/upload`.

```json theme={null}
{
  "mimeType": "audio/wav",
  "data": "BASE64_DATA"
}
```

A resposta fornece um `id` usável como `fileId`, formato, tamanho, SHA-256 e validade. Informe em campos como `source` conforme o catálogo. Conteúdo idêntico no mesmo projeto retorna o mesmo ID; a retenção não se prolonga além do primeiro upload.

## Páginas relacionadas

Consulte estas páginas para autenticação e execução.

* [Autenticar solicitações](https://docs.noimosai.com/pt/developers/api/authentication.md)
* [Gerenciar execução e cobrança](https://docs.noimosai.com/pt/developers/api/execution-and-billing.md)
* [Documentação](https://platform.noimosai.com/docs)


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