Menguasai Unggah File API: Panduan Lengkap multipart/form-data dan Contoh Praktis Sora 2

Upload file API adalah kebutuhan teknis yang sering ditemui pengembang saat memanggil interface seperti pembuatan video AI, pemrosesan gambar, dan lain-lain. Artikel ini akan menjelaskan secara sistematis prinsip kerja metode pengodean multipart/form-data, dan menggunakan API Sora 2 Image-to-Video sebagai contoh untuk membantu Anda menguasai keterampilan inti unggah file API.

Nilai Inti: Setelah membaca artikel ini, Anda akan memahami sepenuhnya mekanisme dasar multipart/form-data, mempelajari cara menggunakan perintah curl -F untuk mengunggah file, dan mampu mengimplementasikan fitur unggah gambar untuk AI API seperti Sora 2 secara mandiri.

Pengetahuan Inti Unggah File API

Sebelum masuk ke kode, kita perlu memahami mengapa unggah file API memerlukan metode pengodean khusus.

Mengapa memerlukan multipart/form-data

Saat Anda mengirim data teks biasa melalui API, Anda dapat menggunakan pengodean sederhana application/x-www-form-urlencoded. Namun, metode ini memiliki masalah serius saat menangani file:

multipart/form-data adalah solusi yang diusulkan dalam standar RFC 2388 pada tahun 1998, khusus untuk menyelesaikan masalah pengiriman campuran data teks dan biner dalam protokol HTTP.

Prinsip Kerja multipart/form-data

Ide utama dari multipart/form-data adalah membagi satu body permintaan HTTP menjadi beberapa "bagian" (parts) yang independen, di mana setiap bagian dapat memiliki tipe kontennya sendiri.

Detail Struktur Data

Permintaan multipart/form-data yang tipikal berisi struktur berikut:

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

[Data gambar biner]
------WebKitFormBoundary7MA4YWxk--

🎯 Poin Teknis: Boundary harus berupa string unik yang tidak akan muncul di dalam body permintaan. Server menggunakan boundary untuk mem-parse dan memisahkan setiap bagian data.

Penjelasan Lengkap Perintah curl -F: Praktik Upload File API

curl adalah alat klien HTTP baris perintah yang paling sering digunakan, dan parameter -F miliknya khusus digunakan untuk permintaan multipart/form-data.

Sintaks Dasar curl -F

curl -F "nama_field=nilai" URL
curl -F "field_file=@jalur_file_lokal" URL

Perbedaan antara curl -F dengan Parameter Lainnya

Banyak pengembang sering bingung dalam menggunakan -F, -d, dan -X POST:

# ❌ Salah: -d digunakan untuk x-www-form-urlencoded, tidak cocok untuk upload file
curl -X POST -d "[email protected]" https://api.example.com/upload

# ❌ Salah: Menentukan Content-Type secara manual tetapi menggunakan -d
curl -X POST -H "Content-Type: multipart/form-data" -d "..." https://api.example.com/upload

# ✅ Benar: Menggunakan -F secara otomatis mengatur Content-Type dan boundary yang tepat
curl -F "[email protected]" https://api.example.com/upload

Penjelasan Teknis: Saat menggunakan -F, curl akan secara otomatis:

1. Mengatur metode permintaan menjadi POST
2. Mengatur Content-Type: multipart/form-data
3. Menghasilkan boundary yang unik
4. Memformat badan permintaan (request body) sesuai standar RFC

Praktik Upload File API Sora 2

Sora 2 adalah model pembuatan video yang diluncurkan oleh OpenAI, yang mendukung pengunggahan gambar referensi melalui API untuk menghasilkan video. Ini adalah skenario aplikasi tipikal untuk multipart/form-data.

Parameter API Video dari Gambar Sora 2

Perbandingan Model Sora 2

Contoh Lengkap Upload File Sora 2

Berikut adalah contoh lengkap menggunakan curl untuk memanggil API Sora 2 guna melakukan pembuatan video dari gambar:

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"

Analisis Perintah

🚀 Mulai Cepat: Direkomendasikan menggunakan platform APIYI apiyi.com untuk menguji API Sora 2 dengan cepat. Platform ini menyediakan antarmuka API siap pakai tanpa memerlukan konfigurasi rumit untuk menyelesaikan integrasi.

