Mastering API File Upload: A Complete Guide to multipart/form-data and Sora 2 Practical Examples

API file upload is a common technical requirement developers face when calling AI interfaces for video generation, image processing, and more. In this post, we'll dive into how the multipart/form-data encoding works. We'll use the Sora 2 image-to-video API as a practical example to help you master the core skills of API file uploading.

Core Value: By the end of this article, you'll fully understand the underlying mechanics of multipart/form-data, learn how to use the curl -F command for uploads, and be able to independently implement image upload features for AI APIs like Sora 2.

Essentials of API File Uploading

Before jumping into the code, we need to understand why API file uploads require a special encoding method.

Why use multipart/form-data?

When you send standard text data via an API, you can use simple application/x-www-form-urlencoded encoding. However, this approach runs into serious issues when handling files:

Proposed in 1998 under the RFC 2388 standard, multipart/form-data was specifically designed to solve the problem of sending mixed text and binary data over HTTP.

How multipart/form-data works

The core idea of multipart/form-data is to split a single HTTP request body into multiple independent "parts," where each part can have its own content type.

Data Structure Breakdown

A typical multipart/form-data request looks like this:

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

[Binary Image Data]
------WebKitFormBoundary7MA4YWxk--

🎯 Pro Tip: The boundary must be a unique string that won't appear within the actual content of the request body. The server uses this boundary to parse and isolate each data part.

Deep Dive into curl -F: A Practical Guide to API File Uploads

curl is pretty much the go-to command-line tool for HTTP requests, and its -F flag is specifically designed for handling multipart/form-data.

The Basics of curl -F

curl -F "field_name=value" URL
curl -F "file_field=@/absolute/path/to/local_file" URL

curl -F vs. Other Parameters

It's easy to get -F, -d, and -X POST mixed up, but they serve different purposes:

# ❌ INCORRECT: -d is for x-www-form-urlencoded, not ideal for file uploads
curl -X POST -d "[email protected]" https://api.example.com/upload

# ❌ INCORRECT: Manually setting Content-Type while using -d
curl -X POST -H "Content-Type: multipart/form-data" -d "..." https://api.example.com/upload

# ✅ CORRECT: Use -F to let curl handle Content-Type and boundaries automatically
curl -F "file=@/absolute/path/to/image.jpg" https://api.example.com/upload

How it works under the hood: When you use -F, curl automatically:

1. Sets the request method to POST.
2. Sets Content-Type: multipart/form-data.
3. Generates a unique boundary string.
4. Formats the request body according to RFC standards.

Sora 2 API: Real-World File Upload Practice

Sora 2, OpenAI's video generation model, allows you to upload reference images via the API to guide video creation. This is a classic scenario for multipart/form-data.

Sora 2 Image-to-Video API Parameters

{{SVG_TEXT_0}} Sora 2 vs Sora 2 Pro Model Comparison
{{SVG_TEXT_1}} Access both models via APIYI (apiyi.com)
{{SVG_TEXT_2}} sora-2
{{SVG_TEXT_3}} sora-2-pro
{{SVG_TEXT_4}} Generation Quality
{{SVG_TEXT_5}} Good
{{SVG_TEXT_6}} Excellent
{{SVG_TEXT_7}} Rendering Speed
{{SVG_TEXT_8}} Fast
{{SVG_TEXT_9}} Slow
{{SVG_TEXT_10}} API Cost
{{SVG_TEXT_11}} Standard
{{SVG_TEXT_12}} High
{{SVG_TEXT_13}} Use Case
{{SVG_TEXT_14}} Rapid Prototyping
{{SVG_TEXT_15}} PoC and Iterative Testing
{{SVG_TEXT_16}} Production Output
{{SVG_TEXT_17}} High-quality Finals, Commercial Projects
{{SVG_TEXT_18}} File Upload
{{SVG_TEXT_19}} ✓ Supports input_reference
{{SVG_TEXT_20}} ✓ Supports input_reference
{{SVG_TEXT_21}} 💡 Pro-tip: Use sora-2 for fast iteration during development, then switch to sora-2-pro for top-tier quality in the final output.

Sora 2 Model Comparison

Full Example for Sora 2 File Upload

Here’s a complete curl command to generate a video using a reference image on Sora 2:

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="@/absolute/path/to/sample_720p.jpeg;type=image/jpeg"

Command Breakdown

🚀 Quick Start: We recommend using the APIYI (apiyi.com) platform for quick Sora 2 API testing. It provides ready-to-use interfaces, making integration seamless without complex configurations.

Key Considerations for Image Uploads

When uploading reference images to the Sora 2 API, keep these points in mind:

Implementing multipart/form-data Upload in Python

While curl is great for quick tests, you'll likely use a programming language for actual development. Here's how to handle file uploads in Python.

Minimal Example

import requests

# Using the unified APIYI interface
url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Preparing multipart data
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 Client - Supports multipart/form-data file uploads"""

    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:
        """
        Create a video generation task

        Args:
            prompt: Video description (prompt)
            model: Model selection (sora-2 or sora-2-pro)
            size: Resolution
            seconds: Duration (4, 8, 12)
            input_reference: Path to reference image (optional)

        Returns:
            Dictionary containing task information
        """
        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):
            # Determine MIME type based on file extension
            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:
        """Query the status of video generation"""
        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:
        """Poll and wait for video generation to finish"""
        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)


# Example usage
if __name__ == "__main__":
    client = Sora2Client(api_key=os.getenv("APIYI_KEY"))

    # Create an Image-to-Video task
    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}")

Pro-tip: You can get free test credits at apiyi.com to quickly verify the Image-to-Video feature.

Multipart Handling in the requests Library

When using Python's requests library to handle multipart/form-data, keep these key points in mind:

⚠️ Note: When you use the data and files parameters together, requests automatically sets the correct Content-Type and boundary for you. You don't need to (and shouldn't) specify them manually.

JavaScript/Node.js Implementation

Browser Environment (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'
        // Note: Do NOT manually set Content-Type
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Node.js Environment

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));

💡 Key Tip: When using FormData in the browser, don't manually set the Content-Type header. The browser will automatically add the correct boundary parameter for you.

Troubleshooting Common multipart/form-data Issues

Common Upload Failures

Debugging Tips

Use curl's -v flag to inspect the complete request:

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

This will show you:

• Request headers (including the auto-generated Content-Type and boundary)
• The structure of the request body
• The server's response

FAQ

Summary

In this article, we've taken a deep dive into multipart/form-data, the core technology behind API file uploads:

Key Takeaways:

Mastering multipart/form-data is a fundamental skill for AI API development. Whether you're working with Sora 2 for video generation, GPT-4 Vision for image understanding, or any other API that requires file uploads, the core principles remain the same.

We recommend using APIYI at apiyi.com to quickly verify your file upload functionality and experience a unified API interface with comprehensive technical support.

Author: APIYI Team | Dedicated to sharing Large Language Model API technical insights.
Technical Exchange: Visit apiyi.com for more API development resources.

References

1. RFC 2388: multipart/form-data Standard Specification

   • Link: tools.ietf.org/html/rfc2388

2. curl Official Documentation: Multipart Formposts

   • Link: everything.curl.dev/http/post/multipart

3. MDN Web Docs: Using FormData Objects

   • Link: developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects

4. OpenAI Sora API Documentation: Video Generation Guide

   • Link: platform.openai.com/docs/guides/video-generation