Tạo API key
Đăng nhập, mở Dashboard → Keys và tạo key. Sao chép key ngay lúc tạo; bạn sẽ không xem lại được đầy đủ sau đó.
Mở API KeysCài đặt API
Làm theo các bước này để nối ứng dụng của bạn với AI Gateway.
Chọn model
Chọn một model đang hoạt động trong danh mục. Dùng đúng Model ID hiển thị ở đó trong từng request.
Xem danh mục modelCấu hình địa chỉ API
Client OpenAI-compatible dùng Base URL bên dưới. Giữ phần /api/v1 để request đi đúng endpoint.
https://vfam.shop/api/v1
Cài SDK nếu cần
Nếu ứng dụng chưa có OpenAI SDK, cài gói cho ngôn ngữ bạn đang dùng. Gọi API bằng curl thì không cần cài SDK.
npm install openai
# Python: python -m pip install openai
Giữ API key an toàn
Đặt key trong biến môi trường, ví dụ OPENAI_API_KEY, thay vì ghi thẳng vào mã nguồn. Không chia sẻ key hoặc đưa key lên GitHub.
Kiểm tra kết nối bằng curl
curl https://vfam.shop/api/v1/chat/completions \
-H "Authorization: Bearer sk_cua_ban" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Xin chào!"}]}'Thay sk_cua_ban bằng API key của bạn. Nếu chưa biết Model ID, mở danh mục model ở bước 2. Phần Bắt đầu nhanh bên dưới giải thích request và phản hồi.
Bắt đầu nhanh
Ba bước là gọi được API đầu tiên.
Tạo API key
Dashboard → Keys → tạo key. Raw key chỉ hiển thị đúng một lần khi tạo.
Trỏ baseURL
Gateway tương thích OpenAI: baseURL là https://vfam.shop/api/v1, không cần SDK riêng.
Gọi thử
Một request curl là thấy phản hồi — hoặc dùng bất kỳ CLI/SDK OpenAI nào.
Gọi chat completion đầu tiên
curl https://vfam.shop/api/v1/chat/completions \
-H "Authorization: Bearer sk_cua_ban" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{ "role": "user", "content": "Xin chào!" }]
}'Phản hồi chuẩn OpenAI
{"id":"chatcmpl-9f2c41e8","object":"chat.completion","model":"gpt-4o-mini","choices":[{"index":0,"message":{"role":"assistant","content":"Chào bạn! 👋"},"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21}}Xác thực
Mọi request /api/v1/* đều yêu cầu API key trong header Authorization.
Header bắt buộc
Authorization: Bearer sk_cua_ban
# Kiểm tra key còn hạn mức — xem model nào được dùng:
curl https://vfam.shop/api/v1/models \
-H "Authorization: Bearer sk_cua_ban"Giữ key an toàn
Raw key chỉ hiển thị một lần khi tạo; server chỉ lưu hash. Không commit key vào repo hoặc nhúng key vào ứng dụng client công khai. Nếu key bị lộ, hãy đổi ngay tại Dashboard → Keys.
Endpoints
Gateway chỉ mở 3 route chuẩn OpenAI — client SDK OpenAI hiểu được luôn.
| Method | Endpoint | Mô tả |
|---|---|---|
| GET | /api/v1/models | Các model được phép dùng với key của bạn; thêm ?include_details=true để kèm giá và chế độ tính phí. |
| GET | /api/v1/models/:id | Chi tiết một model (giá, mô tả). |
| POST | /api/v1/chat/completions | Chat completion — dạng thường hoặc SSE streaming, hỗ trợ tools và response_format… |
Các tham số phổ biến của chat/completions:
model *messages *temperaturemax_completion_tokensmax_tokensstreamstream_options.include_usagetoolstool_choiceresponse_formatstopnseeduserModels từ API
Danh sách model thật được cấp cho tài khoản — lấy trực tiếp từ API gateway.
Đăng nhập để xem model của bạn
Model khả dụng phụ thuộc gói và key. Đăng nhập
Kết nối CLI
Mọi CLI hỗ trợ custom OpenAI-compatible endpoint đều chạy được — cấu hình một lần là xong.
Model trong ví dụ lấy từ API
Nếu đã đăng nhập, ví dụ tự dùng model đầu tiên:
gpt-4o-minicurl
Liệt kê model kèm giá để chọn model:
Models + pricing
curl -s "https://vfam.shop/api/v1/models?include_details=true" -H "Authorization: Bearer sk_cua_ban" | jq '.data[] | {id, billing_mode, input_price_per_1m_usd, output_price_per_1m_usd}'Codex CLI
~/.codex/config.toml
model = "gpt-4o-mini"
model_provider = "qwencoder"
[model_providers.qwencoder]
name = "QwenCoder"
base_url = "https://vfam.shop/api/v1"
env_key = "QWENCODER_API_KEY"
wire_api = "chat"Shell
export QWENCODER_API_KEY=sk_cua_ban
codex "refactor auth.ts"aider
Dùng biến môi trường OpenAI-compatible:
Shell
export OPENAI_API_BASE=https://vfam.shop/api/v1
export OPENAI_API_KEY=sk_cua_ban
aider --model openai/gpt-4o-minillm (datasette)
extra-openai-models.yaml
- model_id: qwencoder-model
model_name: gpt-4o-mini
api_base: "https://vfam.shop/api/v1"
api_key_name: qwencoderShell
llm keys set qwencoder
llm -m qwencoder-model "Explain API quotas"SDK OpenAI
Giữ nguyên SDK quen thuộc — chỉ đổi baseURL và apiKey.
Python — pip install openai
from openai import OpenAI
client = OpenAI(base_url="https://vfam.shop/api/v1", api_key="sk_cua_ban")
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Xin chào!"}],
)
print(resp.choices[0].message.content)TypeScript — npm i openai
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://vfam.shop/api/v1", apiKey: "sk_cua_ban" });
const resp = await client.chat.completions.create({
model: "gpt-4o-mini", messages: [{ role: "user", content: "Xin chào!" }],
});
console.log(resp.choices[0].message.content);Streaming (SSE)
Đặt stream: true — nhận chunk chuẩn OpenAI qua Server-Sent Events.
curl — cờ -N để tắt buffer
curl -N https://vfam.shop/api/v1/chat/completions -H "Authorization: Bearer sk_cua_ban" -H "Content-Type: application/json" -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Xin chào!"}],"stream":true,"stream_options":{"include_usage":true}}'TypeScript — in token ra màn hình
const stream = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Xin chào!" }], stream: true });
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");Usage ở chunk cuối
Bật stream_options.include_usage để chunk cuối có số token, khớp Dashboard → Usage.
Xử lý lỗi
Lỗi trả về đúng format chuẩn OpenAI — SDK tự parse được.
Format lỗi
{"error":{"message":"Provider timeout — thử lại sau.","type":"timeout_error","param":null,"code":"PROVIDER_TIMEOUT"}}| Mã | Trường hợp | Cách xử lý |
|---|---|---|
| 400 | Body sai chuẩn OpenAI (thiếu model/messages…) | Sửa lại payload |
| 401 | Key thiếu, sai, hết hạn hoặc đã thu hồi | Tạo key mới ở Dashboard → Keys |
| 429 | Vượt rate limit hoặc hàng đợi đầy | Đọc Retry-After rồi thử lại |
| 502 | Provider upstream lỗi | Thử lại hoặc đổi model |
| 503 | Provider tạm ngắt | Thử lại sau ít phút |
| 504 | Provider timeout | Thử lại sau |