Hướng dẫn dùng OpenAI Python SDK gọi API qua apicheap.store từng bước

05/11/2026 · apicheap.store

Nếu bạn đang viết ứng dụng Python và muốn gọi các model AI như Claude, GPT hay Gemini mà không cần quản lý nhiều API key từ nhiều nhà cung cấp, bạn có thể dùng thư viện openai chính thức của OpenAI và trỏ nó sang cổng apicheap.store. Bạn chỉ cần đổi base_url, api_key và tên model, còn cách gọi chat.completions giữ nguyên.

Bài này hướng dẫn từ bước cài thư viện, viết đoạn code đầu tiên, đến các tình huống nâng cao như stream phản hồi theo thời gian thực, đếm token trước khi gọi, và xử lý lỗi.

Chuẩn bị

Bạn cần ba thứ:

Python 3.10 trở lên đã cài trên máy (yêu cầu của bản openai mới nhất khi bài này được viết).
Tài khoản tại apicheap.store với số dư trong ví.
Một API key dạng sk-..., tạo trong mục API Keys của tôi của trang quản lý.

Nếu muốn hệ thống tự chuyển model dự phòng khi một model gặp sự cố, hãy vào tab Bộ combo trong trang quản lý để tạo combo trước. Nếu không cần dự phòng, bạn điền thẳng mã model lẻ có trong tab Mô hình AI.

Cài thư viện openai

Mở terminal và chạy:

pip install openai

Nếu đã cài rồi, hãy cập nhật lên phiên bản mới nhất để có đầy đủ tính năng:

pip install --upgrade openai

Gọi API lần đầu

Tạo file test_api.py với nội dung sau:

from openai import OpenAI

client = OpenAI(
    base_url="https://apicheap.store/v1",
    api_key="sk-YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="smart-live-combo",
    messages=[
        {"role": "user", "content": "Xin chào, bạn là ai?"}
    ]
)

print(response.choices[0].message.content)

Thay sk-YOUR_API_KEY bằng key thật của bạn, và smart-live-combo bằng tên combo hoặc mã model lẻ bạn đã chọn. Chạy python test_api.py để kiểm tra kết nối.

Hai dòng quan trọng là base_url và api_key. Cách gọi chat.completions.create() giống khi gọi trực tiếp API OpenAI, nhưng cổng này không có đủ mọi API của OpenAI. Trước khi dùng một tính năng khác, hãy xem danh sách endpoint trong tài liệu kết nối.

Nhận phản hồi theo thời gian thực (stream)

Khi model trả lời dài, bạn có thể nhận từng phần ngay khi nó được tạo ra thay vì đợi toàn bộ. Thêm stream=True vào lời gọi:

from openai import OpenAI

client = OpenAI(
    base_url="https://apicheap.store/v1",
    api_key="sk-YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="smart-live-combo",
    messages=[
        {"role": "system", "content": "Bạn là trợ lý viết nội dung sáng tạo."},
        {"role": "user", "content": "Viết đoạn mở đầu một câu chuyện phiêu lưu."}
    ],
    stream=True
)

for chunk in response:
    if not chunk.choices:
        continue
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)

Kết quả sẽ hiện ra từng chữ trên terminal thay vì chờ xong mới in một lần. Dòng if not chunk.choices là cần thiết vì chunk cuối của stream có thể chỉ chứa thống kê token, không có choices. Stream đặc biệt hữu ích khi bạn xây chatbot hoặc giao diện cần phản hồi nhanh.

Dùng biến môi trường thay vì ghi key vào code

Ghi API key thẳng vào code dễ bị lộ khi đẩy lên git. Cách an toàn hơn là đặt key vào biến môi trường.

Trên Windows (PowerShell):

