Skip to main content
Referensi Open API Directing

Referensi API HappyOyster-Directing-Create World

Buat World directing waktu nyata. Mendukung mode standar (prompt bahasa alami) dan mode skrip (ScriptList terstruktur); API segera mengembalikan ID World yang terenkripsi, World dibangun secara asinkron di latar belakang, dan klien melakukan polling terhadap progres pembangunan hingga selesai.

Cakupan

Buat Directing World. Sebelum memanggil, pastikan hal berikut:
  • Autentikasi: Hanya API Key utama yang didukung; API Key sementara tidak dapat digunakan (kode kesalahan 403003).
  • Mode pemanggilan: Mode asinkron direkomendasikan.
    • Mode asinkron (default): async=true, API segera mengembalikan encryptedWorldId; lakukan polling Query World Build Status untuk melihat progres.
    • Mode sinkron: async=false, server melakukan polling secara internal (setiap 3 detik, hingga 120 detik) dan mengembalikan hasil saat pembangunan selesai; jika waktu habis, sistem kembali ke mode asinkron dan klien terus melakukan polling.
  • Batasan endpoint: Endpoint ini hanya dapat membuat Directing World. Anda tidak perlu meneruskan mode (server menulis 2; meneruskan nilai selain 2 akan mengembalikan 400000). creationModel mendukung simple (mode standar, default) dan scriptlist (mode naskah); versi masuk ruangan ditetapkan ke storyV2, dan aspectRatio serta maxExperienceTimeSec ditetapkan ke null.

Permintaan HTTP

  • Singapore
  • AS (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worldsGanti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya.

Mode standar (creationModel=simple)

Parameter permintaan

  • Mode standar · teks biasa (pembuatan asinkron)
  • Mode standar · teks + gambar referensi (pembuatan asinkron)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "First-person (POV) interactive video: the camera simulates my own eyes, locked on a white Maltese puppy directly in front of me — white chef's hat, black-buttoned chef's coat. Soft home-kitchen background, warm light, the puppy's gaze always facing the camera.",
    "resolution": "720p",
    "layout": "Stable",
    "narrative": "Calm"
}'
Content-Typestring(Wajib)Tipe konten permintaan. Parameter ini harus diatur ke application/json.
Authorization string (Wajib)Autentikasi API Key. Hanya API Key utama yang didukung; dimulai dengan sk-, misalnya sk-xxx. Biasanya dikonfigurasi sebagai variabel lingkungan $DASHSCOPE_API_KEY. API Key sementara (dimulai dengan st-) akan mengembalikan 403003.
Request Body
async boolean (Opsional)Apakah akan membuat secara asinkron. Defaultnya adalah true:
  • true: mengembalikan hasil segera; World dibangun di latar belakang, dan klien melakukan polling Query World Build Status.
  • false: server melakukan polling setiap 3 detik hingga maksimal 120 detik dan mengembalikan hasil saat pembangunan selesai; jika waktu habis, sistem tetap mengembalikan generating, dan klien kemudian melakukan polling secara mandiri.
creationModel string (Opsional)Sub-mode pembuatan; gunakan simple untuk mode standar (default). Anda memberikan prompt bahasa alami, dan server menghasilkan naskah 45 beat lengkap, bingkai pertama (yang dapat Anda sediakan), dan gambar referensi karakter. Setelah Dunia dibuat, Anda dapat memanggil endpoint kontrol berikut selama fase Travel:
  • instruct: kirim instruksi proses teks
  • pause: jeda
  • resume: lanjutkan
  • rewind: putar balik
  • end: akhiri
Lihat Catatan tambahan untuk deskripsi setiap endpoint.
eventStyle string (Opsional)Hanya berlaku untuk creationModel=simple: memilih templat pembuatan naskah. Defaultnya normal. Nilai yang diizinkan:
  • normal: gaya reguler / standar (default). Menyelesaikan 4–5 babak sesuai niat pengguna dengan tempo yang relatif stabil, tanpa memaksakan konflik, pembalikan, atau klimaks tiga babak.
  • dramatic: gaya dramatis / konflik. Menghasilkan naskah pada kerangka tiga babak sekitar 180 detik: pengait pembuka, konflik yang meningkat, titik balik, resolusi klimaks; untuk pertunjukan terbuka, ini mengatur pembalikan berdasarkan genre (misteri / thriller / kebangkitan, dll.), dengan tempo yang lebih padat dan drama yang lebih kuat.
  • regular: nilai lama, dipertahankan hanya untuk kompatibilitas mundur dengan input historis; server mem-parsingnya sebagai normal. Jangan menggunakannya dalam panggilan baru.
