API compatível com a OpenAI

O que é

A API compatível com a OpenAI permite que uma ferramenta que fala o formato chat completions da OpenAI utilize os modelos de chat do ToRun, pagos pela sua conta ToRun. Um agente de programação como o opencode pode utilizar o ToRun como fornecedor de modelos, ao lado das ferramentas MCP do ToRun.

Endereço e início de sessão

Utilize a mesma chave de programador que para o servidor MCP: consulte Chaves de programador. Uma chave criada antes de a API compatível com a OpenAI ser adicionada responde 403 insufficient_scope. As permissões de uma chave nunca mudam, por isso crie uma nova chave.

A API tem dois endpoints, GET /v1/models e POST /v1/chat/completions. Qualquer outro caminho sob /v1 responde 404 not_found.

Modelos

GET /v1/models lista primeiro torun/auto e depois todos os modelos de texto que o seu plano pode utilizar, pelo respetivo id de modelo. Cada modelo indica:

• quanto texto consegue ler (context_length) e que comprimento de resposta consegue escrever (max_completion_tokens),
• se consegue chamar ferramentas (supports_tools) e ler imagens (supports_vision),
• o seu preço em Runs por milhão de tokens (pricing: input e output).

torun/auto deixa o ToRun escolher um modelo para cada pedido: um que lê imagens quando o pedido tem uma imagem, e um que chama ferramentas quando envia tools.

Chat completions

POST /v1/chat/completions aceita:

• messages, com os papéis system, developer (tratado como system), user, assistant e tool,
• tools e tool_choice (auto, none, required ou uma função com nome): as ferramentas da sua própria ferramenta regressam a ela como chamadas de ferramentas, e o ToRun nunca as executa,
• response_format com json_object. json_schema é aceite e respondido em JSON, mas o esquema em si não é imposto,
• temperature (0 a 2), top_p (0 a 1), max_completion_tokens ou max_tokens, stop (até 4 sequências), seed e reasoning_effort,
• stream e stream_options.include_usage.

n acima de 1, logprobs, top_logprobs, áudio e qualquer saída que não seja texto são recusados com 400 unsupported_parameter em vez de ignorados.

Imagens

Envie uma imagem incorporada, como data:image/...;base64,... numa parte image_url, até 20 MB por pedido. Uma imagem enviada como ligação é recusada com 400 image_url_not_supported: o ToRun não a vai buscar. As imagens passam por uma verificação de segurança, como na aplicação.

Streaming

Com "stream": true a resposta chega como eventos enviados pelo servidor no formato chat.completion.chunk:

• O primeiro fragmento traz o papel assistant, e as chamadas de ferramentas são transmitidas com o respetivo index.
• Enquanto não há nada para enviar, chega uma linha de comentário : keepalive a cada 15 segundos; os analisadores de SSE ignoram-na.
• data: [DONE] termina um stream bem-sucedido.
• Com stream_options.include_usage, o último fragmento tem um choices vazio e traz usage.
• Uma falha depois de o stream começar chega como um único evento data: {"error": ...}, sem [DONE].

Uma chamada sem streaming é interrompida ao fim de 110 segundos com 504 timeout. Envie os pedidos longos com "stream": true.

Utilização

usage contém prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens e completion_tokens_details.reasoning_tokens, além de torun_credits: o que a chamada custou, em Runs.

Utilizar no opencode

A configuração do opencode na página Programadores adiciona o ToRun como fornecedor de modelos ao lado do servidor MCP:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "torun": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ToRun",
      "options": { "baseURL": "https://mcp.torun.ai/v1", "apiKey": "{env:TORUN_API_KEY}" },
      "models": { "torun/auto": { "name": "ToRun Auto" } }
    }
  }
}

Qualquer outra ferramenta que fale a API de chat da OpenAI funciona da mesma forma. O separador API OpenAI da página mostra esta chamada:

curl https://mcp.torun.ai/v1/chat/completions \
  -H "Authorization: Bearer $TORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "torun/auto", "messages": [{"role": "user", "content": "Hello"}]}'

Como as chamadas são pagas

As chamadas à API custam os mesmos Runs que a mesma utilização na aplicação. Só fundos pagos as pagam: primeiro a quota do seu plano pago e depois a sua carteira, se o tiver permitido na chave. A quota gratuita nunca paga chamadas à API. Aplicam-se os limites mensal e diário da chave, e as respostas passam por uma verificação de segurança como as respostas do chat.

Limites

Cada chave pode fazer 60 pedidos por minuto a esta API e executar 4 completions ao mesmo tempo. Acima disso, a API responde 429 rate_limit_exceeded com um cabeçalho Retry-After.

Erros

Todos os erros têm a forma {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. A message vem no idioma pedido pelo cabeçalho Accept-Language do pedido.

Um pedido que não pode ser pago responde 402, e não 429, para que um cliente não continue a tentar de novo.