Tài liệu

Hướng dẫn cài API key, cấu hình Base URL và xử lý lỗi thường gặp

API Reference

Techopenclaw exposes three endpoints matching the OpenAI and Anthropic API formats. All endpoints require authentication via API key.

POST/v1/chat/completionsOpenAI

Standard OpenAI Chat Completions format. Works with all models.

Request — curl

curl https://api.techopenclaw.com/v1/chat/completions \
  -H "Authorization: Bearer toc-....." \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5.4",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "max_tokens": 4096,
  "stream": true
}'

Response (non-stream)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 9,
    "total_tokens": 34
  }
}

Streaming: Set stream: true for SSE responses. Add "stream_options": { "include_usage": true } for token usage in stream.

POST/v1/messagesAnthropic

Native Anthropic Messages format. Used by Claude Code and tools that speak the Anthropic API.

Request — curl

curl https://api.techopenclaw.com/v1/messages \
  -H "x-api-key: toc-....." \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
  "model": "gpt-5.4",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "system": "You are a helpful assistant.",
  "max_tokens": 4096,
  "stream": true
}'

Response (non-stream)

{
  "id": "msg_01abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "gpt-5.4",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 9
  }
}

Extended thinking: Supported via the thinking parameter. Add "thinking": { "type": "enabled", "budget_tokens": 10000 } to enable.

POST/v1/responsesOpenAI

OpenAI Responses API format. Used for GPT and Codex models.

Request — curl

curl https://api.techopenclaw.com/v1/responses \
  -H "Authorization: Bearer toc-....." \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5.4-codex",
  "input": [
    { "role": "user", "content": [{ "type": "input_text", "text": "Hello!" }] }
  ],
  "stream": true,
  "reasoning": { "effort": "high" }
}'

Response (non-stream)

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1712345678,
  "model": "gpt-5.4-codex",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 22,
    "output_tokens": 9,
    "total_tokens": 31
  }
}

Authentication

All requests must include your API key. Techopenclaw supports two authentication methods depending on the endpoint format:

Format	Header	Example
OpenAI OpenAI	`Authorization`	`Bearer toc-.....`
Anthropic Anthropic	`x-api-key`	`toc-.....`

Rate Limiting

Techopenclaw uses a Rolling Window mechanism. Each plan has a dollar budget per time window (e.g., $50 every 2 hours). When the budget is exhausted, requests return 402 until the window resets automatically. Rate limit headers are included in every response:

Header	Description
`x-ratelimit-remaining`	Remaining budget in current window (USD)
`x-ratelimit-reset`	Unix timestamp when the current window resets
`retry-after`	Seconds until you can retry (only on 429/402)

Other Endpoints

Method	Endpoint	Description
GET	`/v1/models`	List available models
GET	`/health/ready`	Health check (no auth)

Error Codes

Code	Meaning	Action
`400`	Malformed request body or missing required fields	Verify JSON syntax and required parameters
`401`	Invalid or missing API key	Check your `toc-` key
`402`	Quota exhausted	Wait for window reset or upgrade plan
`403`	Model not available on your plan	Check supported models in LLM Catalog
`429`	Rate limit exceeded	Wait and retry with exponential backoff
`500`	Internal server error	Retry after a few seconds; contact support if persistent
`503`	Service overloaded or upstream provider down	Retry shortly; Smart Routing will failover automatically