refWorldId string (Opsional)Menurunkan kreasi baru dari Directing World yang sudah ada. Harus berupa ID Dunia Terenkripsi Directing di bawah akun utama saat ini; Dunia dari model lain atau akun utama lain akan mengembalikan 403001.
prompt string (Wajib)Deskripsi tema dunia; bahasa Mandarin dan Inggris didukung. Tidak boleh kosong, hingga 2000 karakter.
resolution string (Wajib)Resolusi video. Nilai yang diizinkan:
  • 480p
  • 720p
layout string (Opsional)Gaya pergerakan kamera (bagaimana kamera bergerak dan seberapa keras potongannya). Nilai yang diizinkan:
  • Stable: kamera stabil, sedikit gerakan, mengutamakan pengambilan panjang berkelanjutan dengan potongan yang jarang
  • Fast: kamera cepat, momentum kuat, dengan potongan keras yang lebih padat / zoom cepat / lompatan ukuran pengambilan gambar
  • Calm: di antara keduanya, kamera yang terkendali yang tidak terburu-buru maupun agresif
narrative string (Opsional)Gaya narasi (seberapa padat dramanya dan seberapa kuat emosinya). Nilai yang diizinkan:
  • Calm: sedikit peristiwa, mengutamakan suasana dan perkembangan lambat
  • Dramatic: peristiwa padat, dengan reaksi / pembalikan / hambatan yang lebih menonjol dan ketegangan tinggi
  • Normal: kepadatan narasi reguler, tingkat menengah
  • Steady: tempo merata tanpa menumpuk klimaks, mendekati Normal
firstFrameImage object (Opsional)Jika disediakan, gambar tersebut digunakan kembali secara langsung sebagai bingkai pertama Dunia, melewatkan pembuatan bingkai pertama AI. url dan base64 saling eksklusif (pilih salah satu). Batasan gambar:
  • Format: JPG / JPEG / PNG / WebP
  • Ukuran: harus kurang dari 6 MB per gambar
  • Rasio aspek: harus lanskap, lebar / tinggi sebesar 1.5–2.0 (rasio bingkai mengikuti gambar ini)
  • Keamanan konten: kegagalan verifikasi keamanan konten atau hak cipta / IP mengembalikan 403004 / 403005

Properti

url string (Wajib bersyarat)URL gambar bingkai pertama. Batasan:
  • Harus berupa URL http / https yang valid dengan host, dan dapat diakses oleh server
  • Format, ukuran, dan rasio aspek frame pertama yang sebenarnya divalidasi setelah penyimpanan
  • Permintaan asinkron mungkin pertama kali mengembalikan generating, kemudian World memasuki status failed karena kegagalan validasi gambar
base64 string (Wajib bersyarat)Base64 gambar bingkai pertama. Batasan:
  • Data URI lengkap data:image/<subtype>;base64,<payload> direkomendasikan
  • Format, ukuran, dan rasio aspek frame pertama divalidasi secara sinkron pada titik masuk pembuatan
referenceType string (Opsional)Jenis gambar referensi. Defaultnya adalah default.
inputImages array (Opsional)Digunakan untuk pembuatan naskah dan gambar referensi karakter, hingga 6 gambar, independen dari firstFrameImage. Untuk setiap item array, url dan base64 saling eksklusif (pilih salah satu). Batasan gambar:
  • Format: JPG / JPEG / PNG / WebP
  • Ukuran: harus kurang dari 6 MB per gambar
  • Rasio aspek: harus lanskap, lebar / tinggi sebesar 1.5–2.0 (rasio bingkai mengikuti gambar ini)
  • Keamanan konten: kegagalan verifikasi keamanan konten atau hak cipta / IP mengembalikan 403004 / 403005

Properti

url string (Wajib bersyarat)URL gambar. Batasan:
  • Harus berupa URL http / https yang valid dengan host, dan dapat diakses oleh server
  • Format, ukuran, dan rasio aspek yang sebenarnya divalidasi setelah penyimpanan
  • Permintaan asinkron mungkin pertama kali mengembalikan generating, kemudian World memasuki status failed karena kegagalan validasi gambar
base64 string (Wajib bersyarat)Base64 gambar. Batasan:
  • Data URI lengkap data:image/<subtype>;base64,<payload> direkomendasikan
  • Format, ukuran, dan rasio aspek divalidasi secara sinkron pada titik masuk pembuatan
referenceType string (Opsional)Jenis gambar referensi. Defaultnya adalah default.

Mode naskah (creationModel=scriptlist)