[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-YOUR_API_KEY', 'User')
[System.Environment]::SetEnvironmentVariable('OPENAI_BASE_URL', 'https://apicheap.store/v1', 'User')

Trên macOS hoặc Linux, thêm vào ~/.zshrc hoặc ~/.bashrc:

export OPENAI_API_KEY="sk-YOUR_API_KEY"
export OPENAI_BASE_URL="https://apicheap.store/v1"

Mở terminal mới để biến có hiệu lực. Sau đó code Python chỉ cần viết:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="smart-live-combo",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

Thư viện openai tự đọc OPENAI_API_KEY và OPENAI_BASE_URL từ biến môi trường, nên bạn không cần truyền tham số nào khi khởi tạo OpenAI().

Đếm token trước khi gửi

Nếu bạn muốn ước lượng độ dài ngữ cảnh trước khi gọi model, cổng apicheap.store có endpoint đếm token riêng. Endpoint này chỉ ước lượng số token đầu vào và không gọi model nên không tốn phí. Ví dụ dưới dùng thư viện requests, không đi kèm openai, nên bạn cần cài thêm bằng pip install requests:

import requests

headers = {
    "x-api-key": "sk-YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "model": "smart-live-combo",
    "messages": [{"role": "user", "content": "Nội dung cần đếm token"}]
}

resp = requests.post(
    "https://apicheap.store/v1/messages/count_tokens",
    json=data,
    headers=headers
)
print(resp.json())

Kết quả trả về trường input_tokens cho biết ước lượng số token đầu vào. Đây là con số ước lượng thô, có thể lệch so với số token model tính thật, nên chỉ dùng để tham khảo khi quyết định có cắt bớt ngữ cảnh hay không.

Gọi model với system prompt

System prompt giúp bạn định hướng cách model trả lời. Đặt nó trong tin nhắn đầu tiên với role là system:

response = client.chat.completions.create(
    model="smart-live-combo",
    messages=[
        {"role": "system", "content": "Bạn là chuyên gia lập trình Python. Trả lời ngắn gọn, có code mẫu."},
        {"role": "user", "content": "Cách đọc file JSON trong Python?"}
    ]
)

Bạn có thể giữ system prompt cố định và thay đổi nội dung user theo từng câu hỏi, như cách các chatbot và trợ lý lập trình hoạt động.

Xử lý lỗi thường gặp

Khi gọi API qua thư viện openai, lỗi được ném ra dưới dạng exception. Bạn có thể bắt và xử lý chúng:

from openai import OpenAI, APIError, APIStatusError, AuthenticationError, RateLimitError

client = OpenAI(
    base_url="https://apicheap.store/v1",
    api_key="sk-YOUR_API_KEY"
)

try:
    response = client.chat.completions.create(
        model="smart-live-combo",
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.choices[0].message.content)
except AuthenticationError:
    print("Lỗi 401: API key sai hoặc đã bị vô hiệu hoá.")
except RateLimitError:
    print("Lỗi 429: Gửi quá nhiều request. Giảm số luồng song song rồi thử lại.")
except APIStatusError as e:
    print(f"Lỗi API: {e.status_code} - {e.message}")
except APIError as e:
    print(f"Lỗi kết nối hoặc lỗi trong stream: {e.message}")

Thứ tự các nhánh except là quan trọng: APIStatusError chứa mã HTTP trong status_code, còn lỗi kết nối không có mã này nên được bắt riêng ở nhánh APIError cuối cùng. Mặc định thư viện tự thử lại 2 lần với một số lỗi tạm thời trước khi ném exception.

Các mã lỗi phổ biến và cách xử lý chi tiết hơn có ở bài xử lý lỗi 401, 404, 429 khi gọi API.

Kiểm tra danh sách model khả dụng

Trước khi gọi, bạn có thể liệt kê các model và combo mà key được phép dùng:

from openai import OpenAI

client = OpenAI(
    base_url="https://apicheap.store/v1",
    api_key="sk-YOUR_API_KEY"
)

models = client.models.list()
for m in models.data:
    print(m.id)

Nếu tên model bạn truyền vào create() không tồn tại hoặc chưa được kích hoạt, bạn sẽ nhận lỗi 404. Riêng combo không còn model nào khả dụng sẽ trả lỗi 503, khi đó hãy cập nhật combo hoặc chọn model khác.

Gợi ý chọn model

Bạn có thể đổi model bất kỳ lúc nào bằng cách thay giá trị model trong lời gọi:

Việc cần suy luận sâu (phân tích code, viết thuật toán, review logic): dùng model mạnh.
Việc đơn giản (tóm tắt văn bản, trả lời FAQ, dịch ngắn): dùng model nhẹ hơn để tiết kiệm số dư.
Cần ổn định, ít gián đoạn: tạo combo với nhiều model dự phòng trong trang quản lý — khi model đầu gặp sự cố, hệ thống tự chuyển sang model tiếp theo.

Giá từng model xem ở bảng giá trên trang chủ.

Tóm tắt

Để gọi API AI qua apicheap.store bằng Python, bạn cài thư viện openai, đặt base_url là https://apicheap.store/v1 và api_key là key của bạn, rồi điền tên combo hoặc mã model lẻ. Các lời gọi chat.completions.create(), stream=True và models.list() viết như khi dùng API OpenAI trực tiếp. Tài liệu đầy đủ cho mọi endpoint và công cụ khác nằm ở trang tài liệu kết nối.