Referência da API

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.

https://api.noimosai.com/noimosToolBridge

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

Authorization: Bearer nmp_...
Content-Type: application/json

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

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.

{
  "data": {}
}

Erros contêm status e mensagem em error.

{
  "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.

{
  "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.

Primeiros passos

API

CLI

Servidor MCP

Referência da API

Visão geral

URL base e cabeçalhos

Endpoints

Catálogo de ferramentas

Formato das respostas

Tratar erros

Limites de uso

Enviar arquivos de entrada

Páginas relacionadas

​Visão geral

​URL base e cabeçalhos

​Endpoints

​Catálogo de ferramentas

​Formato das respostas

​Tratar erros

​Limites de uso

​Enviar arquivos de entrada

​Páginas relacionadas

Visão geral

URL base e cabeçalhos

Endpoints

Catálogo de ferramentas

Formato das respostas

Tratar erros

Limites de uso

Enviar arquivos de entrada

Páginas relacionadas