Tài liệu MonkeyTech API

Bắt đầu nhanh

Ba bước: tạo tài khoản, nạp tiền, rồi tạo API key trong bảng điều khiển. Sau đó gửi lượt gọi đầu tiên:

curl -N https://api.monkeytech.vn/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      { "role": "user", "content": "Write a quicksort function in Python" }
    ]
  }'

Tạo ảnh với req/gpt-image-2 (650đ/ảnh) qua /v1/images/generations:

curl https://api.monkeytech.vn/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "req/gpt-image-2",
    "prompt": "a tiny red circle on white",
    "size": "1024x1024",
    "n": 1
  }'

TTS với req/gpt-4o-mini-tts (1.350đ/lượt) qua /v1/audio/speech:

curl https://api.monkeytech.vn/v1/audio/speech \
  -H "Authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "req/gpt-4o-mini-tts",
    "input": "Hello, đây là MonkeyTech API TTS.",
    "voice": "alloy"
  }' \
  --output speech.mp3

Chưa muốn viết mã? Mở Studio AI để gọi thử chat trên trình duyệt, hoặc kéo xuống mục Cài stali-cli.

Cài stali-cli

Cài stali-cli một lần — wizard tự cấu hình Claude Code, Codex, OpenClaw, Cline và 9 công cụ AI khác (có backup file).

1. Tạo API key tại Dashboard → Keys.
2. Chọn tab hệ điều hành bên dưới → sao chép lệnh cài → dán terminal.
3. Wizard mở sau khi cài — dán API key, chọn app và model.
4. Kiểm tra: stali doctor · Cập nhật: stali update.

# Install stali-cli (wizard 13 công cụ AI)
curl -fsSL "https://api.monkeytech.vn/install/stali-cli.sh" | bash

# Chỉ cài, không mở wizard:
# STALI_CLI_NO_RUN=1 curl -fsSL "https://api.monkeytech.vn/install/stali-cli.sh" | bash

# Mở wizard — dán API key khi được hỏi
stali -k 'sk-mtk-...'

Windows: không dùng curl … | bash trên CMD. Chọn tab PowerShell hoặc CMD.

Repo: github.com/ngocvu/stali-cli. Hoặc mở Kết nối ứng dụng trên Dashboard để lấy lệnh đã điền sẵn API key.

Chọn đúng URL gốc

Đây là chỗ sai phổ biến nhất khi cấu hình. MonkeyTech API có hai URL gốc tuỳ theo giao thức mà ứng dụng của bạn nói — dán nhầm sẽ ra lỗi 404 chứ không phải 401.

Không chắc app của mình thuộc kiểu nào? Cứ thử URL không có /v1 trước; nếu app báo 404 thì đổi sang URL có /v1. Model Claude gọi /v1/chat/completions và model GPT gọi /v1/messages được cổng chuyển định dạng (kèm tool calling) giữa Messages ↔ Chat Completions.

Xác thực

Chấp nhận cả hai kiểu tiêu đề xác thực, dùng kiểu nào cũng được:

x-api-key: sk-mtk-...        # Anthropic style
Authorization: Bearer sk-mtk-...     # OpenAI style

Key mới được lưu dưới dạng mã băm để xác thực và mã hóa AES-256-GCM để chính chủ có thể xem hoặc sao chép lại trong bảng điều khiển. Key cũ được tạo trước tính năng này không thể khôi phục. Mỗi tài khoản tối đa 10 key hoạt động cùng lúc.

Nên tạo mỗi máy hoặc mỗi ứng dụng một key riêng: khi lộ key bạn chỉ cần thu hồi đúng key đó, và trang Sử dụng sẽ tách được chi phí theo từng key. Không dán key vào mã nguồn đẩy lên Git — hãy đặt trong biến môi trường hoặc tệp cấu hình nằm ngoài kho mã.

Điểm cuối API

