DEV Community

Cover image for Cách sử dụng API GLM-5.3-Flash (Với đầu vào hình ảnh)
Sebastian Petrus
Sebastian Petrus

Posted on Originally published at apidog.com

Cách sử dụng API GLM-5.3-Flash (Với đầu vào hình ảnh)

Cách dùng API GLM-5.3-Flash: văn bản, hình ảnh, streaming và công cụ

GLM-5.3-Flash tương thích với OpenAI: chỉ cần trỏ client hiện có sang URL cơ sở mới và đổi ID mô hình. Điểm khác biệt quan trọng là đầu vào hình ảnh—mô hình GLM-5 đầu tiên nhận hình ảnh và văn bản trong cùng một yêu cầu.

Dùng thử Apidog ngay hôm nay

Bài này hướng dẫn lấy khóa API, gọi văn bản, gửi hình ảnh, điều chỉnh suy luận, streaming, gọi công cụ, xử lý lỗi và kiểm soát chi phí. Mọi ví dụ dùng glm-5.3-flash.

Tìm hiểu thêm trước khi tích hợp:

Lấy khóa API

Tạo tài khoản tại z.ai, mở mục API key trong dashboard và tạo khóa. Đặt khóa trong biến môi trường, không đưa vào mã nguồn:

export ZAI_API_KEY="your-key-here"
Enter fullscreen mode Exit fullscreen mode

URL cơ sở của API tiêu chuẩn:

https://api.z.ai/api/paas/v4/
Enter fullscreen mode Exit fullscreen mode

Nếu kết nối Claude Code hoặc Cline, hãy dùng URL cơ sở dành cho coding plan theo hướng dẫn Claude Code và Cline.

Thực hiện cuộc gọi đầu tiên

SDK OpenAI hoạt động trực tiếp với URL cơ sở mới.

Python 

from openai import OpenAI
import os

client = OpenAI(
    [REDACTED CREDENTIAL],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {"role": "user", "content": "Giải thích KV cache là gì trong hai câu."}
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

cURL 

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "[REDACTED CREDENTIAL] $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [
      {"role": "user", "content": "Giải thích KV cache là gì trong hai câu."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Node.js 

import OpenAI from "openai";

const client = new OpenAI({
  [REDACTED CREDENTIAL],
  baseURL: "https://api.z.ai/api/paas/v4/",
});

const response = await client.chat.completions.create({
  model: "glm-5.3-flash",
  messages: [
    { role: "user", content: "Giải thích KV cache là gì trong hai câu." },
  ],
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

Ngoài base_url và model, đây là API OpenAI tiêu chuẩn. Vì vậy, bạn có thể thử nghiệm việc chuyển đổi mô hình với chi phí tích hợp thấp.

Gửi hình ảnh

Khác với GLM-5.3, GLM-5.3-Flash nhận hình ảnh thông qua mảng khối nội dung. content không còn là một chuỗi đơn lẻ:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Ảnh chụp màn hình này cho thấy một lỗi hiển thị. Bố cục có vấn đề gì?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshots/broken-layout.png"
                    },
                },
            ],
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

Quy tắc payload đa phương thức

  1. Dùng URL công khai hoặc URL dữ liệu Base64. Với ảnh cục bộ hoặc riêng tư, hãy mã hóa Base64: 
import base64

with open("broken-layout.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

image_block = {
    "type": "image_url",
    "image_url": {"url": f"data:image/png;base64,{encoded}"},
}
Enter fullscreen mode Exit fullscreen mode
  1. Mỗi ảnh là một khối image_url. Để so sánh thiết kế và bản triển khai: 
content = [
    {"type": "text", "text": "Hình ảnh thứ hai có khớp với thiết kế trong hình ảnh đầu tiên không?"},
    {"type": "image_url", "image_url": {"url": design_data_url}},
    {"type": "image_url", "image_url": {"url": built_data_url}},
]
Enter fullscreen mode Exit fullscreen mode
  1. Thứ tự có ý nghĩa. Đặt hướng dẫn văn bản trước ảnh liên quan. Ví dụ, câu hỏi “So sánh hai cái này” nên đứng trước hai khối hình ảnh.

Tài liệu của Z.ai cũng hỗ trợ video và tệp theo cơ chế content block. Hãy xác thực bằng dữ liệu thực tế trước khi xây dựng tính năng phụ thuộc vào đầu vào video.

Để xem quy trình từ ảnh chụp màn hình sang mã và cách kết hợp ảnh với tài liệu dài trong cửa sổ 1 triệu token, hãy đọc hướng dẫn vision API GLM-5.3-Flash.

Điều chỉnh mức suy luận

GLM-5.3-Flash hỗ trợ ba mức reasoning_effort: low, high và max.

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Tái cấu trúc hàm này để dễ hiểu hơn."}],
    extra_body={"reasoning_effort": "low"},
)
Enter fullscreen mode Exit fullscreen mode

Mặc định là max, cũng là chế độ tốn kém nhất. Với phân loại hoặc trích xuất số lượng lớn, đặt rõ low để giảm đáng kể token đầu ra.

low là cấp độ mới so với GLM-5.2, vốn chỉ có high và max.

Trong OpenAI Python SDK, reasoning_effort phải nằm trong extra_body vì đây không phải trường của schema OpenAI chuẩn. Khi gọi cURL, đây là trường cấp cao nhất trong JSON.

Tham số lấy mẫu đề xuất

Z.ai đề xuất các giá trị sau:

Trường hợp sử dụng temperature top_p
Chung 1.0 0.95
Mã hóa 0.95 1.0

Khác biệt nhỏ, nhưng cấu hình mã hóa đáng thử nếu đầu ra mã không ổn định.

Streaming

Dùng ngữ nghĩa streaming tiêu chuẩn của OpenAI:

stream = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Viết một tập lệnh bash để xoay vòng nhật ký."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

Theo Artificial Analysis, GLM-5.3-Flash tạo khoảng 49 token/giây, chậm hơn GLM-5.3 ở khoảng 86 token/giây. Token đầu tiên xuất hiện sau khoảng 1,52 giây: phù hợp cho giao diện hội thoại, nhưng cần tính đến khi tạo tài liệu dài theo lô.

Gọi công cụ

GLM-5.3-Flash dùng schema tool chuẩn của OpenAI:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_deployment_status",
            "description": "Trả về trạng thái hiện tại của một triển khai được đặt tên.",
            "parameters": {
                "type": "object",
                "properties": {
                    "service": {
                        "type": "string",
                        "description": "Tên dịch vụ, ví dụ: 'checkout-api'.",
                    }
                },
                "required": ["service"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "checkout-api có ổn không?"}],
    tools=tools,
)

