API tương thích OpenAI

Đây là gì

API tương thích OpenAI cho phép công cụ hỗ trợ định dạng chat completions của OpenAI dùng các mô hình trò chuyện của ToRun, được thanh toán từ tài khoản ToRun của bạn. Một tác nhân lập trình như opencode có thể dùng ToRun làm nhà cung cấp mô hình, bên cạnh các công cụ MCP của ToRun.

Địa chỉ và đăng nhập

Dùng cùng khóa nhà phát triển như cho máy chủ MCP: xem Khóa nhà phát triển. Khóa được tạo trước khi API tương thích OpenAI được thêm vào sẽ nhận phản hồi 403 insufficient_scope. Quyền của khóa không bao giờ thay đổi, vì vậy hãy tạo khóa mới.

API có hai điểm cuối, GET /v1/models và POST /v1/chat/completions. Mọi đường dẫn khác trong /v1 đều trả về 404 not_found.

Mô hình

GET /v1/models liệt kê torun/auto trước, rồi đến mọi mô hình văn bản mà gói của bạn có thể dùng, theo mã mô hình. Mỗi mô hình cho biết:

• lượng văn bản nó có thể đọc (context_length) và độ dài câu trả lời nó có thể viết (max_completion_tokens),
• nó có thể gọi công cụ (supports_tools) và đọc hình ảnh (supports_vision) hay không,
• giá của nó bằng Runs cho mỗi triệu token (pricing: input và output).

torun/auto để ToRun chọn mô hình cho từng yêu cầu: một mô hình đọc được hình ảnh khi yêu cầu có hình ảnh, và một mô hình gọi được công cụ khi yêu cầu gửi tools.

Chat completions

POST /v1/chat/completions chấp nhận:

• messages, với các vai trò system, developer (được xử lý như system), user, assistant và tool,
• tools và tool_choice (auto, none, required hoặc một hàm được đặt tên): các công cụ riêng của công cụ bạn dùng sẽ được trả lại cho nó dưới dạng lệnh gọi công cụ, và ToRun không bao giờ chạy chúng,
• response_format với json_object. json_schema được chấp nhận và câu trả lời là JSON, nhưng bản thân schema không được áp đặt,
• temperature (0 đến 2), top_p (0 đến 1), max_completion_tokens hoặc max_tokens, stop (tối đa 4 chuỗi), seed và reasoning_effort,
• stream và stream_options.include_usage.

n lớn hơn 1, logprobs, top_logprobs, âm thanh và mọi đầu ra không phải văn bản đều bị từ chối với 400 unsupported_parameter thay vì bị bỏ qua.

Hình ảnh

Gửi hình ảnh dạng nhúng, dưới dạng data:image/...;base64,... trong phần image_url, tối đa 20 MB mỗi yêu cầu. Hình ảnh gửi dưới dạng liên kết bị từ chối với 400 image_url_not_supported: ToRun không tải hình đó về. Hình ảnh được kiểm tra an toàn, giống như trong ứng dụng.

Truyền phát

Với "stream": true, câu trả lời đến dưới dạng server-sent events theo dạng chat.completion.chunk:

• Đoạn đầu tiên mang vai trò assistant, và lệnh gọi công cụ được truyền phát kèm index của chúng.
• Khi không có gì để gửi, cứ 15 giây lại có một dòng chú thích : keepalive; trình phân tích SSE sẽ bỏ qua dòng này.
• data: [DONE] kết thúc một luồng thành công.
• Với stream_options.include_usage, đoạn cuối cùng có choices rỗng và mang usage.
• Lỗi xảy ra sau khi luồng đã bắt đầu sẽ đến dưới dạng một sự kiện data: {"error": ...}, không có [DONE].

Lệnh gọi không truyền phát sẽ bị dừng sau 110 giây với 504 timeout. Hãy gửi các yêu cầu dài với "stream": true.

Mức sử dụng

usage chứa prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens và completion_tokens_details.reasoning_tokens, cùng với torun_credits: chi phí của lệnh gọi, tính bằng Runs.

Dùng trong opencode

Cấu hình opencode trên trang Nhà phát triển thêm ToRun làm nhà cung cấp mô hình bên cạnh máy chủ 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" } }
    }
  }
}

Mọi công cụ khác hỗ trợ API trò chuyện của OpenAI đều hoạt động theo cách tương tự. Thẻ OpenAI API của trang này hiển thị lệnh gọi sau:

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ác lệnh gọi được thanh toán thế nào

Lệnh gọi API tốn số Runs bằng với cùng mức sử dụng trong ứng dụng. Chỉ tiền trả phí mới thanh toán cho chúng: trước tiên là hạn mức gói trả phí của bạn, sau đó là ví nếu bạn đã cho phép điều đó trên khóa. Hạn mức miễn phí không bao giờ trả cho lệnh gọi API. Giới hạn hằng tháng và hằng ngày của khóa được áp dụng, và câu trả lời được kiểm tra an toàn như câu trả lời trong trò chuyện.

Giới hạn

Mỗi khóa có thể gửi 60 yêu cầu mỗi phút tới API này và chạy 4 completions cùng lúc. Vượt quá mức đó, API trả về 429 rate_limit_exceeded kèm tiêu đề Retry-After.

Lỗi

Mọi lỗi đều có dạng {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message được viết bằng ngôn ngữ mà tiêu đề Accept-Language của yêu cầu chỉ định.

Yêu cầu không thể thanh toán sẽ nhận 402 chứ không phải 429, để máy khách không liên tục thử lại.