موارد المطورين

الملفات والرفوعات

أنشئ الملفات الدائمة وأدرج قائمة بها وحمّلها واحذفها، أو اجمع ملفاً من أجزاء الرفع المتعدد الأجزاء.

تخزّن واجهة Files API ملفات user_data وbatch وbatch_output غير قابلة للتعديل وذات نطاق على مستوى الحساب، وتُعيد معرّفات ملفات ثابتة بدلاً من عناوين URL للتخزين. استخدم معرّف الملف عندما تقبل واجهة برمجية موردًا للملف قابلاً لإعادة الاستخدام، واستخدم نقطة نهاية المحتوى عندما تحتاج تطبيقاتك إلى البايتات المخزونة عينها.

اختر تدفق رفع

استخدم POST /v1/files لإنشاء ملف من طلب multipart واحد. يمكن أن يحتوي ملف user_data المكتمل على ما يصل إلى 52,428,800 بايت.
استخدم POST /v1/files مع purpose=batch للإدخال المباشر للدُفعات بحجم يصل إلى 95,000,000 بايت.
استخدم Uploads API لإرسال الأجزاء قبل تكوين الملف النهائي. يمكن أن يحتوي كل جزء على ما يصل إلى 67,108,864 بايت؛ ويقتصر ملف user_data المكتمل على 52,428,800 بايت وملف batch المكتمل على 209,715,200 بايت. تنتهي صلاحية عملية الرفع غير المكتملة بعد ساعة واحدة.
تشترك الملفات النشطة والحجوزات الجارية في حد تخزين الحساب البالغ 5,368,709,120 بايت.

POST /api/v1/files هو تدفق تحميل مؤقت منفصل يُعيد رابطاً مؤقتاً. يواصل SDK files.create وCLI runapi files create استخدام هذا التدفق. استخدم files.createFile أو files.create_file، أو CLI runapi files create-file، عندما تحتاج إلى كائن File دائم.

مصادقة طلب

تستخدم الملفات والرفوعات مفتاح API قياسياً لـ RunAPI. أرسله كرمز Bearer:

SHELL

export RUNAPI_API_KEY="runapi_..."

كل ملف File وعملية Upload وجزء Part وطلب محتوى مرتبط بالحساب الذي تمت مصادقته. يُعيد معرّف يملكه حساب آخر الخطأ 404 دون الكشف عما إذا كان المورد موجوداً أصلاً.

إنشاء ملف باستخدام عميل متوافق

وجّه عميلاً متوافقاً مع OpenAI إلى عنوان URL الأساسي /v1 الخاص بـ RunAPI. لا تتطلب الطلبات أي حقول خاصة بـ RunAPI:

PYTHON

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RUNAPI_API_KEY"],
    base_url="https://runapi.ai/v1",
)

with open("knowledge.pdf", "rb") as source:
    file = client.files.create(file=source, purpose="user_data")

metadata = client.files.retrieve(file.id)
client.files.content(file.id).write_to_file("knowledge-copy.pdf")
client.files.delete(file.id)

لا يحتوي الملف المُعاد أبدًا على معرّف تخزين أو واجهة خلفية أو عنوان URL حامل.

مرجع API

يغطي Persistent Files API كائن File وعمليات الإنشاء والإدراج والاسترداد والمحتوى والحذف.
يغطي Uploads API كائن Upload وعمليات الإنشاء وإضافة الأجزاء والإكمال والإلغاء.
يغطي Batches API إنشاء دُفعات الإشراف وحالتها وإدراجها وإلغاءها.

تشغيل الإشراف في دُفعة

أنشئ ملف إدخال JSONL بطلب اعتدال واحد في كل سطر. يستخدم كل سطر شكل الدُّفعة المتوافق: custom_id وmethod وurl مضبوطة على /v1/moderations، وbody يحتوي على نموذج الاعتدال والمدخل. يمكن أن يحتوي ملف purpose=batch على ما يصل إلى 50,000 طلب. تقبل إمكانية الدُّفعة حالياً نقطة النهاية /v1/moderations بنافذة إكمال 24h.

SHELL

INPUT_FILE_ID=$(curl -sS https://runapi.ai/v1/files \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -F purpose=batch \
  -F [email protected] | jq -r .id)

BATCH_ID=$(curl -sS https://runapi.ai/v1/batches \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg file "$INPUT_FILE_ID" '{input_file_id:$file,endpoint:"/v1/moderations",completion_window:"24h"}')" \
  | jq -r .id)

curl -sS "https://runapi.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $RUNAPI_API_KEY"

استخدم GET /v1/batches لعرض قائمة الأعمال، وكرر GET /v1/batches/{batch_id} حتى تصبح الحالة نهائية، أو استدعِ POST /v1/batches/{batch_id}/cancel طالما لا يزال قيد التشغيل. يتم كشف مخرجات الأخطاء وملفات JSONL المكتملة على هيئة ملفات batch_output Files؛ استرجع بياناتها الوصفية عبر GET /v1/files/{file_id} والبايتات الفعلية عبر GET /v1/files/{file_id}/content.

دورة حياة الرفع متعدد الأجزاء

أنشئ رفعاً بعدد البايتات النهائي واسم الملف ونوع MIME وpurpose=user_data. أضف جزءاً واحداً أو أكثر، ثم مرّر معرّفاتها إلى complete بترتيب التركيب. يُعيد الإكمال الرفعَ مع ملفه المكتمل.

SHELL

UPLOAD_ID=$(curl -sS https://runapi.ai/v1/uploads \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bytes":1048576,"filename":"archive.bin","mime_type":"application/octet-stream","purpose":"user_data"}' \
  | jq -r .id)

PART_ID=$(curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -F [email protected] | jq -r .id)

curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"part_ids\":[\"$PART_ID\"]}"

ألغِ رفعاً غير مكتمل باستخدام POST /v1/uploads/{upload_id}/cancel. تكرار نفس نية الإكمال أو الإلغاء آمن؛ أما الإكمال المتنافس أو الإلغاء أو انتهاء الصلاحية فيُعيد 409 upload_state_conflict عندما تسبق نتيجة نهائية أخرى.

موارد CLI وSDK

تعرض واجهة سطر الأوامر دورة الحياة الكاملة:

SHELL

runapi files create-file knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output knowledge-copy.pdf
runapi files delete file_123

runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123

يكشف كل Provider Client عن files وuploads. تستخدم JavaScript وPHP الدوال createFile / deleteFile / addPart؛ وتستخدم Python وRuby create_file / delete_file / add_part؛ ويستخدم Go الدوال CreateFile / DeleteFile / AddPart؛ ويستخدم Java الدوال createFile / deleteFile / addPart. تتبع عمليات List وretrieve وcontent وcreate وcomplete وcancel اصطلاح التسمية المعتاد لكل لغة. راجع SDKs لتعليمات تثبيت الحزم.

سلوك دورة الحياة

محتوى الملف غير قابل للتغيير. يؤدي حذف ملف إلى إزالته من قوائم الإدراج النشطة فوراً وجدولة تنظيف التخزين. يُرتّب إكمال الرفع الأجزاءَ بالترتيب المُقدَّم فقط، ويُنشئ الإكمال الناجح ملفاً واحداً. احتفظ بترتيب معرّفات الأجزاء الأصلي عند إعادة محاولة استجابة إكمال غير مؤكدة.