واجهة Claude Files API: ارفع مرة واحدة واستخدمها في كل مكان (دليل الإتاحة العامة)

تتيح لك واجهة برمجة تطبيقات الملفات من Claude تحميل ملف مرة واحدة إلى https://api.anthropic.com/v1/files، والحصول على file_id، والإشارة إلى ذلك المعرّف في أي طلب Messages بدلاً من إعادة إرسال المحتوى في كل مرة. اعتبارًا من 20 أغسطس 2026، أصبحت متاحة بشكل عام على منصة Claude: بدون ترويسة بيتا، و1 تيرابايت من التخزين لكل مؤسسة، وحدود معدل أعلى بخمس مرات من بيتا. أعلنت Anthropic عن التغيير في منشور وكلاء الإنتاج، إلى جانب الإتاحة العامة لاستخدام الحاسوب، وأداة المتصفح، وواجهة برمجة تطبيقات المهارات.

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

ما الذي تفعله واجهة برمجة تطبيقات الملفات

واجهة برمجة تطبيقات الملفات هي طبقة تخزين تُنشئ مرة واحدة وتُستخدم مرات عديدة لواجهة برمجة تطبيقات Claude. إنها تحل تكلفة محددة: إذا كان تطبيقك يطرح أسئلة حول نفس ملف PDF المكون من 40 صفحة عبر مئات الطلبات، فإن إعادة تحميل ذلك PDF في كل طلب يهدر النطاق الترددي ويعقّد كود العميل الخاص بك. باستخدام واجهة برمجة تطبيقات الملفات، يمكنك:

Claude Files API lifecycle: upload, reference by file_id, download, delete

تحميل ملف إلى تخزين Anthropic والحصول على file_id فريد
الإشارة إلى ذلك المعرّف في طلبات Messages عبر كتلة محتوى
تنزيل الملفات التي تُنشئها المهارات أو أداة تنفيذ الكود (مخططات، جداول بيانات، عروض تقديمية)
إدارة كل شيء بعمليات السرد، واسترداد البيانات الوصفية، والحذف

سطح نقطة النهاية صغير:

العملية	نقطة النهاية
تحميل ملف	`POST /v1/files`
سرد الملفات	`GET /v1/files`
الحصول على بيانات وصفية للملف	`GET /v1/files/{file_id}`
تنزيل محتوى الملف	`GET /v1/files/{file_id}/content`
حذف ملف	`DELETE /v1/files/{file_id}`

كل ذلك يعمل مع الترويسات القياسية x-api-key و anthropic-version: 2023-06-01. إذا كنت جديدًا على واجهة برمجة تطبيقات Messages نفسها، فإن دليل Claude Opus 5 API الخاص بنا يغطي أساسيات المصادقة وشكل الطلب.

ما الذي تغير عند الإتاحة العامة

أمضت واجهة برمجة تطبيقات الملفات أشهرًا في مرحلة بيتا خلف ترويسة. غيّر إصدار الإتاحة العامة في 20 أغسطس 2026 أربعة أشياء تهم تخطيط الإنتاج:

What changed when the Claude Files API went GA

لا ترويسة بيتا. تعمل الطلبات مع الترويسات القياسية على واجهة برمجة تطبيقات Claude.
حدود معدل أعلى 5 مرات. تسمح عمليات الملفات الآن بحوالي 500 طلب في الدقيقة، مع حدود أعلى متاحة من خلال المبيعات.
1 تيرابايت من التخزين لكل مؤسسة، بحد أقصى 500 ميغابايت لكل ملف.
تغطية منصة أوسع. تعمل واجهة برمجة تطبيقات الملفات على واجهة برمجة تطبيقات Claude مباشرة، وعلى Claude Platform على AWS في مرحلة بيتا، وعلى Microsoft Foundry عند استخدام نشر Hosted on Anthropic. وهي غير متاحة على Amazon Bedrock أو Google Cloud Vertex AI، وغير مؤهلة لاتفاقيات الاحتفاظ الصفري بالبيانات. خطط وفقًا لذلك إذا كنت تتبع سياسة احتفاظ صارمة.

تحميل ملف

عمليات التحميل هي طلبات نموذج متعددة الأجزاء، وليست JSON:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/report.pdf"

تقدم لك الاستجابة كل ما تحتاجه للإشارة إلى الملف لاحقًا:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

هناك حقلان يستحقان الانتباه. downloadable يكون false لأي شيء تقوم بتحميله؛ فقط الملفات التي ينشئها Claude من خلال المهارات أو تنفيذ الكود يمكن تنزيلها مرة أخرى. و expires_at يكون null ما لم تحدد تاريخ انتهاء صلاحية عند التحميل (المزيد عن ذلك أدناه).

في اختبار Apidog CLI أدناه، تحفظ خطوة التحميل id كمتغير، لذا تشير كل طلب لاحق إلى {{claude_file_id}} بدلاً من سلسلة مضمّنة.

الإشارة إلى الملفات في الرسائل

بمجرد التحميل، يتم إدراج الملف في طلب Messages من خلال أحد أنواع كتل المحتوى الثلاثة، اعتمادًا على الملف:

