Gọi API của mô hình AI bằng Python: bài đầu tiên

Bài này theo trang Get started và trang Pricing trong tài liệu Claude, đọc ngày 11/11/2026. Cách làm với API của các hãng khác tương tự: cài thư viện, đặt khóa, gửi tin nhắn, đọc kết quả; chỉ khác tên hàm và tên trường.

Chuẩn bị

Theo trang Get started, bạn cần một tài khoản Claude Console, rồi chọn một trong hai cách xác thực: đăng nhập qua công cụ dòng lệnh (được khuyên dùng khi phát triển trên máy) hoặc tạo khóa API trong Console. Với cách dùng khóa, thư viện và công cụ dòng lệnh đọc khóa từ biến môi trường ANTHROPIC_API_KEY.

Tạo một thư mục dự án, một môi trường ảo, và cài thư viện như hướng dẫn chính thức:

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install anthropic

Đặt khóa trong biến môi trường (hoặc trong tệp .env đã có trong .gitignore), không bao giờ viết khóa vào code. Cách giữ khóa an toàn có trong bài giữ khóa API an toàn.

Lời gọi đầu tiên

Mã mẫu của trang Get started tạo client bằng anthropic.Anthropic(), gọi client.messages.create với model="claude-opus-5-5", max_tokens=1000 và một tin nhắn vai trò user, rồi duyệt qua các khối trong message.content, in khối có kiểu text. Đoạn code của bài làm đúng như vậy, thêm vài thứ bạn sẽ cần ngay: một chỉ dẫn hệ thống (system) bằng tiếng Việt, đọc số token, tính chi phí, cảnh báo khi câu trả lời bị cắt, và bắt lỗi.

"""Gọi API của Claude bằng Python: hỏi một câu, in câu trả lời, số token và chi phí ước tính.

Cài: python -m pip install anthropic
Khóa: đặt biến môi trường ANTHROPIC_API_KEY (thư viện tự đọc), không viết khóa vào code.
Giá (USD cho 1 triệu token, theo trang Pricing ngày 11/11/2026; xem lại trang trước khi dùng):
"""
import os
import sys

GIA = {  # (đầu vào, đầu ra) USD / 1 triệu token; Haiku 5.5 là giá cho prompt tới 100.000 token
    "claude-opus-5-5": (4.0, 20.0),
    "claude-sonnet-5-5": (2.0, 10.0),
    "claude-haiku-5-5": (0.10, 0.50),
}
HE_THONG = "Bạn là trợ giảng lập trình. Trả lời bằng tiếng Việt, ngắn gọn, có ví dụ nếu cần."


def chi_phi(mo_hinh, token_vao, token_ra):
    if mo_hinh not in GIA:  # tên mô hình lạ: báo trước, đừng để vỡ sau khi đã gọi và đã tốn tiền
        return None
    vao, ra = GIA[mo_hinh]
    return (token_vao * vao + token_ra * ra) / 1_000_000


def hoi(client, cau_hoi, mo_hinh="claude-opus-5-5", toi_da=1000):
    """Gửi một câu hỏi, trả về (chữ trả lời, token vào, token ra, lý do dừng)."""
    tin = client.messages.create(
        model=mo_hinh,
        max_tokens=toi_da,
        system=HE_THONG,
        messages=[{"role": "user", "content": cau_hoi}],
    )
    chu = "".join(k.text for k in tin.content if k.type == "text")
    return chu, tin.usage.input_tokens, tin.usage.output_tokens, tin.stop_reason


def in_ket_qua(mo_hinh, chu, vao, ra, ly_do):
    print(chu)
    print(f"[{mo_hinh}] token vào {vao}, token ra {ra}, chi phí khoảng {chi_phi(mo_hinh, vao, ra):.6f} USD")
    if ly_do == "max_tokens":
        print("Lưu ý: câu trả lời bị cắt vì chạm giới hạn max_tokens; tăng giới hạn hoặc hỏi ngắn hơn.")