Parameter permintaan

  • Mode skrip (pembuatan asinkron)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "scriptlist",
    "resolution": "720p",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
        "referenceType": "default"
    },
    "scriptList": {
        "videoTitle": "Su Nian · Sitting with You for a While Tonight",
        "synopsis": "The young girl Su Nian sits at a light-colored desk facing the camera, chatting with you slowly and helping you let go of the day.",
        "subjects": [
            {
                "label": "[character_1]",
                "name": "Su Nian",
                "type": "character",
                "gender": "female",
                "age": "young girl",
                "ethnicity": "East Asian",
                "appearance": "medium-length straight black hair with a side part, a rounded face, a cream-white knit top, anime style, clean lines",
                "position": "center of the frame, seated at a light-colored desk",
                "voice": "gentle girlish voice, slightly slow pace, moderate volume"
            }
        ],
        "acts": [
            {
                "turn": 1,
                "content": "[character_1] sits at the light-colored desk facing the camera, leaning slightly forward, eyes curving as she softly says, \"Hey, I'll sit with you for a while again tonight, let's chat slowly.\"",
                "cameraType": "Push-in",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] folds her hands on the desk, nods gently, and says, \"Let's set aside all the worries of the day for now.\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 3,
                "content": "[character_1] tilts her head slightly, looking at the camera with a gentle expression, and asks, \"How was your day? Are you okay, are you tired?\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            }
        ]
    }
}'
Content-Typestring(Wajib)Tipe konten permintaan. Parameter ini harus diatur ke application/json.
Authorization string (Wajib)Autentikasi API Key. Hanya API Key utama yang didukung; dimulai dengan sk-, misalnya sk-xxx. Biasanya dikonfigurasi sebagai variabel lingkungan $DASHSCOPE_API_KEY. API Key sementara (dimulai dengan st-) akan mengembalikan 403003.
Request Body
async boolean (Opsional)Apakah akan membuat secara asinkron. Defaultnya adalah true:
  • true: mengembalikan hasil segera; World dibangun di latar belakang, dan klien melakukan polling Query World Build Status.
  • false: server melakukan polling setiap 3 detik hingga maksimal 120 detik dan mengembalikan hasil saat pembangunan selesai; jika waktu habis, sistem tetap mengembalikan generating, dan klien kemudian melakukan polling secara mandiri.
creationModel string (Opsional)Sub-mode pembuatan; gunakan scriptlist untuk mode naskah. Anda menyediakan naskah terstruktur, dan server tidak lagi membuat naskah — server hanya merakit dan menyimpannya. Setelah Dunia dibuat, Anda dapat memanggil endpoint kontrol berikut selama fase Travel:
  • update-script: ganti naskah sepenuhnya
  • pause: jeda
  • resume: lanjutkan
  • rewind: putar balik
  • end: akhiri
instruct (mengirim instruksi proses teks) tidak didukung. Lihat Catatan tambahan untuk deskripsi setiap endpoint.
eventStyle tidak digunakan oleh pembuatan scriptlist; jangan meneruskannya.
refWorldId string (Opsional)Menurunkan kreasi baru dari Directing World yang sudah ada. Harus berupa ID Dunia Terenkripsi Directing di bawah akun utama saat ini; Dunia dari model lain atau akun utama lain akan mengembalikan 403001.
resolution string (Wajib)Resolusi video. Nilai yang diizinkan:
  • 480p
  • 720p
firstFrameImage object (Wajib)Referensi gambar yang digunakan kembali secara langsung sebagai bingkai pertama World. url dan base64 saling eksklusif (pilih salah satu). Batasan gambar:
  • Format: JPG / JPEG / PNG / WebP
  • Ukuran: harus kurang dari 6 MB per gambar
  • Rasio aspek: harus lanskap, lebar / tinggi sebesar 1.5–2.0 (rasio bingkai mengikuti gambar ini)
  • Keamanan konten: kegagalan verifikasi keamanan konten atau hak cipta / IP mengembalikan 403004 / 403005

Properti

url string (Wajib bersyarat)URL gambar bingkai pertama. Batasan:
  • Harus berupa URL http / https yang valid dengan host, dan dapat diakses oleh server
  • Format, ukuran, dan rasio aspek frame pertama yang sebenarnya divalidasi setelah penyimpanan
  • Permintaan asinkron mungkin pertama kali mengembalikan generating, kemudian World memasuki status failed karena kegagalan validasi gambar
base64 string (Wajib bersyarat)Base64 gambar bingkai pertama. Batasan:
  • Data URI lengkap data:image/<subtype>;base64,<payload> direkomendasikan
  • Format, ukuran, dan rasio aspek frame pertama divalidasi secara sinkron pada titik masuk pembuatan
