Referensi API text-to-video HappyHorse - Alibaba Cloud Model Studio

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.

CatatanKode contoh dalam topik ini berlaku untuk Wilayah Singapura.

PentingAlibaba 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

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

AS (Virginia)

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Jerman (Frankfurt)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

China (Hong Kong)

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Jepang (Tokyo)

POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Catatan

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.

PentingJika 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 object

Informasi output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.

message string

Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.

Respons sukses

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"
}

Respons error

Pembuatan tugas gagal. Lihat kode kesalahan.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Langkah 2: Kueri hasil berdasarkan ID tugas

Singapura

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

AS (Virginia)

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Jerman (Frankfurt)

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

China (Hong Kong)

GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}

Jepang (Tokyo)

GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Catatan

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

outputobject

Informasi output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status 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 string

Waktu saat tugas dikirimkan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

Waktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

end_time string

Waktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

video_url string

URL video yang dihasilkan. Hanya dikembalikan ketika task_status bernilai SUCCEEDED.

Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.

orig_prompt string

Prompt input asli, sesuai dengan parameter permintaan prompt.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.

message string

Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat kode kesalahan.

usage object

Statistik output. Hanya tugas yang berhasil yang dihitung.

Properti

input_video_duration integer

Durasi video input dalam detik.

output_video_duration integer

Durasi video output dalam detik.

duration integer

Total durasi video untuk penagihan.

SR integer

Resolusi video output.

ratio string

Rasio aspek video output.

video_count integer

Jumlah video output. Selalu bernilai 1.

request_id string

Identifier permintaan unik untuk pelacakan dan troubleshooting.

Tugas berhasil

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"
    }
}

Tugas gagal

Saat tugas gagal, task_status bernilai FAILED dengan kode dan pesan kesalahan. Lihat kode kesalahan.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The parameter is invalid."
    }
}

Kueri tugas kedaluwarsa

task_id berlaku selama 24 jam. Setelah periode ini, kueri akan mengembalikan kesalahan berikut.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

Kode kesalahan

Panggilan API yang gagal mengembalikan kode kesalahan yang didokumentasikan di Pesan kesalahan.