Bạn không bị ràng buộc model theo điểm cuối chat: gửi Claude tới /v1/chat/completions hoặc GPT tới /v1/messages đều được — cổng chuyển qua lại giữa Messages và Chat Completions (kể cả tools). Riêng model tạo ảnh (req/gpt-image-2) chỉ dùng /v1/images/generations; TTS (req/gpt-4o-mini-tts) chỉ dùng /v1/audio/speech. Endpoint /v1/responses giữ nguyên định dạng OpenAI Responses.

Đọc hình ảnh

Các model có nhãn Vision nhận được ảnh PNG/JPEG/WebP/GIF. Với nhóm Claude qua Anthropic Messages, gửi ảnh base64 trong cùng mảng content với câu hỏi:

curl https://api.monkeytech.vn/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 512,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgoAAA..."
          }
        },
        {"type": "text", "text": "Describe this image"}
      ]
    }]
  }'

8 model GPT dùng trực tiếp chuẩn OpenAI image_url tại /v1/chat/completions. Cổng trung chuyển hỗ trợ cả URL dữ liệu base64 và URL ảnh http(s):

{
  "model": "gpt-5.6-sol",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Read the content of this image"},
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAA..."}
      }
    ]
  }]
}

Token hình ảnh do nhà cung cấp trả về sẽ được ghi nhận và tính phí như token đầu vào. Nên nén ảnh trước khi gửi và giữ toàn bộ nội dung yêu cầu dưới giới hạn 20 MB.

Phản hồi dạng luồng

Nên đặt "stream": true (mặc định trong ví dụ SDK). Không stream thì client phải chờ hết JSON — câu dài có thể 40s+. Chuỗi sự kiện được chuyển tiếp nguyên trạng theo điểm cuối đang gọi. Với Anthropic: message_start → content_block_delta (nhiều lần) → message_delta → message_stop. Với OpenAI, dữ liệu giữ định dạng chat.completion.chunk hoặc Responses API. Chi phí được chốt khi luồng phản hồi kết thúc.

event: content_block_delta
data: {"delta":{"text":"Hello","type":"text_delta"},"index":0,"type":"content_block_delta"}

event: message_delta
data: {"delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":128}}

Tiêu đề phản hồi

Với lượt gọi dạng luồng, các tiêu đề token/chi phí không có sẵn (chi phí chỉ biết khi luồng kết thúc) — hãy tra trong trang Sử dụng.

Tính phí

Mọi lượt gọi trừ vào số dư ví theo token thực dùng: Claude Fable 8.300đ; Opus/Sonnet 6.500đ; GPT 2.400đ / 1.000.000 token, DeepSeek tính cố định mỗi lượt gọi (hoặc theo token với Flash). Lỗi xác thực, dữ liệu không hợp lệ hoặc lỗi 4xx/5xx từ nhà cung cấp không bị trừ tiền.

Nạp ví qua VietQR. Mã đơn nạp bắt đầu bằng ST — hãy gửi đúng mã này khi cần đối chiếu giao dịch với bộ phận hỗ trợ.

Mã lỗi

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Balance exhausted. Top up at https://api.monkeytech.vn/dashboard/topup"
  }
}

Khắc phục sự cố

Trước khi báo lỗi, hãy chạy lệnh kiểm tra kết nối này — nó cho biết ngay vấn đề nằm ở key, ở số dư hay ở URL:

curl https://api.monkeytech.vn/v1/messages -i \
  -H "x-api-key: sk-mtk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-fable-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}' | head -20

# 200 with x-stali-cost-vnd header  -> ready
# 401 -> wrong key   402 -> out of balance   404 -> wrong base URL

Giới hạn

• 5000 lượt gọi/phút/API key trên toàn hệ thống (cần cao hơn thì liên hệ).
• Nội dung yêu cầu tối đa 20 MB.
• Claude: ngữ cảnh tối đa 1.000.000 token, đầu ra tối đa 128.000 token; GPT/DeepSeek/AWS theo giới hạn từng model (xem /v1/models).
• Tối đa 10 API key hoạt động mỗi tài khoản.
• Thời gian chờ mỗi lượt gọi: 15 phút.