API Sora 2 dengan Python: Panduan Lengkap Disertai Contoh

Mulai Menggunakan OpenAI API

Untuk memulai, kita perlu membuat akun OpenAI dan kunci API. Untuk melakukannya, buka halaman kunci API mereka dan klik "Create new secret key" di pojok kanan atas.

Kunci ini digunakan untuk membuat permintaan ke OpenAI API. Simpan di file bernama .env pada folder tempat kita menulis skrip Python. Pastikan kunci ini tetap rahasia karena siapa pun dapat menggunakannya untuk berinteraksi dengan API menggunakan akun Anda.

Tempel kunci API ke dalam file .env dengan format berikut:

OPENAI_API_KEY=<paste_api_key_here>

Perlu diingat bahwa penggunaan API tidak gratis, sehingga Anda perlu mengisi saldo akun sebelum mampu menghasilkan video menggunakan Sora 2. Sebagai referensi, berikut harga per detik Sora 2:

Membuat Video Sora 2 dengan Python

Seluruh kode untuk tutorial ini dapat ditemukan di repositori GitHub ini.

Untuk berkomunikasi dengan OpenAI API menggunakan Python, kita akan memakai paket openai. Perlu dicatat, karena Sora baru tersedia di API, kita membutuhkan versi paket yang terbaru.

Kita dapat menggunakan perintah ini untuk memasangnya (atau memperbarui versi saat ini jika sudah terpasang):

pip install --upgrade openai

Buat skrip baru bernama generate_video.py di folder yang sama dengan file .env yang kita buat sebelumnya.

Langkah pertama adalah mengimpor paket yang diperlukan. Berikut yang akan kita gunakan:

• os: Paket bawaan untuk berinteraksi dengan sistem operasi;
• openai: Paket resmi OpenAI untuk berinteraksi dengan API mereka;
• dotenv: Paket bawaan yang memudahkan pemuatan variabel lingkungan dari file .env. Dalam kasus ini, kita gunakan untuk memuat kunci API OpenAI.

import os
from openai import OpenAI 
from dotenv import load_dotenv

Selanjutnya, kita memuat file .env:

load_dotenv()
API_KEY = os.getenv("OPENAI_API_KEY")

Dengan kunci API yang dimuat ke memori, kita dapat menginisialisasi klien OpenAI, yang memungkinkan kita membuat permintaan ke OpenAI API. Kita menggunakan pustaka os untuk memuat kunci API:

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Terakhir, kita gunakan fungsi videos.create dari klien untuk menghasilkan video:

video = client.videos.create(
    prompt="A cat and a dog dancing",
)
print(video.id)

Saat kita meminta pembuatan video, kita tidak langsung mendapatkan videonya karena prosesnya memerlukan waktu. Ini berarti variabel video bukanlah videonya, melainkan objek yang berisi informasi tentang tugas pembuatan video.

Itulah sebabnya kita mencetak pengenal video. Informasi ini yang kita perlukan untuk:

1. Melacak progres pembuatan video.
2. Mengambil video.

Kedua langkah ini akan kita jelaskan secara rinci di bawah.

Berikut hasil yang saya dapatkan:

Melacak progres video

Kita dapat mengambil status sebuah job dengan memberikan pengenal job ke fungsi videos.retrieve(), seperti ini:

job = client.videos.retrieve(job_id)
status = job.status
progress = job.progress
print(f"Status: {status}, {progress}%")

Kita perlu menunggu hingga progres mencapai 100% agar dapat mengunduh videonya. Untuk kenyamanan, kita membuat fungsi wait_for_video_to_finish() yang memantau status sebuah job hingga selesai:

def wait_for_video_to_finish(video_id, poll_interval=5, timeout=600):
    """
    Poll status until the video is ready or timeout is reached.
    Returns the final job info.
    """
    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    elapsed = 0  # Keep track of the elapsed time
    while elapsed < timeout:
        job = client.videos.retrieve(video_id)
        status = job.status
        progress = job.progress
        print(f"Status: {status}, {progress}%")
        if status == "completed":
            return job
        if status == "failed":
            raise RuntimeError(f"Failed to generate the video: {job.error.message}") 
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise RuntimeError("Polling timed out")

Fungsi ini memiliki tiga parameter:

• video_id: Pengenal video yang ingin kita lacak.
• poll_interval: Berapa detik kita menunggu di antara setiap permintaan pelacakan.
• timeout: Jumlah detik maksimum untuk menunggu.

Fungsi ini secara berkala memeriksa status video hingga selesai atau waktu polling habis.

Mengunduh video

Sekarang kita dapat melacak proses pembuatan video, yang kita perlukan berikutnya adalah cara mengunduhnya ketika selesai dibuat. Kita dapat melakukannya dengan fungsi videos.download_content().

Berikut fungsi yang melakukannya:

def download_video(video_id):
    client = get_client()
    response = client.videos.download_content(
        video_id=video_id,
    )
    video_bytes = response.read()
    with open(f"{video_id}.mp4", "wb") as f:
        f.write(video_bytes)

Alur lengkap pembuatan video Sora