referenceType string (Opsional)Jenis gambar referensi. Defaultnya adalah default.
scriptList object (Wajib)Naskah terstruktur. Harus menyertakan synopsis dan acts yang tidak kosong.

Properti

synopsis string (Wajib)Sinopsis cerita. Tidak boleh kosong, hingga 2000 karakter.videoTitle string (Opsional)Nama dunia. Defaultnya adalah New World, hingga 128 karakter.scene string (Opsional)Pengaturan adegan. Defaultnya Static Shot, hingga 64 karakter.style string (Opsional)Gaya visual. Defaultnya adalah Stable, hingga 64 karakter.speed string (Opsional)Tempo narasi. Defaultnya Steady, hingga 64 karakter.language string (Opsional)Bahasa naskah. Defaultnya en (Inggris); gunakan zh untuk bahasa Mandarin. Hingga 64 karakter.setting string (Opsional)Pandangan dunia atau pengaturan latar belakang. Hingga 2000 karakter.soundtrack string (Opsional)Deskripsi jalur suara. Hingga 500 karakter.prologue string (Opsional)Prolog pembuka. Hingga 1000 karakter.videoTags array<string> (Opsional)Tag video. Hingga 20 tag, masing-masing hingga 32 karakter.subjects array<object> (Opsional)Subjek yang telah ditentukan sebelumnya, hingga 6. Setiap item array berisi properti berikut:
label string (Opsional)Mereferensikan subjek dalam acts[].content. Diformat sebagai [character_x], ditetapkan dalam urutan array secara default.name string (Opsional)Nama yang dapat dibaca manusia, tidak dirender sebagai teks di layar. Hingga 64 karakter.type string (Opsional)Jenis subjek. Defaultnya character. Menentukan penampilan subjek dan bagaimana properti lainnya diisi. Nilai yang diizinkan:
  • character: karakter manusia (default). Isi gender / position / ethnicity / age / appearance seperti untuk seseorang.
  • animal: hewan nyata (kucing, anjing, kuda, dll.). Gunakan spesies alih-alih gender dan subspesies / ras alih-alih etnisitas.
  • creature: makhluk non-manusia / fantasi (naga, monster, alien, dll.). Isi juga untuk penampilan non-manusia.
  • narrator: narator / sulih suara. Hanya suara, tidak muncul di layar; isi voice dan tidak ada gambar referensi yang dihasilkan.
refImage object (Opsional)Gambar referensi subjek; url dan base64 saling eksklusif (pilih salah satu), dan gambar harus benar-benar kurang dari 6 MB.
url string (Wajib bersyarat)URL gambar referensi subjek.base64 string (Wajib bersyarat)Base64 gambar referensi subjek.referenceType string (Opsional)Jenis gambar referensi. Defaultnya adalah default.
gender string (Opsional)Deskripsi jenis kelamin. Hingga 64 karakter.position string (Opsional)Posisi di layar. Hingga 64 karakter.ethnicity string (Opsional)Deskripsi etnis atau ras. Hingga 64 karakter.age string (Opsional)Deskripsi usia. Hingga 64 karakter.appearance string (Opsional)Detail penampilan. Hingga 500 karakter.voice string (Opsional)Deskripsi suara, kecepatan bicara, dan volume. Hingga 200 karakter.
acts array<object> (Wajib)Naskah beat demi beat, 1–45 entri, dengan semua content berjumlah tidak lebih dari 100000 karakter. Setiap item array berisi properti berikut:
turn int (Opsional)Nomor giliran. 1–45, tanpa duplikat, bertambah dari 1 dalam urutan array secara default.content string (Wajib)Naskah untuk beat ini. Tidak boleh kosong, hingga 2000 karakter per beat; dapat mereferensikan subjek dengan [character_x].cameraType string (Opsional)Jenis kamera (cara kamera merekam). Defaultnya Static. Nilai yang diizinkan:
  • Static: kamera terkunci di tempat, tanpa dorongan atau putaran (default). Ukuran pengambilan gambar dikendalikan oleh shotSize: wide / medium / close
  • Tracking: pengambilan gambar pelacakan. Kamera mengikuti subjek, mempertahankan jarak pelacakan
  • Pan Left: kamera tetap diam, pan ke kiri
  • Pan Right: kamera tetap diam, pan ke kanan
  • Tilt Up: kamera mendongak ke atas
  • Tilt Down: kamera menunduk ke bawah
  • Push-in: push-in optik / fisik, bingkai semakin mendekat secara bertahap
  • Pull-out: tarik keluar, bingkai perlahan melebar
  • POV Forward: orang pertama, kamera adalah mata, berjalan maju
  • POV Look Down: orang pertama melihat ke bawah
  • POV Look Up: orang pertama melihat ke atas
  • POV Turn Left: orang pertama menoleh ke kiri untuk melihat
  • POV Turn Right: orang pertama menoleh ke kanan untuk melihat
