Skip to main content
HappyHorse

Referensi API text-to-video HappyHorse

Hasilkan video yang secara fisik realistis dan gerakannya halus dari prompt teks menggunakan model HappyHorse.

Ketersediaan

Model, URL endpoint, dan Kunci API harus berada di Wilayah yang sama. Panggilan lintas-Wilayah akan gagal.
  • Select a model: Periksa Wilayah tempat model tersebut berada.
  • Select a URL: Gunakan URL endpoint sesuai Wilayah. HTTP didukung.
  • Configure an API key: Dapatkan Kunci API untuk Wilayah tersebut, lalu Ekspor Kunci API sebagai Variabel lingkungan.
Kode contoh dalam topik ini berlaku untuk Wilayah Singapura.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk Wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan Inferensi. Kami merekomendasikan migrasi ke domain baru:
  • China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Workspace Details pada Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi penuh.

Permintaan HTTP

Tugas text-to-video biasanya memerlukan waktu 1 hingga 5 menit. API menggunakan panggilan asinkron dengan dua langkah: "Create a task → Poll for results".

Langkah 1: Buat tugas dan dapatkan ID tugas

  • Singapura
  • AS (Virginia)
  • China (Beijing)
  • Jerman (Frankfurt)
  • China (Hong Kong)
  • Jepang (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
  • Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk mengkueri hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
  • Untuk panduan pemula, lihat Panggil API dengan Postman atau cURL.

Parameter permintaan

Content-Type string (Wajib)Tipe konten permintaan. Harus berupa application/json.Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.X-DashScope-Async string (Wajib)Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus diatur ke enable.
Jika header permintaan ini tidak disertakan, kesalahan "current user api does not support synchronous calls" akan dikembalikan.
Body permintaan
model string (Wajib)Nama model. Untuk daftar model yang tersedia, lihat Konsol Model Studio.Contoh: happyhorse-1.1-t2v.input object (Wajib)Input model.

Properti

prompt string (Wajib)Deskripsi teks video yang akan dihasilkan.Mendukung semua bahasa. Maksimal 5.000 karakter non-Cina atau 2.500 karakter Cina. Input yang melebihi batas akan dipotong.
parameters object (Opsional)Pengaturan output video (resolusi, rasio aspek, durasi).

Properti

resolution string (Opsional)Resolusi video output.Nilai yang valid:
  • 480P
  • 720P
  • 1080P (default)
ratio string (Opsional)Rasio aspek video output.Nilai yang valid:
  • 16:9 (default)
  • 9:16
  • 1:1
  • 4:3
  • 3:4
  • 4:5
  • 5:4
  • 9:21
  • 21:9
duration integer (Opsional)Durasi video output dalam detik.
  • happyhorse-1.0-t2v: 3–15. Default: 5.
watermark boolean (Opsional)Apakah akan menambahkan Watermark. Menampilkan "HappyHorse" di pojok kanan bawah.
  • true (default)
  • false
seed integer (Opsional)Bilangan acak seed harus berupa integer dalam rentang [0, 2147483647].Jika tidak ditentukan, seed acak akan dihasilkan. Seed tetap meningkatkan kemampuan reproduksi.Karena generasi model bersifat probabilistik, seed yang sama tidak menjamin hasil identik.
  • Text-to-video
# URL berikut untuk Wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL bervariasi tergantung Wilayah.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "happyhorse-1.1-t2v",
    "input": {
        "prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead."
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5
    }
}'

Parameter respons

output objectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
request_id stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.
  • Respons sukses
  • Respons error
Simpan task_id untuk mengkueri status dan hasil tugas.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Langkah 2: Kueri hasil berdasarkan ID tugas

  • Singapura
  • AS (Virginia)
  • China (Beijing)
  • Jerman (Frankfurt)
  • China (Hong Kong)
  • Jepang (Tokyo)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Rekomendasi polling: Generasi video memerlukan beberapa menit. Gunakan mekanisme polling dengan interval yang wajar, misalnya 15 detik.
  • Transisi status tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.
  • Tautan hasil: Setelah tugas berhasil, URL video yang berlaku selama 24 jam akan dikembalikan. Unduh dan simpan video ke penyimpanan permanen, seperti OSS.
  • task_idmasa berlaku: 24 jam. Setelah periode ini, kueri akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan

Header
Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Parameter path
task_id string (Wajib)ID tugas.
  • Kueri hasil tugas
Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam, Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter respons

outputobjectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
Transisi status selama polling:
  • PENDING → RUNNING → SUCCEEDED atau FAILED.
  • Status kueri awal biasanya PENDING atau RUNNING.
  • Saat status berubah menjadi SUCCEEDED, respons berisi URL video yang dihasilkan.
  • Jika statusnya FAILED, periksa pesan kesalahan dan coba ulang tugas tersebut.
submit_time stringWaktu saat tugas dikirimkan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL video yang dihasilkan. Hanya dikembalikan ketika task_status bernilai SUCCEEDED.Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.orig_prompt stringPrompt input asli, sesuai dengan parameter permintaan prompt.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.
usage objectStatistik output. Hanya tugas yang berhasil yang dihitung.

Properti

input_video_duration integerDurasi video input dalam detik.output_video_duration integerDurasi video output dalam detik.duration integerTotal durasi video untuk penagihan.SR integerResolusi video output.ratio stringRasio aspek video output.video_count integerJumlah video output. Selalu bernilai 1.
request_id stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.
  • Tugas berhasil
  • Tugas gagal
  • Kueri tugas kedaluwarsa
URL video hanya berlaku selama 24 jam, lalu secara otomatis dipurge. Segera simpan video yang dihasilkan.
{
    "request_id": "99243b47-ec5f-9413-9993-xxxxxx",
    "output": {
        "task_id": "4673458e-28be-4a05-bf2a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 17:55:17.075",
        "scheduled_time": "2026-04-20 17:55:17.129",
        "end_time": "2026-04-20 17:56:36.658",
        "orig_prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead.",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

Kode kesalahan

Panggilan API yang gagal mengembalikan kode kesalahan yang didokumentasikan di Pesan kesalahan.
Penggunaan API
Generasi teks
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Real-time multimodal
Realtime API
Penyematan Teks
Lainnya Model
Toolkit/Framework
TokenPlan
Model production
Manajemen file
Penagihan
Manajemen Model
Lebih Banyak Tentang Model