نوع الملف	نوع MIME	كتلة المحتوى
PDF، نص عادي	`application/pdf`, `text/plain`	`document`
صور	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`
مجموعات البيانات وكل شيء آخر	متنوع	`container_upload` (أداة تنفيذ الكود)

يبدو طلب تلخيص PDF كما يلي:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

تقبل كتلة document أيضًا حقولًا اختيارية هي title و context و citations، لذا يمكنك تمكين إخراج الاستشهادات مقابل الملف المحمّل. بالنسبة للصور، بدّل نوع الكتلة إلى image بنفس شكل source. بالنسبة لجداول البيانات، أو ملفات CSV التي تريد تحليلها بدلاً من قراءتها، أو أي تنسيق لا تقبله كتلة document، استخدم container_upload لتسليم الملف إلى أداة تنفيذ الكود.

ملاحظة حول التنسيق: لا تدعم كتلة document ملفات .docx و .xlsx مباشرة. حوّل ملفات Word إلى PDF للحفاظ على تحليل الصور والاستشهادات، أو استخرج النص العادي وأرسله ضمنيًا.

تنزيل الملفات المُنشأة

توجد نقطة نهاية التنزيل للمخرجات، وليس للمدخلات. عندما ينشئ Claude مخططًا باستخدام تنفيذ الكود أو ينتج جدول بيانات من خلال مهارة، تتضمن الاستجابة file_id داخل كتلة bash_code_execution_tool_result. هذا المعرّف قابل للتنزيل:

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

محاولة تنزيل ملف قمت بتحميله تُرجع خطأ 400. تحقق من علامة downloadable في البيانات الوصفية قبل ربط منطق إعادة المحاولة حول هذا؛ فهذا يوفر تذكرة دعم. حلقة التحميل-إلى-الداخل، والتوليد-إلى-الخارج هي العمود الفقري لسير عمل Skills API المتاح عامًا حديثًا، حيث تنتج المهارات مستندات Office التي تنزّلها عبر نفس نقطة النهاية هذه. يغطي دليلنا إلى Claude Skills ماهية المهارات وكيفية تنفيذها.

انتهاء الصلاحية ودورة حياة الملف

تظل الملفات موجودة حتى تحذفها أو حتى ينتهي تاريخ انتهاء الصلاحية الذي حددته عند التحميل:

مرر expires_in_seconds كحقل نموذج عند التحميل. النطاق الصالح: 3,600 (ساعة واحدة) إلى 7,776,000 (90 يومًا). يتم تعيينه مرة واحدة ولا يمكن تغييره لاحقًا.
بعد مرور expires_at، تُرجع عمليات تنزيل المحتوى خطأ 404 وأي طلب Messages يشير إلى الملف يفشل قبل الاستدلال.
تظل البيانات الوصفية قابلة للقراءة لمدة تصل إلى 30 يومًا بعد انتهاء الصلاحية، وتظهر الملفات منتهية الصلاحية في استجابات السرد خلال تلك الفترة. قارن expires_at بالوقت الحالي عند التصفية.
حذف ملف يزيله فورًا ولا يمكن التراجع عنه. يتم تحرير المحتوى منتهي الصلاحية من حصة التخزين الخاصة بك ولكن قد يتم الاحتفاظ به لفترة وجيزة لمراجعة السلامة، لذا فإن انتهاء الصلاحية هو أداة دورة حياة وليس ضمانًا للتحكم في الحذف.

نموذج الأمان: الملفات محددة النطاق بمساحة العمل

هذه هي الحافة الأكثر حدة في الواجهة بأكملها. الملفات المحمّلة يمكن الوصول إليها من مساحة العمل بأكملها، وليس مقتصرة على مستخدم نهائي أو محادثة أو جلسة. أي مفتاح API في نفس مساحة العمل يمكنه قراءة أي ملف تم تحميله هناك، وتشارك جميع المفاتيح مساحة العمل الافتراضية لمؤسستك ما لم تقم بتعيينها في مكان آخر.

القواعد العملية:

لا تقبل أبدًا قيم file_id من المستخدمين النهائيين. فمعرّف يقدمه المستخدم سيسمح لمستخدم واحد من تطبيقك بقراءة تحميلات مستخدم آخر. تعامل مع معرّفات الملفات كمراجع من جانب الخادم واحتفظ بتعيين المستخدم إلى الملف في قاعدة البيانات الخاصة بك.
هل تبني نظامًا متعدد المستأجرين؟ مساحة عمل واحدة لكل مستأجر. مساحة العمل هي حدود العزل. تحصل كل مؤسسة على ما يصل إلى 100 مساحة عمل، ويمكن لفرق حسابات Anthropic رفع ذلك.

إذا كنت تتبع بالفعل مفاتيح API لكل مستأجر لتوزيع التكلفة (وهو موضوع نتعمق فيه في كيفية تقليل فاتورة Claude API)، فإن نفس تخطيط مساحة العمل يمنحك عزل الملفات مجانًا.

الحدود والفوترة

الأرقام التي يجب البناء عليها:

الحد	القيمة
الحجم الأقصى للملف	500 ميغابايت
تخزين المؤسسة	1 تيرابايت
حد معدل واجهة برمجة تطبيقات الملفات	~500 طلب/دقيقة
طول اسم الملف	من 1 إلى 255 حرفًا
نطاق انتهاء الصلاحية	من ساعة واحدة إلى 90 يومًا

الفوترة ودية: تحميل الملفات وتنزيلها وسردها وحذفها كلها مجانية. أنت تدفع فقط عندما يدخل محتوى الملف في طلب Messages، حيث يتم تسعيره كرموز إدخال عادية. ملف PDF من 100 صفحة يُشار إليه في عشرة طلبات يكلف نفس رموز الإدخال عشر مرات؛ توفر لك واجهة برمجة تطبيقات الملفات النطاق الترددي وتعقيد العميل، وليس إنفاق الرموز. لتوفير الجانب المتعلق بالرموز، اقرن مراجع الملفات بالتخزين المؤقت للمطالبات.

احترس من هذه الأخطاء: 413 عندما يتجاوز ملف 500 ميغابايت، و400 عندما تصل مؤسستك إلى سقف 1 تيرابايت، و400 عندما لا يتطابق نوع الملف مع كتلة المحتوى الخاصة به (صورة في كتلة document، على سبيل المثال)، و404 للمعرّفات خارج مساحة العمل الخاصة بك.

دع Claude Code يختبر واجهة برمجة تطبيقات الملفات باستخدام Apidog CLI

واجهة برمجة تطبيقات الملفات هي تدفق متعدد الخطوات وذو حالة، لذا فهي تستحق اختبار انحدار، وليس سجل أوامر shell. يمكن لـ Claude Code، أو أي وكيل برمجة، إنشاء وتشغيل ذلك الاختبار من خلال Apidog CLI. قم بإعداده مرة واحدة:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

يأتي الرمز المميز من Apidog ضمن إعدادات الحساب، رمز الوصول إلى API. ثم أعط الوكيل مطالبة واحدة:

Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

الأوامر التي يشغلها، تم التحقق منها مقابل Apidog CLI 2.2.7:

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

يكرر الوكيل endpoint create لكل نقطة نهاية، ثم يكتب استخراج المتغيرات والتأكيدات في السيناريو قبل تشغيله. تغيير ملفات الاختبار لاحقًا يعني تغيير خطوة تحميل واحدة، وليس كل طلب. اطلب أيضًا محاكاة لاستجابة التحميل (apidog mock create)، وسيحصل فريق الواجهة الأمامية على شكل JSON قبل وجود وكيل الواجهة الخلفية الخاص بك. نفس سطر apidog run مع -r junit ينزل إلى CI؛ يغطي دليلنا Apidog CLI في Claude Code إعداد الوكيل من البداية إلى النهاية.

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

هل ما زلت بحاجة إلى ترويسة بيتا؟ لا. منذ الإتاحة العامة في 20 أغسطس 2026، تعمل واجهة برمجة تطبيقات الملفات على واجهة برمجة تطبيقات Claude مع الترويسات القياسية x-api-key و anthropic-version. إذا كان SDK أو الوكيل الخاص بك لا يزال يثبّت ترويسة بيتا القديمة للملفات، فأزلها عند الترقية.

هل يمكنني تحديث محتوى ملف؟ لا. الملفات غير قابلة للتغيير بعد التحميل. حمّل ملفًا جديدًا، ووجّه مراجعك إلى المعرّف الجديد، واحذف القديم.

هل تعمل واجهة برمجة تطبيقات الملفات على Bedrock أو Vertex AI؟ لا. إنها على واجهة برمجة تطبيقات Claude، وClaude Platform على AWS (بيتا)، وMicrosoft Foundry مع نشر Hosted on Anthropic. على Bedrock وVertex، ما زلت بحاجة إلى محتوى base64 مضمّن.

هل واجهة برمجة تطبيقات الملفات هي نفس الشيء الذي تستخدمه Skills API للمخرجات؟ نعم. تكتب المهارات وأداة تنفيذ الكود مستنداتها المُنشأة في نفس مخزن الملفات، وتنزّلها عبر GET /v1/files/{file_id}/content. يتناسب جانب Skills API من سير العمل هذا جيدًا مع الاختبار الآلي.

خاتمة

إتاحة واجهة برمجة تطبيقات الملفات بشكل عام تزيل العذر الأخير لحشو نفس المستند بصيغة base64 في كل طلب. حمّل مرة واحدة، وأشر بالمعرّف، وحدد تاريخ انتهاء الصلاحية، واحتفظ بملفات المستأجرين في مساحات عمل منفصلة. سطح API هو خمس نقاط نهاية، وكل واحدة منها قابلة للاختبار في دقائق: اجعل وكيل البرمجة الخاص بك يكتب التدفق باستخدام Apidog CLI، وربط file_id عبر متغير، وتحقق من دورة الحياة بأكملها في CI قبل أن يجد مستخدموك الحالات الحدية نيابة عنك.