طريقة استخدام GLM-5.3-Flash API مع مدخلات الصور

دليل عملي لاستخدام GLM-5.3-Flash API

GLM-5.3-Flash متوافق مع OpenAI، لذا يمكنك البدء بتغيير عنوان URL الأساسي ومعرّف النموذج فقط. وهو أول نموذج GLM-5 يدعم إرسال الصور مع النص في الطلب نفسه.

جرّب Apidog اليوم

يغطي هذا الدليل المفتاح، والمكالمات النصية، والصور، وجهد التفكير، والتدفق، والأدوات. تستخدم الأمثلة معرّف النموذج glm-5.3-flash.

للمزيد، اقرأ شرح GLM-5.3-Flash ودليل API لـ GLM-5.3.

احصل على مفتاح API

أنشئ حسابًا على z.ai، وأنشئ مفتاح API من لوحة التحكم، ثم خزّنه في متغير بيئة:

export ZAI_API_KEY="your-key-here"

عنوان URL الأساسي:

https://api.z.ai/api/paas/v4/

تستخدم نقاط نهاية خطة الترميز عنوانًا أساسيًا مختلفًا عند ربط Claude Code أو Cline. راجع دليل Claude Code وCline.

أول مكالمة نصية

تعمل حزمة OpenAI SDK مباشرة:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZAI_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ],
)

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

باستخدام 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": "Explain what a KV cache is in two sentences."}
    ]
  }'

وباستخدام 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: "Explain what a KV cache is in two sentences." },
  ],
});

console.log(response.choices[0].message.content);

التغييران الوحيدان هما base_url وmodel.

إرسال الصور

إدخال الصور يستخدم كتل محتوى؛ يصبح content مصفوفة بدلًا من سلسلة نصية:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This screenshot shows a rendering bug. What is wrong with the layout?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshots/broken-layout.png"
                    },
                },
            ],
        }
    ],
)

اتبع هذه القواعد:

• يقبل url رابطًا عامًا أو رابط بيانات Base64.
• أرسل كل صورة في كتلة image_url مستقلة.
• ضع تعليمات المهمة قبل الصور، لأن ترتيب الكتل مهم.

لترميز صورة محلية:

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}"},
}

لمقارنة صورتين:

content = [
    {"type": "text", "text": "Does the second image match the design in the first?"},
    {"type": "image_url", "image_url": {"url": design_data_url}},
    {"type": "image_url", "image_url": {"url": built_data_url}},
]

تذكر توثيقات Z.ai الفيديو والملفات عبر الآلية نفسها. اختبر الفيديو على وسائطك الفعلية قبل الاعتماد عليه. لمزيد من تطبيقات الرؤية، راجع دليل الرؤية لـ GLM-5.3-Flash.

التحكم في جهد التفكير

استخدم reasoning_effort بقيم low أو high أو max:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Refactor this function for clarity."}],
    extra_body={"reasoning_effort": "low"},
)

القيمة الافتراضية هي max، وهي الأكثر تكلفة. اختر low للتصنيف أو الاستخراج الدفعي عندما لا تحتاج إلى استدلال عميق.

في Python SDK، ضع هذا الحقل داخل extra_body لأنه ليس جزءًا من مخطط OpenAI القياسي. أما في طلبات curl الخام فهو حقل على المستوى الأعلى.

معلمات أخذ العينات

تنشر Z.ai الإعدادات التالية:

حالة الاستخدام	temperature	top_p
عام	1.0	0.95
البرمجة	0.95	1.0

إذا كان ناتج الكود غير متسق، ابدأ بملف تعريف البرمجة.

التدفق

استخدم دلالات تدفق OpenAI المعتادة:

stream = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Write a bash script that rotates logs."}],
    stream=True,
)

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

ينتج GLM-5.3-Flash نحو 49 رمزًا في الثانية وفقًا لتحليل الذكاء الاصطناعي، مقابل نحو 86 رمزًا لـ GLM-5.3. يبلغ وقت الوصول إلى أول رمز نحو 1.52 ثانية؛ وهو مناسب لواجهات المستخدم المتدفقة، لكن خصص ميزانية زمنية للمهام الدفعيّة الطويلة.

