API compatible con OpenAI

Qué es

La API compatible con OpenAI permite que una herramienta que habla el formato chat completions de OpenAI use los modelos de chat de ToRun, pagados desde tu cuenta de ToRun. Un agente de programación como opencode puede usar ToRun como su proveedor de modelos, junto a las herramientas MCP de ToRun.

Dirección e inicio de sesión

Usa la misma clave de desarrollador que para el servidor MCP: consulta Claves de desarrollador. Una clave creada antes de que se añadiera la API compatible con OpenAI responde 403 insufficient_scope. Los permisos de una clave nunca cambian, así que crea una clave nueva.

La API tiene dos endpoints, GET /v1/models y POST /v1/chat/completions. Cualquier otra ruta bajo /v1 responde 404 not_found.

Modelos

GET /v1/models muestra primero torun/auto y después todos los modelos de texto que puede usar tu plan, por su id de modelo. Cada modelo indica:

• cuánto texto puede leer (context_length) y qué longitud de respuesta puede escribir (max_completion_tokens),
• si puede llamar a herramientas (supports_tools) y leer imágenes (supports_vision),
• su precio en Runs por millón de tokens (pricing: input y output).

torun/auto deja que ToRun elija un modelo para cada solicitud: uno que lee imágenes cuando la solicitud tiene una imagen, y uno que llama a herramientas cuando envía tools.

Chat completions

POST /v1/chat/completions acepta:

• messages, con los roles system, developer (tratado como system), user, assistant y tool,
• tools y tool_choice (auto, none, required o una función con nombre): las herramientas propias de tu herramienta vuelven a ella como llamadas a herramientas, y ToRun nunca las ejecuta,
• response_format con json_object. json_schema se acepta y se responde como JSON, pero el esquema en sí no se impone,
• temperature (de 0 a 2), top_p (de 0 a 1), max_completion_tokens o max_tokens, stop (hasta 4 secuencias), seed y reasoning_effort,
• stream y stream_options.include_usage.

n mayor que 1, logprobs, top_logprobs, el audio y cualquier salida que no sea texto se rechazan con 400 unsupported_parameter en lugar de ignorarse.

Imágenes

Envía una imagen en línea, como data:image/...;base64,... en una parte image_url, de hasta 20 MB por solicitud. Una imagen enviada como enlace se rechaza con 400 image_url_not_supported: ToRun no la descarga. Las imágenes pasan una comprobación de seguridad, como en la app.

Streaming

Con "stream": true la respuesta llega como eventos enviados por el servidor con la forma chat.completion.chunk:

• El primer fragmento lleva el rol assistant, y las llamadas a herramientas se transmiten con su index.
• Mientras no hay nada que enviar, llega una línea de comentario : keepalive cada 15 segundos; los analizadores de SSE la omiten.
• data: [DONE] termina un stream que ha salido bien.
• Con stream_options.include_usage, el último fragmento tiene choices vacío y lleva usage.
• Un fallo después de que empiece el stream llega como un único evento data: {"error": ...}, sin [DONE].

Una llamada sin streaming se detiene a los 110 segundos con 504 timeout. Envía las solicitudes largas con "stream": true.

Uso

usage incluye prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens y completion_tokens_details.reasoning_tokens, además de torun_credits: lo que costó la llamada, en Runs.

Úsala en opencode

La configuración de opencode de la página Desarrolladores añade ToRun como proveedor de modelos junto al 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" } }
    }
  }
}

Cualquier otra herramienta que hable la API de chat de OpenAI funciona igual. La pestaña API de OpenAI de la página muestra esta llamada:

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"}]}'

Cómo se pagan las llamadas

Las llamadas a la API cuestan los mismos Runs que el mismo uso en la app. Solo las pagan fondos de pago: primero la asignación de tu plan de pago y después tu monedero, si lo permitiste en la clave. La asignación gratuita nunca paga llamadas a la API. Se aplican los límites mensual y diario de la clave, y las respuestas pasan una comprobación de seguridad como las respuestas del chat.

Límites

Cada clave puede hacer 60 solicitudes por minuto a esta API y ejecutar 4 completions a la vez. Por encima de eso, la API responde 429 rate_limit_exceeded con una cabecera Retry-After.

Errores

Todos los errores tienen la forma {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. El message está en el idioma que pide la cabecera Accept-Language de la solicitud.

Una solicitud que no se puede pagar responde 402, no 429, para que un cliente no la siga reintentando.