Gọi API trực tiếp

Địa chỉ và xác thực

Riêng Cherry Studio điền https://apivn.vn, không thêm /v1: Cherry tự nối thêm, điền thừa sẽ thành /v1/v1 và báo lỗi 404.

Xác thực bằng header Authorization: Bearer sk-...; đường kiểu Anthropic nhận cả header x-api-key. Khoá nằm ở Bảng điều khiển → Khóa API, dạng sk-...; đăng ký xong là đã có sẵn một khoá, bạn không phải tạo.

cURL

Xem khoá của bạn gọi được những mô hình nào:

curl https://apivn.vn/v1/models \
  -H "Authorization: Bearer $APIVN_API_KEY"

Gửi một tin nhắn qua Chat Completions:

curl https://apivn.vn/v1/chat/completions \
  -H "Authorization: Bearer $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Xin chào APIVN"}]
  }'

Responses API

Khoá nhóm Tự động gọi được. Codex CLI dùng endpoint này.

curl https://apivn.vn/v1/responses \
  -H "Authorization: Bearer $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.6-sol", "input": "Xin chào APIVN"}'

Messages API (Anthropic)

Khoá nhóm Tự động gọi được.

curl https://apivn.vn/v1/messages \
  -H "x-api-key: $APIVN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Xin chào APIVN"}]
  }'

Gemini API (Google)

Nếu mã của bạn đang viết theo thư viện Google GenAI thì không phải sửa gì ngoài địa chỉ và khoá. Đặt base URL là https://apivn.vn; thư viện tự thêm /v1beta phía sau. Xác thực bằng header x-goog-api-key.

curl https://apivn.vn/v1beta/models/gemini-3.8-flash:generateContent \
  -H "x-goog-api-key: $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Xin chào APIVN"}]}]
  }'

GET /v1beta/models liệt kê mọi mô hình khoá của bạn gọi được, không riêng Gemini — nên đừng ngạc nhiên khi thấy cả tên Claude trong đó.

Đọc giọng với Gemini

gemini-3.1-flash-tts-preview chỉ chạy qua đường Gemini gốc ở trên, không qua /v1/audio/speech. Đặt responseModalities là AUDIO và chọn giọng đọc; âm thanh trả về dạng PCM 24 kHz mã hoá base64 trong inlineData. Tiền tính theo token như mô hình chat.

curl https://apivn.vn/v1beta/models/gemini-3.1-flash-tts-preview:generateContent \
  -H "x-goog-api-key: $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Xin chào, đây là APIVN"}]}],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}}
    }
  }'

Tạo ảnh

Nhóm Image có sáu mô hình: gpt-image-2.5, gpt-image-2, nano-banana-pro, gemini-2.5-flash-image, grok-imagine-image-quality và grok-imagine-image. Khoá nhóm Tự động gọi được cả sáu, tính tiền theo từng ảnh (giá ở trang Mô hình). Một ảnh mất từ vài chục giây tới hơn một phút, nên đặt thời gian chờ của chương trình từ 300 giây trở lên. Cỡ ảnh: 1024x1024, 1536x1024 (ngang) hoặc 1024x1536 (dọc).

curl https://apivn.vn/v1/images/generations \
  -H "Authorization: Bearer $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Ly cà phê sữa đá trên bàn gỗ, ánh nắng buổi sáng",
    "size": "1024x1024"
  }'

Ảnh nằm ở data[0].url. Tải về và tự lưu ngay, vì đường dẫn này có thể hết hạn sau một thời gian. Riêng Grok Imagine trả ảnh JPEG trên máy chủ ảnh của xAI, nơi chặn chương trình tải không gửi User-Agent: mở bằng trình duyệt thì được, tải bằng mã thì nhớ gửi kèm header đó.

Bằng SDK Python:

result = client.images.generate(
    model="gpt-image-2",
    prompt="Ly cà phê sữa đá trên bàn gỗ",
    size="1024x1024",
)
print(result.data[0].url)

Sửa ảnh có sẵn

Gửi ảnh gốc kèm mô tả việc cần sửa tới /v1/images/edits, dạng form (multipart) chứ không phải JSON:

curl https://apivn.vn/v1/images/edits \
  -H "Authorization: Bearer $APIVN_API_KEY" \
  -F model=gpt-image-2.5 \
  -F image=@anh-goc.png \
  -F prompt="Đổi nền thành bãi biển lúc hoàng hôn" \
  -F size=1024x1024

Ảnh sửa xong trả về dạng base64 ở data[0].b64_json; giải mã rồi lưu thành tệp PNG.

Tạo video

Nhóm Video có ba mô hình: seedance-2.0-fast, grok-imagine-video và minimax-h3. Khoá nhóm Tự động gọi được cả ba. Tiền tính theo số giây video bạn xin (giá ở trang Mô hình), trừ ngay khi gửi yêu cầu. Video làm không thành thì được hoàn tiền.

Tạo video là việc chạy nền, gồm ba bước:

1. POST /v1/videos gửi yêu cầu, nhận về id.
2. GET /v1/videos/{id} hỏi trạng thái mỗi 10–15 giây cho tới khi status là completed (thường 1–3 phút).
3. GET /v1/videos/{id}/content tải file MP4.

curl https://apivn.vn/v1/videos \
  -H "Authorization: Bearer $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Chiếc thuyền giấy đỏ trôi trên mặt hồ lúc bình minh",
    "seconds": "6",
    "size": "1280x720"
  }'

curl https://apivn.vn/v1/videos/task_xxx \
  -H "Authorization: Bearer $APIVN_API_KEY"

curl -o video.mp4 https://apivn.vn/v1/videos/task_xxx/content \
  -H "Authorization: Bearer $APIVN_API_KEY"

Streaming

Thêm "stream": true để nhận câu trả lời theo từng đoạn. Với cURL, thêm -N để in ra ngay khi có:

curl -N https://apivn.vn/v1/chat/completions \
  -H "Authorization: Bearer $APIVN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "stream": true,
    "messages": [{"role": "user", "content": "Xin chào"}]
  }'

Phản hồi mang Content-Type: text/event-stream; mỗi đoạn là một dòng data: ..., và Chat Completions kết thúc bằng data: [DONE].

Python

Cài SDK: pip install openai.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIVN_API_KEY"],
    base_url="https://apivn.vn/v1",
)

reply = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Xin chào APIVN"}],
)
print(reply.choices[0].message.content)

Node.js

Cài SDK: npm install openai.

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.APIVN_API_KEY,
  baseURL: 'https://apivn.vn/v1',
})

const reply = await client.chat.completions.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: 'Xin chào APIVN' }],
})
console.log(reply.choices[0].message.content)

Chỉ gọi API từ phía máy chủ. Đừng đưa khoá vào mã chạy trên trình duyệt hay biến môi trường public của framework.

Postman

Tạo request GET https://apivn.vn/v1/models với header Authorization: Bearer {{APIVN_API_KEY}}. Cất khoá trong biến loại secret của Environment và đừng đồng bộ giá trị thật lên workspace dùng chung.

Dùng APIVN làm nguồn cho hệ thống relay

Nếu hệ thống của bạn tự nối thêm /v1/..., điền https://apivn.vn; nếu ô nhập đòi Base URL OpenAI đầy đủ, điền https://apivn.vn/v1. Gọi /models trước để chắc đường dẫn không bị lặp thành /v1/v1. Dùng một khoá riêng có hạn mức cho relay, tách khỏi khoá cá nhân.