إتقان تحميل الملفات عبر API: الدليل الشامل لـ multipart/form-data مع أمثلة عملية لـ Sora 2

يعد رفع ملفات واجهة برمجة التطبيقات (API) مطلبًا تقنيًا شائعًا يواجهه المطورون عند استدعاء واجهات برمجة تطبيقات الذكاء الاصطناعي لإنشاء الفيديو، ومعالجة الصور، وما إلى ذلك. سيتناول هذا المقال شرحًا منهجيًا لمبدأ عمل طريقة الترميز multipart/form-data، وسنأخذ واجهة برمجة تطبيقات Sora 2 (تحويل الصورة إلى فيديو) كمثال، لمساعدتك في إتقان المهارات الأساسية لرفع ملفات API.

القيمة الجوهرية: بعد قراءة هذا المقال، ستفهم تمامًا الآلية الأساسية لـ multipart/form-data، وستتعلم كيفية استخدام أمر curl -F لرفع الملفات، وستتمكن من تنفيذ ميزة رفع الصور لواجهات AI API مثل Sora 2 بشكل مستقل.

المعرفة الأساسية لرفع الملفات عبر API

قبل التعمق في الكود، نحتاج إلى فهم سبب احتياج رفع الملفات عبر API إلى طريقة ترميز خاصة.

لماذا نحتاج إلى multipart/form-data

عندما ترسل بيانات نصية عادية عبر API، يمكنك استخدام ترميز application/x-www-form-urlencoded البسيط. ومع ذلك، تواجه هذه الطريقة مشاكل خطيرة عند التعامل مع الملفات:

تعد multipart/form-data حلاً تم اقتراحه في معيار RFC 2388 عام 1998، وهو مخصص لحل مشكلة إرسال البيانات النصية والثنائية المختلطة في بروتوكول HTTP.

آلية عمل multipart/form-data

الفكرة الأساسية لـ multipart/form-data هي تقسيم جسم طلب HTTP إلى عدة "أجزاء" (parts) مستقلة، حيث يمكن لكل جزء أن يكون له نوع محتوى خاص به.

شرح مفصل لبنية البيانات

يحتوي طلب multipart/form-data النموذجي على البنية التالية:

POST /v1/videos HTTP/1.1
Host: api.apiyi.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxk

------WebKitFormBoundary7MA4YWxk
Content-Disposition: form-data; name="prompt"

She turns around and smiles
------WebKitFormBoundary7MA4YWxk
Content-Disposition: form-data; name="model"

sora-2-pro
------WebKitFormBoundary7MA4YWxk
Content-Disposition: form-data; name="input_reference"; filename="sample.jpeg"
Content-Type: image/jpeg

[بيانات صورة ثنائية]
------WebKitFormBoundary7MA4YWxk--

🎯 نقطة تقنية: يجب أن يكون الـ Boundary سلسلة نصية فريدة لا تظهر أبداً داخل محتوى البيانات في جسم الطلب. يستخدم الخادم هذا الـ boundary لتحليل وفصل كل جزء من أجزاء البيانات.

curl هي أداة سطر الأوامر الأكثر استخداماً كعميل HTTP، وتُستخدم المعلمة -F الخاصة بها خصيصاً لطلبات multipart/form-data.

الصيغة الأساسية لـ curl -F

curl -F "اسم_الحقل=القيمة" URL
curl -F "حقل_الملف=@مسار_الملف_المحلي" URL

الفرق بين curl -F والمعلمات الأخرى

يقع العديد من المطورين في حيرة من أمرهم بشأن استخدام -F و -d و -X POST:

# ❌ خطأ: يُستخدم -d لـ x-www-form-urlencoded، وهو غير مناسب لرفع الملفات
curl -X POST -d "[email protected]" https://api.example.com/upload

# ❌ خطأ: تحديد Content-Type يدوياً مع استخدام -d
curl -X POST -H "Content-Type: multipart/form-data" -d "..." https://api.example.com/upload

# ✅ صحيح: استخدام -F يضبط Content-Type و boundary بشكل صحيح وتلقائي
curl -F "[email protected]" https://api.example.com/upload

توضيح تقني: عند استخدام -F يقوم curl تلقائياً بـ:

1. ضبط طريقة الطلب (Method) لتكون POST.
2. ضبط الرأس Content-Type: multipart/form-data.
3. توليد boundary فريد.
4. تنسيق جسم الطلب (Request Body) وفقاً لمعايير RFC.

