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

تمنحكم واجهة برمجة تطبيقات CloudZIR الوصول إلى نماذج Mina عبر واجهتين متوافقتين: صيغة OpenAI وصيغة Anthropic. تعمل حزم SDK والوكلاء والأدوات التي تستخدمونها اليوم مع نقاط النهاية والمعاملات الموثقة هنا: يكفي تعديل ثلاثة إعدادات، هي عنوان القاعدة (base URL) ومفتاح API واسم النموذج.

النماذج والأسعارذكاء اصطناعي واحد بثلاثة مستويات: mina-flash وmina-low وmina-full. أسعار بالدينار لكل مليون رمز. Claude Codeربط وكيل برمجي بـ CloudZIR بثلاثة متغيرات بيئة فقط. مرجع APIكل المعاملات، حقلاً حقلاً.

1. الحصول على مفتاح API#

أنشئوا مفتاحكم على plateforme.cloudzir.com (نفس حساب الدردشة ai.cloudzir.com). يبدو المفتاح هكذا :

zir_ai_exemple_0000000000000000000000000000000000000000

هذا المثال قابل للتمييز عمدًا كمثال. أي توثيق يعرض سلسلة لا يمكن تمييزها عن مفتاح حقيقي يعلّم أدوات الكشف تجاهلها؛ ويوم يتسرب مفتاح حقيقي فعلًا، لن يلاحظه أحد.

مهم

لا يُعرض المفتاح السري الكامل إلا مرة واحدة فقط، عند الإنشاء. نحتفظ فقط ببصمته: لا أحد، ولا حتى دعم CloudZIR، يمكنه إعادة إظهاره لكم. فقدتموه؟ ألغوا المفتاح وأنشئوا مفتاحًا آخر.

2. شحن رصيد حسابكم#

واجهة API مدفوعة مسبقًا: كل طلب يخصم من محفظتكم. اشحنوا بالدينار الجزائري من Top up :

تظهر وسائل الدفع المقترحة في صفحة Top up على المنصة.

بدون رصيد، ترد واجهة API بالرمز 402 insufficient_balance.

3. أول استدعاء لكم#

عنوان القاعدة (صيغة OpenAI) : https://api.cloudzir.com/v1

curl https://api.cloudzir.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY" \
  -d '{
    "model": "mina-low",
    "messages": [
      {"role": "system", "content": "Tu es un assistant utile."},
      {"role": "user", "content": "Bonjour !"}
    ]
  }'

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="zir_ai_...",
    base_url="https://api.cloudzir.com/v1",
)

response = client.chat.completions.create(
    model="mina-low",
    messages=[
        {"role": "system", "content": "Tu es un assistant utile."},
        {"role": "user", "content": "Bonjour !"},
    ],
)

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

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLOUDZIR_API_KEY,
  baseURL: "https://api.cloudzir.com/v1",
});

const response = await client.chat.completions.create({
  model: "mina-low",
  messages: [
    { role: "system", content: "Tu es un assistant utile." },
    { role: "user", content: "Bonjour !" },
  ],
});

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

الاستجابة#

{
  "id": "chatcmpl-4334a6f158894999",
  "object": "chat.completion",
  "created": 1766400000,
  "model": "mina-low",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Bonjour ! Comment puis-je vous aider ?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 12, "total_tokens": 33 }
}

4. البث المباشر (Streaming)#

أضيفوا "stream": true لتلقي الاستجابة رمزًا رمزًا (أحداث مرسلة من الخادم Server-Sent Events). التفاصيل : دليل البث المباشر.

curl https://api.cloudzir.com/v1/chat/completions \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mina-flash",
    "messages": [{"role": "user", "content": "Raconte une histoire courte."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

stream = client.chat.completions.create(
    model="mina-flash",
    messages=[{"role": "user", "content": "Raconte une histoire courte."}],
    stream=True,
    stream_options={"include_usage": True},
)

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

5. صيغة Anthropic#

نفس المفتاح يعمل على واجهة Anthropic : https://api.cloudzir.com/anthropic. اختاروا معرّف Mina مثل mina-flash أو mina-low أو mina-full. تُعيد GET /anthropic/v1/models قائمة النماذج المفعّلة لمفتاحكم.

# pip install anthropic
import anthropic

client = anthropic.Anthropic(
    api_key="zir_ai_...",
    base_url="https://api.cloudzir.com/anthropic",
)

message = client.messages.create(
    model="mina-full",
    max_tokens=1000,
    system="Tu es un assistant utile.",
    messages=[{"role": "user", "content": "Bonjour !"}],
)

print(message.content[0].text)

curl https://api.cloudzir.com/anthropic/v1/messages \
  -H "x-api-key: $CLOUDZIR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "mina-full",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "Bonjour !"}]
  }'

وبعد ذلك#

استدعاء الأدواتFunction calling لربط دوالكم الخاصة. إخراج JSONفرض JSON صالح وقابل للاستغلال. أكواد الأخطاءفهم كل كود مرجَع ومعالجته.