Kita dapat menyatukan langkah-langkah ini untuk membangun alur kerja pembuatan video dengan Sora:

prompt = "A cat and a dog dancing"
video = client.videos.create(
    prompt="A cat and a dog dancing",
)
video_id = video.id
print(f"Started generating video with id {video_id}")
wait_for_video_to_finish(video_id)
download_video(video_id)

Mengatur ukuran dan durasi video

Skrip di atas hanya menggunakan prompt teks untuk menghasilkan video. Namun, OpenAI Sora 2 API menyediakan opsi lain, seperti:

• model: Model yang digunakan untuk menghasilkan video. Secara default, nilainya sora-2.
• resolution: Ukuran video. Secara default, ukuran video adalah 720x1280.
• duration: Berapa detik panjang video. Secara default, video berdurasi 4 detik.

Berikut tabel dengan semua nilai yang mungkin bergantung pada mode (nilai yang dicetak tebal adalah nilai default):

Agar skrip lebih mudah digunakan, kita dapat memanfaatkan paket bawaan argparse untuk memungkinkan pengguna menentukan nilai setiap parameter.

Berikut contoh cara menetapkan argumen prompt dan model dengan argparse:

parser = argparse.ArgumentParser()
parser.add_argument(
    "--prompt", # Name of the argument
    required=True, # Specify that the argument is required
    help="The video prompt.", # Helper text
)
parser.add_argument(
    "--model",
    default="sora-2", # Specify a default value for the argument
    choices=["sora-2", "sora-2-pro"], # Specify a list of possible values for the argument
    help="Model to use (sora-2 or sora-2-pro).",
)

Untuk memuat argumen, kita memanggil metode parse_args(), seperti ini:

args = parser.parse_args()
prompt = args.prompt
model = args.model

Script generate_video_pipeline.py di repositori GitHub menggabungkan seluruh bagian yang telah kita pelajari menjadi skrip yang dapat menghasilkan video menggunakan Sora 2.

Berikut contoh cara menjalankannya di terminal dengan parameter spesifik:

python generate_video_pipeline.py --prompt "A family of dogs driving a car" --model sora-2-pro  --size 1280x720 --seconds 8

Hasilnya seperti ini:

Tips Prompt API Sora 2

OpenAI menyediakan panduan prompt lengkap untuk Sora 2.

Gagasan mendasar untuk membangun prompt Sora 2 yang baik adalah:

• Seimbangkan detail dan kebebasan: Prompt yang spesifik memberi kendali; yang sederhana mengundang kreativitas.
• Tetapkan parameter di API: Definisikan model (sora-2 atau sora-2-pro), resolusi, dan panjang klip secara eksplisit.
• Pikirkan dalam bidikan: Jelaskan pembingkaian kamera, pencahayaan, subjek, dan satu aksi jelas per bidikan.
• Visual dan konkret: “Aspal basah di bawah lampu neon” lebih baik daripada “sebuah jalan yang indah.”
• Jaga gerak tetap sederhana: Satu aksi subjek + satu gerakan kamera adalah yang terbaik.
• Pencahayaan: Tentukan kualitas cahaya, arah, dan palet warna agar konsisten.
• Gunakan referensi gambar: Tambahkan masukan visual untuk menambatkan gaya dan komposisi.
• Dialog: Kalimat pendek dan natural; beri label jelas; batasi per klip.
• Iterasi dengan Remix: Sesuaikan satu elemen (pencahayaan, lensa, palet) pada satu waktu untuk kontrol yang presisi.

Mereka merangkum ide-ide ini ke dalam templat prompt berikut:

[Prose scene description in plain language. Describe characters, costumes, scenery, weather and other details. Be as descriptive to generate a video that matches your vision.]
Cinematography:
Camera shot: [framing and angle, e.g. wide establishing shot, eye level]
Mood: [overall tone, e.g. cinematic and tense, playful and suspenseful, luxurious anticipation]
Actions:
- [Action 1: a clear, specific beat or gesture]
- [Action 2: another distinct beat within the clip]
- [Action 3: another action or dialogue line]
Dialogue:
[If the shot has dialogue, add short natural lines here or as part of the actions list. Keep them brief so they match the clip length.]

Memberikan prompt panjang di terminal cukup merepotkan. Untuk meningkatkan pengalaman pengguna, kita bisa mengubah skrip sehingga jika prompt berakhiran .txt, skrip mengasumsikan bahwa pengguna memberikan path ke file teks berisi prompt.

Berikut cara kita memperbarui skrip untuk mendukung hal ini:

...
args = parser.parse_args()
prompt = args.prompt
if prompt.endswith(".txt"):
    with open(prompt, "rt") as f:
        prompt = f.read()
video_id = generate_video(prompt, args.model, args.size, args.seconds)
...

Untuk mengujinya, saya membuat file di folder yang sama bernama prompt.txt dengan prompt berikut:

A polite green alien wearing a beret struggles to order croissants in broken French at a bustling Paris café.