def main(cau_hoi, mo_hinh):
    # Thư viện tự tìm cách xác thực: biến môi trường ANTHROPIC_API_KEY, hoặc hồ sơ đã đăng nhập bằng công cụ
    # dòng lệnh (cách trang Get started khuyên dùng khi làm trên máy). Chặn sẵn là bỏ mất cách thứ hai.
    if not os.environ.get("ANTHROPIC_API_KEY"):
        print("Không thấy ANTHROPIC_API_KEY; sẽ dùng hồ sơ đã đăng nhập bằng công cụ dòng lệnh nếu có.")
    import anthropic  # chỉ cần thư viện khi gọi thật
    client = anthropic.Anthropic()
    try:
        in_ket_qua(mo_hinh, *hoi(client, cau_hoi, mo_hinh))
    except anthropic.APIStatusError as e:  # lỗi từ phía API: khóa sai, hết hạn mức, quá tải...
        sys.exit(f"API báo lỗi {e.status_code}: {e.message}")
    except anthropic.APIConnectionError:
        sys.exit("Không kết nối được tới API. Kiểm tra mạng rồi thử lại.")


if __name__ == "__main__":
    cau = " ".join(sys.argv[1:]) or "Giải thích list comprehension trong Python bằng một ví dụ."
    main(cau, os.environ.get("MO_HINH", "claude-opus-5-5"))

Chạy python hoi_claude.py "câu hỏi của bạn". Muốn đổi mô hình, đặt biến môi trường MO_HINH, ví dụ claude-haiku-5-5 cho các thử nghiệm rẻ. Khi chưa đặt khóa, chương trình dừng với lời nhắn rõ ràng thay vì báo lỗi khó hiểu.

Đọc câu trả lời

Theo ví dụ JSON trong trang Get started, câu trả lời có các trường quan trọng:

• content: danh sách khối nội dung. Thường là khối text, nhưng có thể có loại khác (ví dụ khi bật suy nghĩ hay dùng công cụ), nên lọc theo type thay vì lấy thẳng phần tử đầu.
• stop_reason: vì sao mô hình dừng. end_turn là trả lời xong bình thường; max_tokens là bị cắt vì chạm giới hạn bạn đặt.
• usage: input_tokens và output_tokens, số token đã dùng ở đầu vào và đầu ra.

Ví dụ trong trang Get started có input_tokens là 21 và output_tokens là 305. Đoạn code của bài dùng đúng hai con số đó trong phần kiểm, để tính chi phí.

Token và chi phí

Mô hình tính tiền theo token (đơn vị văn bản nhỏ, thường là một phần của từ). Bảng giá ngày 11/11/2026 (USD cho một triệu token):

Với 21 token vào và 305 token ra, chi phí trên Opus 5.5 là 21 × 4 + 305 × 20 phần triệu USD, khoảng 0,006 USD; trên Haiku 5.5 khoảng 0,00015 USD. Hai điều rút ra: token ra đắt hơn token vào nhiều lần, nên giới hạn độ dài câu trả lời giúp tiết kiệm; và nên thử nghiệm với mô hình rẻ, chỉ dùng mô hình lớn khi bài toán cần. Giá thay đổi theo thời gian, luôn xem trang Pricing trước khi ước tính; Haiku 5.5 còn có giá khác cho prompt trên 100.000 token.

Xử lý lỗi

Các lỗi hay gặp lần đầu: chưa đặt khóa (chương trình dừng ngay với lời nhắn), khóa sai hoặc hết hạn mức (API trả mã lỗi, thư viện ném anthropic.APIStatusError có status_code), mất mạng hay sai địa chỉ (anthropic.APIConnectionError). Đoạn code bắt riêng hai loại lỗi này để in thông báo dễ hiểu. Khi gặp lỗi quá tải tạm thời, thư viện chính thức có cơ chế thử lại tự động; đừng tự viết vòng lặp gọi lại liên tục.

Chỉ dẫn hệ thống và độ dài câu trả lời

