OpenAI 호환 API

소개

OpenAI 호환 API를 사용하면 OpenAI의 chat completions 형식을 지원하는 도구가 ToRun 계정에서 결제하며 ToRun의 채팅 모델을 쓸 수 있습니다. opencode 같은 코딩 에이전트는 ToRun의 MCP 도구와 함께 ToRun을 모델 제공자로 쓸 수 있습니다.

주소와 로그인

MCP 서버와 같은 개발자 키를 쓰세요. 개발자 키를 참고하세요. OpenAI 호환 API가 추가되기 전에 만든 키는 403 insufficient_scope를 받습니다. 키의 권한은 바뀌지 않으므로 새 키를 만드세요.

이 API의 엔드포인트는 GET /v1/models와 POST /v1/chat/completions 두 개입니다. /v1 아래의 다른 경로는 모두 404 not_found를 돌려줍니다.

모델

GET /v1/models는 먼저 torun/auto를, 그다음 요금제에서 쓸 수 있는 모든 텍스트 모델을 모델 ID로 나열합니다. 각 모델에는 다음이 표시됩니다.

• 읽을 수 있는 텍스트 양(context_length)과 쓸 수 있는 답변 길이(max_completion_tokens),
• 도구를 호출할 수 있는지(supports_tools)와 이미지를 읽을 수 있는지(supports_vision),
• 100만 토큰당 Runs로 나타낸 가격(pricing: input과 output).

torun/auto를 쓰면 ToRun이 요청마다 모델을 고릅니다. 요청에 이미지가 있으면 이미지를 읽는 모델을, tools를 보내면 도구를 호출하는 모델을 고릅니다.

Chat completions

POST /v1/chat/completions는 다음을 받습니다.

• system, developer(system으로 처리), user, assistant, tool 역할을 쓰는 messages,
• tools와 tool_choice(auto, none, required 또는 이름을 지정한 함수 하나): 사용하는 도구 자체의 도구는 도구 호출로 그 도구에 돌아가며, ToRun은 절대 실행하지 않습니다,
• json_object를 지정한 response_format. json_schema도 받아 JSON으로 답하지만 스키마 자체를 강제하지는 않습니다,
• temperature(0_{2), top_p(0}1), max_completion_tokens 또는 max_tokens, stop(최대 4개 시퀀스), seed, reasoning_effort,
• stream과 stream_options.include_usage.

1보다 큰 n, logprobs, top_logprobs, 오디오, 텍스트가 아닌 출력은 무시되지 않고 400 unsupported_parameter로 거부됩니다.

이미지

이미지는 image_url 파트에 data:image/...;base64,... 형태로 인라인으로 보내며, 요청당 최대 20 MB입니다. 링크로 보낸 이미지는 400 image_url_not_supported로 거부됩니다. ToRun은 그 이미지를 가져오지 않습니다. 이미지는 앱에서와 마찬가지로 안전 검사를 거칩니다.

스트리밍

"stream": true를 쓰면 답변이 chat.completion.chunk 형태의 server-sent events로 도착합니다.

• 첫 청크에는 assistant 역할이 담기며, 도구 호출은 각자의 index와 함께 스트리밍됩니다.
• 보낼 것이 없는 동안에는 15초마다 : keepalive 주석 줄이 옵니다. SSE 파서는 이 줄을 건너뜁니다.
• data: [DONE]은 성공한 스트림을 끝냅니다.
• stream_options.include_usage를 쓰면 마지막 청크는 choices가 비어 있고 usage를 담습니다.
• 스트림이 시작된 뒤의 실패는 [DONE] 없이 data: {"error": ...} 이벤트 하나로 옵니다.

스트리밍하지 않는 호출은 110초 뒤에 504 timeout으로 중단됩니다. 긴 요청은 "stream": true로 보내세요.

사용량

usage에는 prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens, completion_tokens_details.reasoning_tokens와 함께, 호출에 든 Runs를 나타내는 torun_credits가 담깁니다.

opencode에서 쓰기

개발자 페이지의 opencode 설정은 MCP 서버 옆에 ToRun을 모델 제공자로 추가합니다.

{
  "$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" } }
    }
  }
}

OpenAI 채팅 API를 지원하는 다른 도구도 같은 방식으로 작동합니다. 이 페이지의 OpenAI API 탭에는 다음 호출이 나와 있습니다.

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

호출 비용은 어떻게 결제되나요

API 호출에는 앱에서 같은 방식으로 쓸 때와 같은 Runs가 듭니다. 이 비용은 유료 자금으로만 결제됩니다. 먼저 유료 요금제 사용량에서, 키에서 허용했다면 그다음 지갑에서 결제됩니다. 무료 사용량은 API 호출 비용을 결제하지 않습니다. 키의 월 한도와 일일 한도가 적용되며, 답변은 채팅 답변처럼 안전 검사를 거칩니다.

한도

키마다 이 API에 분당 60개의 요청을 보낼 수 있고, completions를 동시에 4개까지 실행할 수 있습니다. 이를 넘으면 API는 Retry-After 헤더와 함께 429 rate_limit_exceeded를 돌려줍니다.

오류

모든 오류는 {"error": {"message": ..., "type": ..., "param": ..., "code": ...}} 형태입니다. message는 요청의 Accept-Language 헤더가 요청한 언어로 옵니다.

결제할 수 없는 요청은 클라이언트가 계속 다시 시도하지 않도록 429가 아니라 402를 받습니다.