تطبيق عملي: رفع الملفات عبر Sora 2 API

Sora 2 هو نموذج توليد الفيديو الذي أطلقته OpenAI، ويدعم رفع صور مرجعية عبر API لتوليد الفيديو. هذا تطبيق نموذجي لاستخدام multipart/form-data.

معلمات Sora 2 API لتحويل الصور إلى فيديو

مقارنة بين نماذج Sora 2

مثال كامل لرفع ملف إلى Sora 2

فيما يلي مثال كامل لاستخدام curl لاستدعاء Sora 2 API لتوليد فيديو من صورة:

curl -X POST "https://api.apiyi.com/v1/videos" \
  -H "Authorization: Bearer $APIYI_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F prompt="She turns around and smiles, then slowly walks out of the frame." \
  -F model="sora-2-pro" \
  -F size="1280x720" \
  -F seconds="8" \
  -F input_reference="@sample_720p.jpeg;type=image/jpeg"

تحليل الأمر

🚀 ابدأ بسرعة: نوصي باستخدام منصة APIYI apiyi.com لاختبار Sora 2 API بسرعة. توفر هذه المنصة واجهات جاهزة للاستخدام، مما يسمح بإتمام التكامل دون الحاجة إلى إعدادات معقدة.

ملاحظات حول رفع الصور

عند استخدام Sora 2 API لرفع صور مرجعية، يرجى مراعاة ما يلي:

تنفيذ رفع البيانات بصيغة multipart/form-data باستخدام بايثون

إلى جانب curl، يشيع استخدام لغات البرمجة في التطوير العملي لرفع الملفات. إليك كيفية تنفيذ ذلك باستخدام بايثون.

مثال مبسط للغاية

import requests

# 使用 APIYI 统一接口
url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# 准备 multipart 数据
files = {
    "input_reference": ("sample.jpeg", open("sample_720p.jpeg", "rb"), "image/jpeg")
}
data = {
    "prompt": "She turns around and smiles, then slowly walks out of the frame.",
    "model": "sora-2-pro",
    "size": "1280x720",
    "seconds": "8"
}

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

import requests
import time
import os

