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).- Dapatkan API Key utama: Mendapatkan dan mengonfigurasi API Key.
-
Mode pemanggilan: Mode asinkron direkomendasikan.
- Mode asinkron (default):
async=true, API segera mengembalikanencryptedWorldId; 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.
- Mode asinkron (default):
-
Batasan endpoint: Endpoint ini hanya dapat membuat Directing World. Anda tidak perlu meneruskan
mode(server menulis2; meneruskan nilai selain2akan mengembalikan400000).creationModelmendukungsimple(mode standar, default) danscriptlist(mode naskah); versi masuk ruangan ditetapkan kestoryV2, danaspectRatiosertamaxExperienceTimeSecditetapkan kenull.
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 |
|
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:
| |
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:
| |
eventStyle string (Opsional)Hanya berlaku untuk creationModel=simple: memilih templat pembuatan naskah. Defaultnya normal. Nilai yang diizinkan:
| |
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:
| |
layout string (Opsional)Gaya pergerakan kamera (bagaimana kamera bergerak dan seberapa keras potongannya). Nilai yang diizinkan:
| |
narrative string (Opsional)Gaya narasi (seberapa padat dramanya dan seberapa kuat emosinya). Nilai yang diizinkan:
| |
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:
Properti url string (Wajib bersyarat)URL gambar bingkai pertama. Batasan:
string (Wajib bersyarat)Base64 gambar bingkai pertama. Batasan:
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:
Properti url string (Wajib bersyarat)URL gambar. Batasan:
string (Wajib bersyarat)Base64 gambar. Batasan:
string (Opsional)Jenis gambar referensi. Defaultnya adalah default. |
Mode naskah (creationModel=scriptlist)
Parameter permintaan |
|
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:
| |
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:
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:
| |
firstFrameImage object (Wajib)Referensi gambar yang digunakan kembali secara langsung sebagai bingkai pertama World. url dan base64 saling eksklusif (pilih salah satu). Batasan gambar:
Properti url string (Wajib bersyarat)URL gambar bingkai pertama. Batasan:
string (Wajib bersyarat)Base64 gambar bingkai pertama. Batasan:
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:
Properti subjects[] 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:
object (Opsional)Gambar referensi subjek; url dan base64 saling eksklusif (pilih salah satu), dan gambar harus benar-benar kurang dari 6 MB.
Properti refImage 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.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.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:
Properti acts[] 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:
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:
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:
|
Parameter respons |
|
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:
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,
actsdibatasi 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
creationModeladalah endpoint sisi server yang dapat dipanggil selama fase Travel setelah Dunia dibuat, bukan nilai enum untuk input endpoint ini. Artinya adalah sebagai berikut:instruct: mengirim instruksi proses teks ke Travel yang sedang berjalan; hanya mode standar.pause: menjeda Travel.resume: melanjutkan pemutaran.rewind: memutar ulang ke titik waktu tertentu; memerlukan penjedaan terlebih dahulu.end: mengakhiri Travel.update-script: mengganti sepenuhnya naskah; hanya mode naskah.
Kode kesalahan
Jika pemanggilan model gagal dan mengembalikan kesalahan, lihat Kode Kesalahan HappyOyster untuk menyelesaikannya.
Langkah selanjutnya
Setelah berhasil membuat, Anda dapat:
- Query World Build Status: lakukan polling setiap 3–5 detik hingga World memasuki status
ready. - Setelah World memasuki status
ready, panggil Get Travel Credential untuk ditukarkan denganticketsekali pakai. - Kueri Detail Dunia: kueri metadata pembuatan lengkap dan ScriptList.