Cinematography:
Camera shot: eye-level shot, warm morning light
Mood: whimsical and awkward
Actions:
The alien studies the pastry display, fascinated.
It points to the baguette, then accidentally eats the napkin.
The waiter shrugs, unfazed, and brings it another napkin.
Dialogue:
Alien (content): “Très… chewy.”

Untuk menghasilkan video, kita memberikan prompt.txt pada parameter --prompt:

python generate_video_pipeline.py --prompt prompt.txt --model sora-2-pro  --size 1280x720 --seconds 8

Berikut videonya:

Terlihat bahwa hasilnya tidak sepenuhnya mengikuti prompt. Berdasarkan pengalaman saya bekerja dengan model video AI, saya selalu mendapatkan hasil yang lebih baik dengan membuat beberapa video yang lebih sederhana lalu menggabungkannya.

Namun, untuk melakukan itu, kita perlu membuatnya konsisten. Kita dapat mencapainya dengan memberikan gambar referensi ke model. Itulah yang akan kita pelajari berikutnya.

Membuat Video Sora 2 Berdasarkan Gambar

Untuk membuat video berdasarkan gambar, kita menggunakan parameter input_reference.

Berikut potongan kode cara memuat gambar dan memberikannya ke model sebagai referensi:

f = open("image_reference.jpeg", "rb")

# Generate the video
video = client.videos.create(
    prompt="The two people walk away from each other.",
    input_reference=f
)

f.close()

wait_for_video_to_finish(video.id)
download_video(video.id)

Script generate_video_with_reference.py di repositori GitHub menyediakan contoh lengkap yang berfungsi. Saat dijalankan pada gambar referensi, kita mendapatkan ini:

Agar gambar referensi berfungsi, ukurannya harus sama dengan yang diminta untuk pembuatan video.

Kita dapat menggunakan paket Pillow untuk mengubah ukuran gambar referensi secara otomatis sebelum memberikannya ke model. Namun perlu dicatat, jika rasio aspek gambar asli sangat berbeda, gambar akan terdistorsi, dan kemungkinan video yang dihasilkan kurang baik.

Untuk memasangnya, gunakan perintah:

pip install Pillow

Script sora.py menyediakan implementasi fungsi generate_video() yang menyesuaikan kode yang kita buat sebelumnya untuk mengubah ukuran gambar jika disediakan.

Script generate_video_pipeline_reference.py menunjukkan bagaimana kita dapat menambahkan parameter referensi ke skrip pembuatan video.

Berikut contoh yang dihasilkan dari sebuah foto menggunakan fitur ubah ukuran otomatis yang baru saja kita terapkan:

Menggunakan referensi video

Skrip yang kita bangun di sini siap menangani referensi video maupun gambar. Namun, setiap kali saya mencoba membuat video sambil memberikan video lain sebagai referensi, saya mendapat galat:

Video inpaint is not available for your organization

Menurut forum mereka, tampaknya ini masalah umum, yang menunjukkan bahwa fitur ini belum tersedia untuk semua orang di API. Kita harus menunggu sedikit lebih lama untuk dapat menggunakannya.

Batasan lainnya

Saat saya bekerja dengan Sora 2, saya sering mengalami masalah ketika Sora menolak membuat video, menyatakan bahwa sistem moderasi memblokir permintaan:

RuntimeError: Video generation failed: Your request was blocked by our moderation system.

Saya memahami bahwa sistem seperti ini membutuhkan moderasi yang kuat karena banyak hal merugikan dapat terjadi jika pengguna diizinkan membuat video apa pun yang mereka inginkan. Namun, saya merasa algoritme moderasinya perlu disempurnakan karena sebagian besar permintaan saya diblokir, sehingga saya meninggalkan ide awal saya.

Foto-foto yang saya coba ubah menjadi video tidak mengandung konten sensitif atau masalah hak cipta, karena semua gambar adalah milik saya. Galat tersebut juga tidak memberikan informasi apa pun tentang alasan pemblokiran.

Masalah ini sangat sering terjadi, sehingga membuat saya tidak mampu membuat sesuatu yang bermakna.

Kesimpulan

Sora 2 membuka kemungkinan baru yang menarik untuk pembuatan video berbasis AI, dan berkat ketersediaannya melalui OpenAI API, integrasi alat mutakhir ini ke dalam alur kerja Python Anda kini dapat diakses oleh pengembang dari berbagai latar belakang.

Dengan mengikuti tutorial ini, Anda kini memiliki dasar yang kuat untuk membuat video kustom melalui prompt sederhana, menyetel hasil dengan parameter lanjutan, dan memanfaatkan referensi gambar untuk konsistensi yang lebih tinggi. Seiring API terus berkembang, semakin banyak fitur — termasuk kemampuan video-ke-video yang andal — akan tersedia, memperluas perangkat kreatif Anda.

Baik Anda bereksperimen dengan prompt yang jenaka, membangun storyboard kompleks, atau mengembangkan aplikasi multimedia generasi berikutnya, Sora 2 menawarkan cara ampuh untuk mewujudkan ide Anda. Saya juga menyarankan membaca panduan kami tentang model SAM3 baru dari Meta.