API الملفات

ارفعوا مستندًا مرة واحدة، وأعيدوا استخدامه بقدر ما تشاؤون. تستخرج CloudZIR النص منه عند التسجيل : تسترجعون هذا النص وتُدرجونه في إدخالاتكم، دون إعادة إرسال الملف في كل طلب.

الرفع#

POST https://api.cloudzir.com/v1/files؛ multipart، بحقلَي file وpurpose.

from openai import OpenAI

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

with open("facture.txt", "rb") as fichier:
    envoi = client.files.create(file=fichier, purpose="assistants")

print(envoi.id, envoi.status)     # 9f2c1a7b-… processed

import fs from "node:fs";

const envoi = await client.files.create({
  file: fs.createReadStream("facture.txt"),
  purpose: "assistants",
});

console.log(envoi.id, envoi.status);

curl https://api.cloudzir.com/v1/files \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY" \
  -F purpose=assistants \
  -F file=@facture.txt

الاستجابة#

{
  "id": "9f2c1a7b-…",
  "object": "file",
  "bytes": 4821,
  "created_at": 1766400000,
  "filename": "facture.txt",
  "purpose": "assistants",
  "status": "processed",
  "status_details": null,
  "tokens": 1204
}

tokens هو تقدير ما سيكلفه المستند من رموز إدخال عند إدراجه؛ ما يتيح توقع الفاتورة حتى قبل استدعاء أي نموذج.

استخدام المستند#

استرجعوا النص المُستخرَج، ثم ضعوه في إدخالكم :

import httpx

texte = httpx.get(
    f"https://api.cloudzir.com/v1/files/{envoi.id}/content",
    headers={"Authorization": f"Bearer {cle}"},
).text

reponse = client.chat.completions.create(
    model="mina-low",
    messages=[
        {"role": "system", "content":
         "Réponds UNIQUEMENT à partir du document. Si l'information n'y est pas, dis-le."},
        {"role": "user", "content": f"DOCUMENT :\n{texte}\n\nQUESTION : quel est le total ?"},
    ],
)

إدارة ملفاتكم#

ملفاتكم مرئية فقط لحسابكم : معرّف ملف لعميل آخر يُعيد 404، أبدًا محتواه.

الصيغ والقيود#

حين لا يكون الملف قابلًا للقراءة#

ينجح الرفع رغم ذلك، لكن الملف يحمل status: "error" و status_details يقول بدقة لماذا :

{
  "id": "…", "status": "error",
  "status_details": "Type de fichier non supporté (application/octet-stream). Formats acceptés : texte, code, csv, json, markdown, pdf."
}

طلب محتوى ملف كهذا يُعيد 400 بنفس الرسالة؛ أبدًا مستندًا فارغًا قد يعطي إجابات مُختلَقة.

تقطيع المستندات الكبيرة#

يجب تقطيع مستند أطول من نافذة النموذج. انظروا الرمز واستخدامه للنوافذ المتاحة، وضعوا في الحسبان التخزين المؤقت : بإبقاء المستند في بداية طلباتكم، قد يُفوتَر بسعر مخفّض بدءًا من السؤال الثاني المطروح عليه، حين يتعرّف التخزين المؤقت عليه (تُبيّن الاستجابة ذلك في usage).

الحذف#

لحذف ملف صراحةً، استخدموا DELETE /v1/files/{file_id}. يحذف هذا الطلب المحتوى وكائن التخزين؛ ويبقى أثر تقني للحذف. لا تُطبّق مدة انتهاء تلقائية لهذه الملفات. تُحتسَب ضمن حصة تخزينكم، لكن التخزين نفسه غير مُفوتَر : الرموز المستهلكة في استدعاءاتكم وحدها تُفوتَر.