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: sk-mtk-..." \
  -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 ($0.0455/ảnh) qua /v1/images/generations:

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

Ảnh tham chiếu (edits) với req/gpt-image-2 ($0.0455/ảnh) qua /v1/images/edits — gửi `image` / `image_url` (URL http(s), data URL hoặc base64) hoặc alias `reference_image` / `ref_image` + prompt:

curl https://api.monkeytech.vn/v1/images/edits \
  -H "Authorization: Bearer sk-mtk-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "req/gpt-image-2",
    "prompt": "keep the same subject, soft studio lighting",
    "image": "https://example.com/reference.png",
    "size": "1024x1024",
    "n": 1
  }'

# image / image_url / reference_image / ref_image:
# data URL, base64 thuần, hoặc URL http(s) công khai

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

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

Tạo video qua POST /v1/videos. Mẫu gọi, bảng giá và tham số nằm ở mục Tạo video.

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 API CLI · Kết nối ứng dụng.

Cài API CLI

Cài API 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).

Win / macOS / Linux giống nhau: khuyến nghị npm install -g API CLI@latest (cần Node.js ≥ 18). One-liner curl/irm là alternate (npm bên trong). Chỉ fallback GitHub + Bun khi npm lỗi.

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: api-cli doctor · Cập nhật: api-cli update.

# Khuyến nghị (Win / macOS/Linux giống nhau) — cần Node.js >= 18
npm install -g API CLI@latest

# Hoặc one-liner (npm bên trong; fallback GitHub+Bun nếu npm lỗi):
# curl -fsSL "https://api.monkeytech.vn/install/api-cli.sh" | bash

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

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

Windows: dùng tab PowerShell hoặc CMD (không dùng curl … | bash trên CMD). Cùng luồng npm như macOS/Linux.

Repo: api.monkeytech.vn. Hoặc mở Kết nối ứng dụng trên Dashboard để lấy lệnh đã điền sẵn API key.

Kết nối ứng dụng

Chọn đúng app → làm đúng từng bước (URL, file path Win/macOS/Linux, Settings, lệnh kiểm tra). Dưới đây là hướng dẫn đầy đủ cho các app phổ biến; xem toàn bộ catalogue để mở từng trang riêng.

Chi tiết nhanh (app phổ biến) — Claude Code, Codex CLI, OpenClaw, Hermes, Cline, Cursor, Claude Desktop — bấm “Hướng dẫn đầy đủ” để xem path Win/macOS/Linux, Settings, kiểm tra và lỗi:

npm install -g API CLI@latest
api-cli configure claude -k 'sk-mtk-...' -m claude-fable-5
api-cli doctor

npm install -g API CLI@latest
api-cli configure codex -k 'sk-mtk-...' -m gpt-5.6-sol
# API key (dán vào cấu hình app): sk-mtk-...
codex

api-cli configure openclaw -k 'sk-mtk-...' -m claude-fable-5

# ~/.hermes/config.yaml
model:
  default: "claude-fable-5"
  provider: "custom"
  base_url: "https://api.monkeytech.vn/v1"
  api_key: "sk-mtk-..."

# Hoặc tách secret sang ~/.hermes/.env:
# OPENAI_API_KEY=sk-mtk-...

1. Mở Claude Desktop → Settings
2. Tìm mục API key / Custom endpoint / Developer
3. Nếu CÓ ô Base URL + API key:
     Base URL : https://api.monkeytech.vn
     API Key  : sk-mtk-...
     Model    : claude-fable-5 (nếu chọn được)
4. Nếu KHÔNG có ô đó:
     → Cài Claude Code + api-cli configure claude
     → Hoặc dùng AI Studio / Chatbox trên MonkeyTech API

Cursor → Settings → Models
  OpenAI API Key : sk-mtk-...
  ☑ Override OpenAI Base URL
  Base URL       : https://api.monkeytech.vn/v1

Thêm Model Names (nếu cần):
  claude-fable-5
  claude-sonnet-5
  gpt-5.6-sol

Bấm Verify / dùng Chat với model vừa thêm.

api-cli configure cline -k 'sk-mtk-...' -m claude-fable-5

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) dùng /v1/images/generations hoặc /v1/images/edits (ảnh tham chiếu); TTS (req/gpt-4o-mini-tts) chỉ dùng /v1/audio/speech; model video chỉ dùng /v1/videos. Endpoint /v1/responses giữ nguyên định dạng OpenAI Responses.

Tạo video

Chuẩn OpenAI Videos. POST /v1/videos trả ngay trạng thái queued kèm id. Gọi GET /v1/videos/{id} đến khi completed, rồi GET /v1/videos/{id}/content để tải MP4. DELETE /v1/videos/{id} hủy task đang chờ. SDK Python dùng videos.create_and_poll() rồi videos.download_content().

google-omni-flash $0.15/video. veo-3.1 $0.1136/video. seedance-2.0-fast: 5 giây $0.10, 10 giây $0.1682, 15 giây $0.2591. seedance-2.5: 5 giây $0.1273, 10 giây $0.1955, 15 giây $0.2864, 20–30 giây $0.4227. Không gửi seconds thì tính 5 giây. Ảnh tham chiếu, last_frame và 1080p không phụ thu.

Tiền trừ khi POST tạo video trả thành công. Tra tiến độ, tải MP4 và hủy task không trừ thêm. Lỗi 4xx/5xx hoặc seconds không hợp lệ không trừ tiền.

curl https://api.monkeytech.vn/v1/videos \
  -H "Authorization: Bearer sk-mtk-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "Cinematic drone shot flying through neon Tokyo at night",
    "seconds": 10,
    "aspect_ratio": "16:9"
  }'

# 200 ngay, status queued + id. Rồi poll đến completed.

Đọ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: sk-mtk-..." \
  -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"}
      ]
    }]
  }'

16 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 $0.3773; Opus/Sonnet $0.2955; GPT $0.1091 / 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": "Số dư đã hết. Top up tại 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 kèm tiêu đề x-monkeytech-cost-vnd  -> đã sẵn sàng
# 401 -> wrong key   402 -> out of balance   404 -> wrong base URL

Giới hạn

• Không giới hạn RPM và TPM.
• 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.