Hal yang Perlu Diperhatikan Saat Upload Gambar

Saat menggunakan API Sora 2 untuk mengunggah gambar referensi, perhatikan hal berikut:

Implementasi Python untuk Unggah multipart/form-data

Selain curl, dalam pengembangan nyata kita lebih sering menggunakan bahasa pemrograman untuk melakukan unggah berkas. Berikut adalah cara implementasinya menggunakan Python.

Contoh Sangat Sederhana

import requests

# Menggunakan antarmuka terpadu APIYI
url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Menyiapkan data 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:
    """Klien API Sora 2 - Mendukung unggahan berkas 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:
        """
        Membuat tugas pembuatan video

        Args:
            prompt: Deskripsi video (petunjuk)
            model: Pilihan model (sora-2 atau sora-2-pro)
            size: Resolusi
            seconds: Durasi (4, 8, 12)
            input_reference: Jalur gambar referensi (opsional)

        Returns:
            Kamus informasi tugas
        """
        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):
            # Menentukan tipe MIME berdasarkan ekstensi berkas
            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:
        """Memeriksa status pembuatan video"""
        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:
        """Polling untuk menunggu pembuatan video selesai"""
        while True:
            status = self.get_video_status(video_id)
            if status.get("status") in ["completed", "failed"]:
                return status
            print(f"Status: {status.get('status')}... menunggu {poll_interval} detik")
            time.sleep(poll_interval)


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

    # Membuat tugas Image-to-Video
    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"Tugas berhasil dibuat: {result['id']}")
        final_result = client.wait_for_completion(result["id"])
        print(f"Video URL: {final_result.get('video_url')}")
    else:
        print(f"Terjadi kesalahan: {result}")

Saran: Dapatkan kuota pengujian gratis melalui APIYI apiyi.com untuk memvalidasi fitur Image-to-Video dengan cepat.

Penanganan multipart pada pustaka requests

Poin penting dalam menangani multipart/form-data dengan pustaka requests Python:

⚠️ Catatan: Saat menggunakan parameter data dan files secara bersamaan, requests akan secara otomatis mengatur Content-Type dan boundary yang benar, jadi Anda tidak perlu menentukannya secara manual.

Solusi Implementasi JavaScript/Node.js

Lingkungan Browser (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'
        // Catatan: Jangan mengatur Content-Type secara manual
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

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

💡 Tip Penting: Saat menggunakan FormData di browser, jangan mengatur header Content-Type secara manual. Browser akan menambahkan parameter boundary yang benar secara otomatis.

Pemecahan Masalah Umum multipart/form-data

Penyebab Umum Gagal Unggah

Tips Debugging

Gunakan parameter -v pada curl untuk melihat detail permintaan lengkap:

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

Ini akan menampilkan:

• Header permintaan (termasuk Content-Type dan boundary yang dibuat otomatis)
• Struktur isi permintaan (request body)
• Respons server

Pertanyaan Umum (FAQ)

Ringkasan

Artikel ini menjelaskan secara rinci teknologi inti untuk unggah file API, yaitu multipart/form-data:

Tinjauan Poin Penting:

Menguasai multipart/form-data adalah kemampuan dasar dalam pengembangan API AI. Baik itu pembuatan video Sora 2, pemahaman gambar GPT-4 Vision, atau API lain yang memerlukan unggah file, prinsip intinya tetap sama.

Direkomendasikan untuk menggunakan APIYI apiyi.com guna memvalidasi fungsi unggah file dengan cepat, merasakan antarmuka API yang seragam, dan dukungan teknis yang mendalam.

Penulis: APIYI Team | Fokus pada berbagi teknologi API Model Bahasa Besar AI
Diskusi Teknis: Kunjungi apiyi.com untuk mendapatkan lebih banyak sumber daya pengembangan API

Referensi

1. RFC 2388: Spesifikasi standar multipart/form-data

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

2. Dokumentasi resmi curl: Multipart Formposts

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

3. MDN Web Docs: Menggunakan Objek FormData

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

4. Dokumentasi OpenAI Sora API: Panduan Pembuatan Video

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