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 use os modelos de chat do ToRun, pagos pela sua conta ToRun. Um agente de programação como o opencode pode usar o ToRun como provedor de modelos, junto com as ferramentas MCP do ToRun.

Endereço e login

Use a mesma chave de desenvolvedor do servidor MCP: veja Chaves de desenvolvedor. Uma chave criada antes de a API compatível com a OpenAI ser adicionada recebe 403 insufficient_scope. As permissões de uma chave nunca mudam, então crie uma nova chave.

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

Modelos

GET /v1/models lista primeiro torun/auto e depois todo modelo de texto que seu plano pode usar, pelo id do modelo. Cada modelo informa:

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

torun/auto deixa o ToRun escolher um modelo para cada solicitação: um que lê imagens quando a solicitação tem uma imagem, e um que chama ferramentas quando ela 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 nomeada): as ferramentas da sua própria ferramenta voltam para ela como chamadas de ferramenta, e o ToRun nunca as executa,
• response_format com json_object. json_schema é aceito 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 embutida, como data:image/...;base64,... em uma parte image_url, com até 20 MB por solicitação. Uma imagem enviada como link é recusada com 400 image_url_not_supported: o ToRun não a baixa. As imagens passam por uma verificação de segurança, como no app.

Streaming

Com "stream": true a resposta chega como server-sent events no formato chat.completion.chunk:

• O primeiro chunk traz o papel assistant, e as chamadas de ferramenta são transmitidas com seu index.
• Enquanto não há nada para enviar, chega uma linha de comentário : keepalive a cada 15 segundos; os parsers de SSE a ignoram.
• data: [DONE] encerra um stream que deu certo.
• Com stream_options.include_usage, o último chunk tem choices vazio e traz usage.
• Uma falha depois que o stream começou chega como um único evento data: {"error": ...}, sem [DONE].

Uma chamada sem streaming é interrompida depois de 110 segundos com 504 timeout. Envie solicitações longas com "stream": true.

Uso

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

Use no opencode

A configuração do opencode na página Desenvolvedores adiciona o ToRun como provedor 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 do mesmo jeito. A aba API da 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

Chamadas de API custam os mesmos Runs que o mesmo uso no app. Só recursos pagos as pagam: primeiro a cota do seu plano pago e depois sua carteira, se você permitiu isso na chave. A cota gratuita nunca paga chamadas de API. Os limites mensal e diário da chave se aplicam, e as respostas passam por verificação de segurança como as respostas do chat.

Limites

Cada chave pode fazer 60 solicitações 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

Todo erro tem o formato {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. A message vem no idioma pedido pelo cabeçalho Accept-Language da solicitação.

Uma solicitação que não pode ser paga responde 402, não 429, para que um cliente não fique tentando de novo.