class Sora2Client:
    """Sora 2 API 客户端 - 支持 multipart/form-data 文件上传"""

    def __init__(self, api_key: str, base_url: str = "https://api.apiyi.com/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {api_key}"}

    def create_video(
        self,
        prompt: str,
        model: str = "sora-2",
        size: str = "1280x720",
        seconds: int = 8,
        input_reference: str = None
    ) -> dict:
        """
        创建视频生成任务

        Args:
            prompt: 视频描述
            model: 模型选择 (sora-2 或 sora-2-pro)
            size: 分辨率
            seconds: 时长 (4, 8, 12)
            input_reference: 参考图片路径 (可选)

        Returns:
            任务信息字典
        """
        url = f"{self.base_url}/videos"

        data = {
            "prompt": prompt,
            "model": model,
            "size": size,
            "seconds": str(seconds)
        }

        files = None
        if input_reference and os.path.exists(input_reference):
            # 根据文件扩展名确定 MIME 类型
            ext = os.path.splitext(input_reference)[1].lower()
            mime_types = {
                ".jpg": "image/jpeg",
                ".jpeg": "image/jpeg",
                ".png": "image/png",
                ".webp": "image/webp"
            }
            mime_type = mime_types.get(ext, "application/octet-stream")

            files = {
                "input_reference": (
                    os.path.basename(input_reference),
                    open(input_reference, "rb"),
                    mime_type
                )
            }

        try:
            response = requests.post(
                url,
                headers=self.headers,
                data=data,
                files=files,
                timeout=30
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            return {"error": str(e)}
        finally:
            if files and "input_reference" in files:
                files["input_reference"][1].close()

    def get_video_status(self, video_id: str) -> dict:
        """查询视频生成状态"""
        url = f"{self.base_url}/videos/{video_id}"
        response = requests.get(url, headers=self.headers, timeout=30)
        return response.json()

    def wait_for_completion(self, video_id: str, poll_interval: int = 10) -> dict:
        """轮询等待视频生成完成"""
        while True:
            status = self.get_video_status(video_id)
            if status.get("status") in ["completed", "failed"]:
                return status
            print(f"Status: {status.get('status')}... waiting {poll_interval}s")
            time.sleep(poll_interval)


# 使用示例
if __name__ == "__main__":
    client = Sora2Client(api_key=os.getenv("APIYI_KEY"))

    # 创建图生视频任务
    result = client.create_video(
        prompt="She turns around and smiles, then slowly walks out of the frame.",
        model="sora-2-pro",
        size="1280x720",
        seconds=8,
        input_reference="sample_720p.jpeg"
    )

    if "id" in result:
        print(f"Task created: {result['id']}")
        final_result = client.wait_for_completion(result["id"])
        print(f"Video URL: {final_result.get('video_url')}")
    else:
        print(f"Error: {result}")

نصيحة: احصل على رصيد تجريبي مجاني عبر APIYI (apiyi.com) للتحقق بسرعة من ميزة تحويل الصور إلى فيديو.

معالجة multipart في مكتبة requests

النقاط الرئيسية لمعالجة multipart/form-data باستخدام مكتبة requests في بايثون:

⚠️ تنبيه: عند استخدام معاملي data و files معاً، ستقوم مكتبة requests بتعيين رأس Content-Type والفاصل (boundary) الصحيح تلقائياً، ولا داعي لضبطهما يدوياً.

حلول التنفيذ باستخدام JavaScript/Node.js

بيئة المتصفح (FormData API)

const formData = new FormData();
formData.append('prompt', 'She turns around and smiles');
formData.append('model', 'sora-2-pro');
formData.append('size', '1280x720');
formData.append('seconds', '8');
formData.append('input_reference', fileInput.files[0]);

fetch('https://api.apiyi.com/v1/videos', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
        // 注意: 不要手动设置 Content-Type
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

بيئة Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('prompt', 'She turns around and smiles');
form.append('model', 'sora-2-pro');
form.append('size', '1280x720');
form.append('seconds', '8');
form.append('input_reference', fs.createReadStream('sample_720p.jpeg'), {
    contentType: 'image/jpeg'
});

axios.post('https://api.apiyi.com/v1/videos', form, {
    headers: {
        ...form.getHeaders(),
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
.then(response => console.log(response.data));

💡 نصيحة جوهرية: عند استخدام FormData في المتصفح، لا تقم بضبط رأس Content-Type يدوياً. سيقوم المتصفح بإضافة بارامتر boundary الصحيح تلقائياً.

استكشاف أخطاء multipart/form-data وإصلاحها

الأسباب الشائعة لفشل الرفع

نصائح لتصحيح الأخطاء (Debugging)

استخدم الخيار -v في أداة curl لعرض الطلب كاملاً:

curl -v -F "[email protected]" https://api.example.com/upload

سيعرض لك هذا:

• ترويسات الطلب (بما في ذلك الـ Content-Type المولد تلقائيًا والـ boundary)
• هيكل جسم الطلب (Request body)
• استجابة الخادم

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

ملخص

يتناول هذا المقال بالتفصيل التقنية الأساسية لرفع الملفات عبر واجهة برمجة التطبيقات (API)، وهي multipart/form-data:

مراجعة لأبرز النقاط التقنية:

يُعد إتقان multipart/form-data مهارة أساسية في تطوير تطبيقات نماذج اللغة الكبيرة (AI API). وسواء كنت تعمل على توليد الفيديو باستخدام Sora 2، أو فهم الصور عبر GPT-4 Vision، أو أي واجهة برمجة تطبيقات أخرى تتطلب رفع ملفات، فإن المبادئ الأساسية تظل واحدة.

نوصي باستخدام APIYI (apiyi.com) للتحقق من ميزة رفع الملفات بسرعة، حيث يمكنك تجربة واجهة برمجة تطبيقات موحدة والحصول على دعم تقني شامل.

المؤلف: فريق APIYI | متخصصون في مشاركة تقنيات نماذج اللغة الكبيرة (AI APIs)
التواصل التقني: قم بزيارة apiyi.com للحصول على المزيد من موارد تطوير الـ APIs.

المصادر والمراجع

1. RFC 2388: معيار multipart/form-data

   • الرابط: tools.ietf.org/html/rfc2388

2. وثائق curl الرسمية: منشورات النماذج متعددة الأجزاء (Multipart Formposts)

   • الرابط: everything.curl.dev/http/post/multipart

3. وثائق MDN Web: استخدام كائنات FormData

   • الرابط: developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects

4. وثائق OpenAI Sora API: دليل توليد الفيديو (Video Generation Guide)

   • الرابط: platform.openai.com/docs/guides/video-generation