shotSize string (Opsional)Ukuran pengambilan gambar. Defaultnya Medium. Menentukan berapa banyak detail yang dapat dibawa oleh beat ini; ubah ukuran pengambilan gambar melalui potongan, dan jangan mendeskripsikan seluruh tubuh dan ujung jari dalam beat yang sama. Nilai yang diizinkan:
  • Wide: pengambilan gambar lebar / penuh, mencakup seluruh tubuh dan hubungannya dengan lingkungan. Cocok untuk blocking, penempatan posisi, dan pementasan spasial; jangan mendeskripsikan mikro-ekspresi atau ujung jari.
  • Medium: pengambilan gambar medium (default), postur dan gestur tubuh bagian atas. Cocok untuk dialog dan tindakan sehari-hari; jangan mendeskripsikan blocking kaki atau operasi tangan yang halus.
  • Close-up: close-up, satu wajah / satu tangan / satu properti. Cocok untuk ekspresi dan detail penting; jangan mendeskripsikan gerakan seluruh tubuh.
Dipasangkan dengan potongan: untuk melihat lebih banyak detail, pertama lakukan cut-in ke Close-up, lalu cut-out kembali ke pengambilan gambar lebar; gunakan long-take untuk sebagian besar beat guna mempertahankan ukuran pengambilan gambar yang sama dan menghindari lompatan ukuran pengambilan gambar bolak-balik.cut string (Opsional)Metode pemotongan (cara beat ini dipotong masuk). Defaultnya long-take. Nilai yang diizinkan:
  • long-take: tanpa potongan, melanjutkan dari pengambilan gambar sebelumnya. Default dan yang paling stabil
  • hard-cut: potongan keras, langsung beralih ke pengambilan gambar lain. Gunakan ini untuk dialog shot / reverse-shot
  • cut-in: memotong ke ukuran pengambilan gambar yang lebih dekat, mis. Medium → Close-up. Gunakan untuk melihat detail dan memotong ke interaksi tangan
  • cut-out: memotong ke ukuran pengambilan gambar yang lebih lebar, mis. Close-up → Medium / Wide
  • cutaway: potong singkat ke detail di luar garis utama
  • cutback: memotong kembali ke subjek utama dari sebuah cutaway. Hanya dapat mengikuti sebuah cutaway
  • camera movement transition: menghubungkan dua segmen dengan pergerakan kamera yang cepat alih-alih potongan keras

Parameter respons

  • Pembuatan asinkron
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}
code integerKode pengembalian. 0 berarti berhasil; bukan nol adalah kode kesalahan.
message stringPesan kesalahan. null jika berhasil.
data objectData respons. null jika gagal.

Properti

encryptedWorldId stringID Dunia Terenkripsi, dikembalikan dalam mode sinkron dan asinkron. Nilai ini digunakan untuk kueri status pembangunan berikutnya, kueri detail Dunia, dan menukar kredensial pengalaman.status stringStatus pembuatan saat ini:
  • generating: sedang dibuat
  • ready: siap
  • failed: pembuatan gagal
firstFrame stringURL frame pertama World; null sebelum dihasilkan.

Catatan tambahan

  • Penghitungan karakter: Batas "hingga N karakter" dalam dokumen ini dihitung berdasarkan karakter (karakter Unicode), terlepas dari bahasa Mandarin atau Inggris — karakter Mandarin, huruf Inggris, angka, spasi, dan tanda baca masing-masing dihitung sebagai 1 karakter.
  • Persyaratan pengiriman ScriptList: Saat membuat Dunia, acts dibatasi hingga 45 entri tetapi tidak harus tepat 45; 45 entri lengkap hanya diperlukan saat memanggil update-script selama Travel.
  • Endpoint kontrol Travel: Nama endpoint yang tercantum di bawah creationModel adalah endpoint sisi server yang dapat dipanggil selama fase Travel setelah Dunia dibuat, bukan nilai enum untuk input endpoint ini. Artinya adalah sebagai berikut:

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan kesalahan, lihat Kode Kesalahan HappyOyster untuk menyelesaikannya.

Langkah selanjutnya

Setelah berhasil membuat, Anda dapat:
Pembuatan Gambar
  • FAQ
Video Generation
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production