Tài liệu API Stack

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 https://apistack.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,
    "messages": [
      { "role": "user", "content": "Viết hàm quicksort bằng Python" }
    ]
  }'

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

curl https://apistack.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.200đ/lượt) qua /v1/audio/speech:

curl https://apistack.vn/v1/audio/speech \
  -H "Authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "req/gpt-4o-mini-tts",
    "input": "Xin chào, đây là API Stack 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 Gắn vào ứng dụng AI.

Chọn đúng URL gốc

Đây là chỗ sai phổ biến nhất khi cấu hình. API Stack 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-stk-...        # kiểu Anthropic
Authorization: Bearer sk-stk-...     # kiểu OpenAI

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ã.

Gắn vào ứng dụng AI

Cấu hình phổ biến nhất bên dưới. Ở mọi ví dụ, thay sk-stk-... bằng key thật (hoặc dùng máy phát config trên Dashboard). Đổi model theo nhu cầu — xem bảng giá tại /pricing hoặc GET /v1/models.

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app claude-code \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app codex \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app openclaw \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app hermes \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app cursor \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app cline \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app continue \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app 9router \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app cliproxy \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

# Stali setup — patch an toàn (backup, không ghi đè cả file)
curl -fsSL "https://apistack.vn/install/stali-setup.sh" | bash -s -- \
  --app antigravity \
  --key 'sk-stk-...' \
  --base 'https://apistack.vn' \
  --yes

# Xem trước: thêm --dry-run
# Liệt kê app: --app list

export ANTHROPIC_API_BASE="https://apistack.vn"
export ANTHROPIC_API_KEY="sk-ash-..."

aider --model anthropic/claude-fable-5

{
  "language_models": {
    "anthropic": {
      "api_url": "https://apistack.vn",
      "available_models": [
        {
          "name": "claude-fable-5",
          "display_name": "Claude Fable 5",
          "max_tokens": 1000000
        }
      ]
    }
  },
  "agent": {
    "default_model": {
      "provider": "anthropic",
      "model": "claude-fable-5"
    }
  }
}

Copilot Chat → chọn model → "Manage Models…"
  Provider : Anthropic
  API Key  : sk-ash-...

Nếu bản cài cho phép đổi URL, dùng:
  https://apistack.vn

Bản không cho đổi URL thì chọn provider
"OpenAI Compatible" và dán https://apistack.vn/v1

Settings → Model Provider → Claude (Anthropic)
  API Host : https://apistack.vn
  API Key  : sk-ash-...
  Model    : claude-fable-5

# Hoặc chọn "OpenAI API Compatible":
  API Host : https://apistack.vn/v1
  Model    : gpt-5.6-sol

Cài đặt → Nhà cung cấp mô hình → Thêm (loại: Anthropic)
  Tên       : API Stack
  API Key   : sk-ash-...
  API Host  : https://apistack.vn
  Thêm model: claude-fable-5, claude-sonnet-5, claude-opus-5

# Thêm một nhà cung cấp thứ hai loại OpenAI nếu muốn dùng GPT/DeepSeek:
  API Host  : https://apistack.vn/v1

Admin Panel → Settings → Connections → OpenAI API
  API Base URL : https://apistack.vn/v1
  API Key      : sk-ash-...
  → Save, rồi tải lại trang để hiện danh sách model.

version: 1.2.8
endpoints:
  custom:
    - name: "API Stack"
      apiKey: "${STALI_API_KEY}"
      baseURL: "https://apistack.vn/v1"
      models:
        default: ["claude-fable-5", "claude-sonnet-5", "gpt-5.6-sol"]
        fetch: true
      titleConvo: true
      titleModel: "claude-fable-5"
      modelDisplayLabel: "API Stack"

OPENAI_API_KEY=sk-ash-...
OPENAI_PROXY_URL=https://apistack.vn/v1
OPENAI_MODEL_LIST=+claude-fable-5,+gpt-5.6-sol

# Anthropic riêng:
ANTHROPIC_API_KEY=sk-ash-...
ANTHROPIC_PROXY_URL=https://apistack.vn

API → Chat Completion
  Source        : Claude
  Claude API Key: sk-ash-...
  ☑ Use Custom Endpoint
  Endpoint      : https://apistack.vn
  Model         : claude-fable-5

# Hoặc Source: Custom (OpenAI-compatible)
  Endpoint : https://apistack.vn/v1

Settings → Model Provider → OpenAI-API-compatible → Add Model
  Model Name        : claude-fable-5
  API Key           : sk-ash-...
  API endpoint URL  : https://apistack.vn/v1
  Model type        : LLM
  Model context size: 1000000
  Max token limit   : 128000
  ☑ Vision support

Credentials → OpenAI (hoặc Anthropic)
  API Key  : sk-ash-...
  Base URL : https://apistack.vn/v1
             (nếu chọn Anthropic thì dùng https://apistack.vn)

Node "Basic LLM Chain" → Model: claude-fable-5

from anthropic import Anthropic

client = Anthropic(api_key="sk-ash-...", base_url="https://apistack.vn")
msg = client.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Xin chào!"}],
)
print(msg.content[0].text)

Ứng dụng bạn dùng không có trong danh sách? Chỉ cần nó cho phép nhập URL gốc tuỳ ý (thường ghi là “Custom base URL”, “API Host”, “OpenAI compatible” hoặc “Custom provider”) thì vẫn chạy được: dán URL ở mục Chọn đúng URL gốc cùng API key là xong.

Đ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://apistack.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": "Mô tả nội dung ảnh này"}
      ]
    }]
  }'

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": "Đọc nội dung ảnh này"},
      {
        "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 8 MB.

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

Đặt "stream": true để nhận Server-Sent Events. 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 1.800đ / 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. Nạp thêm tại https://apistack.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://apistack.vn/v1/messages -i \
  -H "x-api-key: sk-stk-..." \
  -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-stali-cost-vnd  -> đã sẵn sàng
# 401 -> key sai   402 -> hết số dư   404 -> sai URL gốc

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 8 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.