تخطَّ إلى المحتوى
مرجع API
مرجع API

إنشاء رفع ملف

رفع ملف محلي واحد أو عنوان HTTPS بعيد أو مصدر base64 واستلام عنوان URL مؤقت.

عرض Markdown

رفع ملف محلي واحد أو عنوان HTTPS بعيد أو مصدر base64 واستلام عنوان URL مؤقت.

نقطة النهاية

POST /api/v1/files
عنوان URL الأساسي
https://runapi.ai
إصدار API
v1
المصادقة
Authorization: Bearer YOUR_API_KEY
02

الطلب

نص JSON

أرسل القيم فقط في موقع الطلب المُدرج.

application/json - Base64 source4 حقل
file_namestring
اختياري

اسم ملف اختياري لرفع الملف المُنشأ.

sourceobject
مطلوب

بايتات المصدر مُرمَّزة بـ Base64.

source.datastring
مطلوب

بيانات Base64

source.typestring
مطلوب

يحدد تمثيل المصدر بترميز base64.

application/json - URL source4 حقل
file_namestring
اختياري

اسم ملف اختياري لرفع الملف المُنشأ.

sourceobject
مطلوب

المصدر البعيد عبر HTTPS للتنزيل.

source.typestring
مطلوب

يحدد تمثيل مصدر URL.

source.urlstring
مطلوب

عنوان URL عام عبر HTTPS للتنزيل.

multipart/form-data2 حقل
filestring
مطلوب

بايتات الملف المحلي للرفع.

file_namestring
اختياري

اسم ملف اختياري لرفع الملف المُنشأ.

03

استجابة النجاح

HTTP 201

POST /api/v1/files

JSON 
{
  "created_at": "2026-07-27T10:00:00.000Z",
  "expires_at": "2026-07-27T11:00:00.000Z",
  "file_name": "mask.png",
  "mime_type": "image/png",
  "size_bytes": 204800,
  "url": "https://file.runapi.ai/temp/user-uploads/mask.png"
}
04

استجابة الخطأ (401)

HTTP 401
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Authentication required"
}
05

استجابة الخطأ (403)

HTTP 403
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Standard API key required"
}
06

استجابة الخطأ (400)

HTTP 400
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Only HTTPS URLs are allowed"
}
07

استجابة الخطأ (408)

HTTP 408
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Download timeout"
}
08

استجابة الخطأ (413)

HTTP 413
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "File size exceeds the maximum allowed size"
}
09

استجابة الخطأ (415)

HTTP 415
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "This content type is not supported"
}
10

استجابة الخطأ (422)

HTTP 422
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "File upload failed. Please try again."
}
11

استجابة الخطأ (429)

HTTP 429
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Too many file uploads for this account. Please retry later."
}
12

مثال cURL

CURL 
curl -X POST https://runapi.ai/api/v1/files \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"source":{"type":"url","url":"https://cdn.runapi.ai/public/samples/mask.png"},"file_name":"mask.png"}'