Hướng dẫn nhanh

1. Lấy API key

Mở Telegram, bắt đầu trò chuyện với bot, rồi vào mục API Key trong Mini App để tạo key mới. Key chỉ hiển thị một lần — hãy sao chép và lưu lại ngay.

2. Base URL & xác thực

Base URL

https://thoth.rezlabs.io

Xác thực

Gửi API key qua header Authorization: Bearer sk-.... Header x-api-key: sk-... cũng được chấp nhận như một lựa chọn thay thế.

3. Chat Completions (tương thích OpenAI)

POST /v1/chat/completions tương thích với OpenAI Chat Completions API — dùng trực tiếp với hầu hết client/SDK hiện có.

Không streaming

curl https://thoth.rezlabs.io/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-latest",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Streaming (SSE)

curl https://thoth.rezlabs.io/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-latest",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

4. Models & Messages

Danh sách model

GET /v1/models trả về các model mà API key của bạn được phép dùng, tuỳ theo channel đã được gán.

curl https://thoth.rezlabs.io/v1/models \
  -H "Authorization: Bearer sk-..."

Anthropic Messages

POST /v1/messages theo định dạng Anthropic Messages API gốc — dùng trực tiếp với Claude Code hoặc SDK Anthropic.

curl https://thoth.rezlabs.io/v1/messages \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-latest",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

5. SDK mẫu

Dùng thẳng SDK openai chính thức hoặc fetch — chỉ cần đổi base_url/URL và api_key.

Python (openai SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://thoth.rezlabs.io/v1",
    api_key="sk-...",
)

resp = client.chat.completions.create(
    model="claude-sonnet-latest",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

JavaScript (fetch)

const res = await fetch("https://thoth.rezlabs.io/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-latest",
    messages: [{ role: "user", content: "Hello!" }],
  }),
});
const data = await res.json();
console.log(data.choices[0].message.content);

6. Model khả dụng

Bảng dưới là ví dụ minh hoạ các model phổ biến — danh sách thật phụ thuộc channel được gán cho từng API key.

7. Rate limit & lưu ý

Mỗi API key có thể bị giới hạn theo số request/phút, số request đồng thời, hoặc Budget tổng — tuỳ cấu hình được quản trị viên gán.

• 401 Unauthorized — key sai hoặc thiếu header xác thực.
• 403 Forbidden — key chưa được gán channel/model tương ứng.
• 429 Too Many Requests — vượt rate limit hoặc Budget, hãy giảm tốc độ gửi request và thử lại sau.

8. MCP (Cursor & Claude Code)

Kết nối Cursor hoặc Claude Code với các công cụ media của Thoth qua MCP từ xa.

MCP cung cấp gì

Thoth cung cấp một MCP server Streamable HTTP không lưu session tại endpoint hiển thị trên trang này. Endpoint này dành cho MCP tools và tách biệt với các API model tại /v1/*.

Điều kiện trước khi bắt đầu

Prompt gửi cho agent

Dán prompt sau vào agent. Đặt THOTH_API_KEY trong shell hoặc secret manager cục bộ; không gửi key vào chat. Agent phải merge cấu hình hiện có thay vì ghi đè toàn bộ file.

Configure Thoth MCP in this workspace. Do not print, request, or commit an API key.

MCP URL: https://thoth.rezlabs.io/mcp
Set THOTH_API_KEY locally in your shell or secret manager; never paste it into this chat.
Use ${env:THOTH_API_KEY} in Cursor config and ${THOTH_API_KEY} in Claude Code config.
Use this origin only (not workers.dev). Host/Origin hostname must be thoth.rezlabs.io.

Cursor: merge .cursor/mcp.json with a remote server (url + headers). type is optional.
Claude Code: merge .mcp.json and set "type": "http" (required when url is present).

Reload MCP, then list tools.
Empty tools/list with a valid key means entitlement is off or no media capacity is advertised.
mcp_media_unavailable or video_no_account means no eligible media capacity is available for the key.

Cursor — cấu hình tay

File .cursor/mcp.json (trong project) hoặc ~/.cursor/mcp.json (toàn máy). Settings → Tools & MCP để bật server. Dùng ${env:THOTH_API_KEY} nếu đã export biến môi trường.

{
  "mcpServers": {
    "thoth": {
      "url": "https://thoth.rezlabs.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THOTH_API_KEY}"
      }
    }
  }
}

Claude Code — cấu hình tay

File .mcp.json ở root project phải có "type": "http" và header dùng ${THOTH_API_KEY}. Không có type thì Claude Code coi như stdio và bỏ server. Sau đó approve MCP khi Claude hỏi.

{
  "mcpServers": {
    "thoth": {
      "type": "http",
      "url": "https://thoth.rezlabs.io/mcp",
      "headers": {
        "Authorization": "Bearer ${THOTH_API_KEY}"
      }
    }
  }
}

Hoặc dùng CLI:

'claude' 'mcp' 'add' '--transport' 'http' 'thoth' 'https://thoth.rezlabs.io/mcp' '--header' "Authorization: Bearer $THOTH_API_KEY"

Xác thực và public origin

Gửi key bằng Authorization: Bearer sk-... hoặc x-api-key: sk-.... Luôn dùng URL MCP được render trên trang này; hostname Host/Origin phải khớp public origin. Không thay URL này bằng hostname workers.dev.

Xác minh kết nối

Reload MCP client, xác nhận server thoth đã kết nối, rồi chạy tools/list. Lỗi xác thực nghĩa là key/header không hợp lệ; danh sách tools rỗng với key hợp lệ nghĩa là key chưa có media entitlement hoặc hiện không có media capacity được quảng bá.

Tool reference

Các provider option khả dụng được công bố trong live tool schema của client; hãy đọc schema hiện tại thay vì giả định một provider luôn tồn tại.

Quyền và khả năng hiển thị tool

Xử lý sự cố

• Missing/invalid key: kiểm tra prefix sk-, header và khoảng trắng sau Bearer.
• Host/Origin rejected: dùng đúng URL public trên trang này; không thay bằng hostname deployment khác.
• Không có tools: key có thể hợp lệ nhưng chưa được cấp media entitlement hoặc hiện không có media capacity được quảng bá.
• mcp_media_unavailable hoặc video_no_account: hiện không có media capacity phù hợp cho key; liên hệ quản trị viên dịch vụ.
• Invalid image/idempotency input: dùng data URI hoặc URL HTTP(S), key idempotency 1–128 ký tự, và không gửi đồng thời image với reference_images.
• Video pending: chờ số giây trong retry_after trước khi thử lại với cùng idempotency key.

Bảo mật key và output

Không print, log, chia sẻ hoặc commit API key hay payload base64. Ưu tiên biến môi trường/local config không được track. Nếu key bị lộ, hãy revoke hoặc rotate ngay và cập nhật các MCP client đang dùng.