استدعاء الأدوات

استخدم مخطط أدوات OpenAI القياسي:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_deployment_status",
            "description": "Returns the current status of a named deployment.",
            "parameters": {
                "type": "object",
                "properties": {
                    "service": {
                        "type": "string",
                        "description": "The service name, for example 'checkout-api'.",
                    }
                },
                "required": ["service"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Is checkout-api healthy?"}],
    tools=tools,
)

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

وفقًا لمعايير Z.ai عند الإطلاق، حقق النموذج 48.8 في AutomationBench مقابل 26.2 لـ GLM-5.2. هذه أرقام المورد، لكنها تتوافق مع تركيز النموذج على حلقات استدعاء الأدوات.

إذا كنت تولّد تعريفات الأدوات من API موجودة، راجع تحويل مواصفات OpenAPI إلى أدوات وكيل.

معالجة الأخطاء

حدود المعدل

استخدم التراجع الأسي مع التذبذب:

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())

تجاوز السياق

نافذة المليون رمز كبيرة، لكن المستندات الطويلة والصور عالية الدقة تستهلك السياق. تتبع ميزانية رموز الإدخال قبل الطلب.

الإخراج المقتطع

إذا انتهت الاستجابة في منتصف الجملة، افحص finish_reason. تعني length أنك وصلت إلى حد الإخراج، لا أن النموذج توقف عن المحاولة.

قراءة استخدام الرموز

استخدم كائن usage لتتبع التكلفة الفعلية:

print(response.usage.prompt_tokens, response.usage.completion_tokens)

راقب completion_tokens خصوصًا: عند استخدام reasoning_effort="max"، تُحتسب رموز التفكير ضمن الإخراج. قارن استخدام الرموز عبر مستويات الجهد على مطالباتك الفعلية.

التسعير

سعر القائمة هو:

• 0.15 دولار لكل مليون رمز إدخال.
• 0.50 دولار لكل مليون رمز إخراج.
• 0.03 دولار لكل مليون رمز إدخال مخزن مؤقتًا.

يسري خصم إطلاق بنسبة 50% حتى 9 سبتمبر 2026، لتصبح الأسعار 0.075 دولار و0.25 دولار و0.015 دولار على الترتيب.

قد تختلف الأسعار بين OpenRouter وCloudflare Workers AI وVercel AI Gateway وDeepInfra وغيرهم. راجع تحليل الأسعار، وتحقق دائمًا من سعر المزود الذي تستخدمه قبل وضع الميزانية.

اختبار التكامل

اختبر طلبات النص والصور والأدوات كمجموعة واحدة، وأضف تأكيدات للحقول التي يعتمد عليها تطبيقك. خزّن مفتاح API في متغير بيئة، ثم بدّل معرّف النموذج وأعد تشغيل المجموعة عند المقارنة بين Flash وGLM-5.3.

يسهّل Apidog حفظ هذه الطلبات، وإعادة تشغيلها، والتحقق من اختلافات الاستجابة بدل الاعتماد على اختبار يدوي.

الأسئلة الشائعة

ما معرّف النموذج؟ استخدم glm-5.3-flash على API الخاص بـ Z.ai، أو z-ai/glm-5.3-flash على OpenRouter.

هل تعمل OpenAI SDK بلا تغييرات؟ نعم، لإكمال الدردشة والتدفق واستدعاء الأدوات. ضع المعلمات غير القياسية مثل reasoning_effort في extra_body عند استخدام Python SDK.

كم صورة يمكن إرسالها في طلب واحد؟ يمكنك إرسال صور متعددة، كل واحدة في كتلة image_url مستقلة. الحد العملي تحدده ميزانية السياق.

لماذا الاستجابات مطولة أو بطيئة؟ القيمة الافتراضية لـ reasoning_effort هي max. استخدم low عندما لا تحتاج إلى تفكير عميق.

ما الحد الأقصى لطول الإخراج؟ تختلف المصادر: يسرد OpenRouter 131,072 رمزًا، بينما تشير بطاقة Hugging Face إلى 163,840. تحقق من مزودك قبل الاعتماد على عمليات توليد طويلة جدًا.