Hai tham số ảnh hưởng nhiều nhất tới kết quả mà người mới hay bỏ qua là chỉ dẫn hệ thống và giới hạn độ dài. Chỉ dẫn hệ thống là đoạn văn đặt khung cho cả cuộc trò chuyện: mô hình đóng vai gì, trả lời bằng ngôn ngữ nào, dài hay ngắn, giọng ra sao. Trong ví dụ, chỉ dẫn yêu cầu trả lời bằng tiếng Việt, ngắn gọn, có ví dụ; nhờ vậy bạn không phải nhắc lại điều đó trong từng câu hỏi. Giữ chỉ dẫn hệ thống ngắn, cụ thể, và đặt nó trong code để quản lý phiên bản như mọi thay đổi khác.

Giới hạn độ dài là số token tối đa mô hình được viết ra. Đặt quá nhỏ thì câu trả lời bị cắt giữa chừng; đặt quá lớn thì không sai, nhưng một câu trả lời dài lê thê sẽ tốn tiền vì token đầu ra đắt nhất. Cách làm hợp lý là ước lượng độ dài bạn thật sự cần, cộng thêm một khoảng dư, rồi theo dõi lý do dừng: nếu thường xuyên thấy câu trả lời bị cắt, tăng giới hạn hoặc yêu cầu trả lời ngắn hơn trong chỉ dẫn.

Hội thoại nhiều lượt

API không tự nhớ các lần gọi trước. Muốn mô hình trả lời tiếp theo ngữ cảnh, mỗi lần gọi bạn gửi lại cả lịch sử: tin nhắn của người dùng, câu trả lời trước đó của mô hình, rồi câu hỏi mới, xen kẽ theo thứ tự. Điều này có hai hệ quả thực tế. Thứ nhất, cuộc trò chuyện càng dài thì mỗi lần gọi càng nhiều token đầu vào và càng tốn tiền. Thứ hai, chính bạn quyết định mô hình "nhớ" gì: có thể rút gọn hay bỏ bớt phần cũ không cần thiết. Trang Working with the Messages API trong tài liệu chính thức mô tả cách xếp các tin nhắn này.

Một ứng dụng nhỏ để luyện

Sau lời gọi đầu tiên, hãy làm một ứng dụng nhỏ có ích cho chính bạn để luyện: một trợ giảng giải thích lỗi Python. Chương trình nhận đoạn thông báo lỗi bạn dán vào, gửi kèm chỉ dẫn "giải thích nguyên nhân và gợi ý cách sửa, không viết lại cả chương trình", rồi in câu trả lời cùng chi phí. Sau vài ngày dùng, ghi lại những câu trả lời sai hoặc dài dòng, chỉnh chỉ dẫn hệ thống, và so lại. Đó chính là vòng làm việc của người xây ứng dụng AI ở quy mô nhỏ: gọi, đo, sửa.

Đi tiếp từ đây

Khi lời gọi đầu tiên chạy được, các bước tiếp theo tự nhiên là: hội thoại nhiều lượt (gửi lại cả lịch sử tin nhắn mỗi lần, như trang Working with the Messages API hướng dẫn), cho mô hình trả lời theo tài liệu riêng bằng RAG (xem RAG là gì), và đo chất lượng câu trả lời bằng một bộ câu hỏi mẫu (xem đánh giá câu trả lời của AI). Nếu muốn thử mô hình mở chạy ngay trên máy, không cần khóa, xem chạy AI trên máy cá nhân.

Một thói quen tốt ngay từ đầu: ghi lại mỗi lần gọi (thời điểm, mô hình, số token, chi phí) vào một tệp log không chứa nội dung nhạy cảm. Sau một tuần thử nghiệm, bạn sẽ biết chính xác mình đã tiêu bao nhiêu và vào đâu.

Câu hỏi thường gặp

Học tiếp

• Giữ khóa an toàn trước khi đưa code lên GitHub: giữ khóa API an toàn.
• Cho mô hình trả lời theo tài liệu riêng: RAG là gì.
• Đo chất lượng câu trả lời: đánh giá câu trả lời của AI.

Nếu bạn muốn học Python và AI bài bản cùng giảng viên, tham khảo khóa học AI của Big-O Coding.

Nguồn tham khảo

• Claude Docs: Get started with Claude
• Claude Docs: Pricing
• Claude Docs: Working with the Messages API
• Claude Docs: Models overview