call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
Enter fullscreen mode Exit fullscreen mode

Các benchmark tác nhân do Z.ai công bố cho thấy AutomationBench đạt 48.8, so với 26.2 ở GLM-5.2. Đây là số liệu của nhà cung cấp, nhưng phù hợp với định hướng tối ưu cho các vòng lặp gọi công cụ hơn là hội thoại một lượt.

Nếu muốn tạo tool definition từ API hiện có, hãy xem cách chuyển OpenAPI specification thành công cụ tác nhân.

Xử lý lỗi cần có trong production

1. Giới hạn tốc độ

Dùng exponential backoff kèm jitter. Tránh khoảng thời gian retry cố định vì nhiều worker có thể retry đồng thời.

import time, random
from openai import RateLimitError

def call_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            if attempt == 4:
                raise
            time.sleep((2 ** attempt) + random.random())
Enter fullscreen mode Exit fullscreen mode

2. Tràn ngữ cảnh

Cửa sổ 1 triệu token rất lớn, nhưng tài liệu dài kết hợp với nhiều hình ảnh độ phân giải cao vẫn có thể vượt giới hạn. Hình ảnh cũng tiêu tốn ngữ cảnh, nên hãy theo dõi token đầu vào trước khi gửi yêu cầu.

3. Đầu ra bị cắt cụt

Nếu phản hồi dừng giữa câu, hãy kiểm tra finish_reason. Giá trị length nghĩa là yêu cầu đã chạm giới hạn đầu ra, không phải mô hình tự dừng.

Đọc mức sử dụng token

Mỗi phản hồi chứa usage:

print(response.usage.prompt_tokens, response.usage.completion_tokens)
Enter fullscreen mode Exit fullscreen mode

Đặc biệt theo dõi completion_tokens. Với reasoning_effort="max", token suy luận được tính như token đầu ra, nên phản hồi ngắn vẫn có thể tốn nhiều token hoàn thành.

Cách nhanh nhất để chọn cấu hình phù hợp là chạy cùng prompt ở các mức low, high và max, sau đó so sánh completion_tokens.

Chi phí

Giá niêm yết:

  • Đầu vào: 0,15 USD / một triệu token
  • Đầu ra: 0,50 USD / một triệu token
  • Đầu vào cache: 0,03 USD / một triệu token

Chương trình giảm giá ra mắt 50% kéo dài đến ngày 9 tháng 9 năm 2026, đưa giá xuống lần lượt còn 0,075 USD, 0,25 USD và 0,015 USD.

Giá có thể khác giữa OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra và các nhà cung cấp khác. Xem phân tích giá GLM-5.3-Flash, đồng thời luôn xác minh giá trực tiếp với nhà cung cấp trước khi lập ngân sách.

Kiểm thử tích hợp

Các payload đa phương thức Base64 thường khó tạo lại bằng cURL, và việc đổi model có thể âm thầm thay đổi cấu trúc phản hồi.

Apidog giúp lưu riêng các request văn bản, hình ảnh và gọi công cụ trong một collection; thêm assertion cho các trường ứng dụng thực sự dùng; và lưu API key trong biến môi trường thay vì shell history.

Khi chương trình khuyến mãi kết thúc, bạn có thể đổi ID model tại một nơi và chạy lại toàn bộ test suite với cả Flash và GLM-5.3. Điều này biến việc chuyển đổi model thành khác biệt có thể quan sát, thay vì một giả định.

FAQ

ID model chính xác là gì?

glm-5.3-flash trên API của Z.ai. Trên OpenRouter là z-ai/glm-5.3-flash.

SDK OpenAI có hoạt động mà không cần sửa đổi không?

Có, với chat completion, streaming và tool calling. Tham số không chuẩn như reasoning_effort cần extra_body trong Python SDK.

Có thể gửi bao nhiêu hình ảnh trong một request?

Có thể gửi nhiều ảnh, mỗi ảnh là một khối image_url. Giới hạn thực tế là ngân sách ngữ cảnh, không phải số lượng ảnh cố định.

Vì sao phản hồi dài và chậm?

reasoning_effort mặc định là max. Đặt low cho công việc không cần suy luận sâu.

Độ dài đầu ra tối đa là bao nhiêu?

Các nguồn chưa thống nhất: OpenRouter liệt kê 131.072 token, còn thẻ Hugging Face nêu 163.840 token. Hãy xác minh với nhà cung cấp trước khi phụ thuộc vào thế hệ rất dài.

Top comments (0)