AI CODING GATEWAY · TÀI LIỆU

Kết nối API trong 5 phút

Dùng curl, Codex CLI, aider hoặc SDK Python/JS với một API key và base URL.

OpenAI-compatibleStreaming SSEPython · JS · CLI
Base URL của gatewayhttps://vfam.shop/api/v1
Request mẫuPOST /api/v1/chat/completions

const response = await client.chat.completions.create({

model: "your-model-id",

messages: [{

role: "user",

content: "Hello, gateway!"

}],

});

Phản hồi streaming từ gateway200 OK
Một endpoint cho các model/api/v1

Video demo · Z-Code

Xem video hướng dẫn, tải Z-Code và kết nối với API của CodeAI.

Tải Z-Code

Mở trang tải chính thức và chọn bản cài đặt phù hợp với hệ điều hành của bạn.

4 bước kết nối

  1. 01

    Tải và cài đặt Z Code

    Tải Z Code cho hệ điều hành của bạn, cài đặt và mở thư mục dự án.

  2. 02

    Tạo API key

    Đăng nhập và tạo key trong bảng điều khiển.

  3. 03

    Chọn model

    Dùng model ID từ danh mục đang hoạt động.

  4. 04

    Kết nối công cụ và chạy code

    Trong Z Code: Manage Models → Add Provider → OpenAI. Nhập Base URL, API key và Model ID từ CodeAI, sau đó bật provider để chạy request.

Kết nối Z Code với API của CodeAI

Minh họa cấu hình · dùng key và Model ID từ tài khoản của bạn.

Z Code / Manage Models / Add Provider
Provider
CodeAI · OpenAI
Base URL
https://vfam.shop/api/v1
API key
•••••••• · API key của bạn
Model ID
Model ID từ danh mục CodeAI
my-project

Đọc dự án và giúp tôi xây dựng tính năng mới.

CodeAI · Chọn model vừa thêm và gửi yêu cầu đầu tiên

Cà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.

01

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 Keys
02

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 model
03

Cấ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
04

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.

1

Tạo API key

Dashboard → Keys → tạo key. Raw key chỉ hiển thị đúng một lần khi tạo.

2

Trỏ baseURL

Gateway tương thích OpenAI: baseURL là https://vfam.shop/api/v1, không cần SDK riêng.

3

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.

MethodEndpointMô tả
GET/api/v1/modelsCá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/:idChi tiết một model (giá, mô tả).
POST/api/v1/chat/completionsChat 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_formatstopnseeduser

Models 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-mini

curl

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-mini

llm (datasette)

extra-openai-models.yaml
- model_id: qwencoder-model
  model_name: gpt-4o-mini
  api_base: "https://vfam.shop/api/v1"
  api_key_name: qwencoder
Shell
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ợpCách xử lý
400Body sai chuẩn OpenAI (thiếu model/messages…)Sửa lại payload
401Key thiếu, sai, hết hạn hoặc đã thu hồiTạo key mới ở Dashboard → Keys
403Gói hiện tại chưa có quyền dùng modelChọn model khác hoặc nâng cấp gói
429Vượt rate limit hoặc đã hết quotaĐọc Retry-After; kiểm tra quota hoặc nâng cấp gói
502Provider upstream lỗiThử lại hoặc đổi model
503Provider tạm ngắtThử lại sau ít phút
504Provider timeoutThử lại sau

Sẵn sàng gọi API đầu tiên?

Tạo key ở Dashboard → Keys, trỏ baseURL về https://vfam.shop/api/v1 là chạy ngay.