API tạo video

Cách tạo video qua /videos: tạo tác vụ, theo dõi, tải tệp. Các trường request, tệp tham chiếu, bản nháp và cách tính tiền video.

Video

Model video chạy dạng tác vụ. POST /videos tạo tác vụ và trả về id ngay; gọi GET /videos/{id} vài giây một lần đến khi status là completed hoặc failed (thường 1 đến 5 phút), rồi tải về: tác vụ hoàn tất có trường url (liên kết tới tệp, hiệu lực một tuần và được làm mới mỗi lần đọc; nếu chúng tôi chưa lưu được tệp thì url là đường dẫn /v1/videos/{id}/content), và GET /videos/{id}/content luôn trả về tệp đó. Trường id của mọi phản hồi (chatcmpl-…, img_…, video_…) và request_id trong lỗi là thông tin cần gửi cho hỗ trợ.

TrườngKiểu
modelstringBắt buộc. Id của model video.
promptstringBắt buộc (trừ khi dùng draft_id). 3 đến 20.000 ký tự.
secondsinteger | "auto"Độ dài (duration cũng được nhận như cùng trường). Seedance 2.5: 4 đến 30; Seedance 2.0: 4 đến 15. "auto" để model tự chọn; giữ tạm theo độ dài tối đa và tính theo độ dài thực tế. Mặc định 5; khi có reference_videos thì mặc định là "auto".
resolutionstring480p, 720p (mặc định), 1080p hoặc 4k; chỉ những độ phân giải model hỗ trợ (xem danh sách model).
ratiostring16:9 (mặc định), 9:16, 1:1, 4:3, 3:4, 21:9 hoặc adaptive. Khi có reference_videos thì mặc định theo video đầu vào.
imagestringKhung đầu: link ảnh hoặc data URL (first_frame cũng được nhận như cùng trường).
last_framestringKhung cuối, dùng cùng với image.
audiobooleanTạo âm thanh cho video. Mặc định true.
seedinteger-1 là seed ngẫu nhiên (mặc định), hoặc một số nguyên từ 1 đến 4294967295 để lặp lại kết quả trên cùng model. Kết quả trả về seed bạn gửi, hoặc -1 khi là ngẫu nhiên.
camera_fixedbooleantrue giữ máy quay cố định.
bitrate_modestringstandard (mặc định) hoặc high. high có thể lỗi khi model quá tải; khi đó được hoàn tiền.
return_last_framebooleantrue: khung cuối được lưu dạng ảnh tại GET /videos/{id}/last_frame.
reference_imagesstring[]Link ảnh hoặc data URL: tối đa 30 với Seedance 2.5, 9 với Seedance 2.0 (jpeg, png, webp, bmp, tiff, gif; tối đa 30 MB; mỗi cạnh 300 đến 6000 px).
reference_videosstring[]Link MP4/MOV công khai: tối đa 10 với Seedance 2.5, 3 với Seedance 2.0; mỗi video 2 đến 15 giây, 480p hoặc 720p, tối đa 50 MB. Độ dài của chúng cũng được tính phí.
reference_audiosstring[]Link WAV/MP3 công khai: tối đa 10 với Seedance 2.5, 3 với Seedance 2.0; mỗi file 2 đến 15 giây, tối đa 15 MB.
task_typestringKhi có reference_videos: auto, reference, edit hoặc extend (Seedance 2.5). edit và extend theo video đầu vào; không gửi seconds và ratio.
draftbooleanSeedance 2.5: true tạo bản xem trước 480p với giá 480p. resolution phải là 480p.
draft_idstringTạo video chính thức 1080p từ bản nháp đã xong. Chỉ gửi model và draft_id: prompt, tham chiếu, độ dài, tỉ lệ, âm thanh và seed lấy từ bản nháp. Bản nháp dùng được 7 ngày.

File tham chiếu được đánh số theo từng loại, theo thứ tự bạn gửi: phần tử đầu của reference_images là ảnh 1, phần tử thứ hai là ảnh 2, video và âm thanh cũng vậy. Hãy gọi chúng như thế trong prompt, giống playground dùng [Image 1], [Video 1] và [Audio 1], ví dụ "The woman in [Image 1] walks through the street of [Video 1]". Gửi nhiều file hơn mức model nhận sẽ bị từ chối, không tự cắt bớt.

status là queued, in_progress, completed hoặc failed. Tác vụ hoàn tất có usage.video_tokens và usage.cost_usd; tác vụ lỗi không bị tính tiền và có error.code cùng error.message: generation_failed (model không tạo được video), invalid_reference (một file tham chiếu bị từ chối; thông báo nêu rõ file nào) hoặc timeout.

// GET https://api.apistore.cloud/v1/videos/video_...
{
  "id": "video_0123456789abcdef0123456789abcdef",
  "object": "video",
  "model": "MODEL_NAME",
  "status": "completed",
  "created_at": 1793984023,
  "completed_at": 1793984214,
  "prompt": "A red paper boat drifting across a calm lake at sunrise",
  "resolution": "720p",
  "ratio": "16:9",
  "seconds": 5,
  "draft": false,
  "seed": 49873,
  "url": "https://.../video_0123456789abcdef0123456789abcdef.mp4",
  "last_frame": null,
  "error": null,
  "usage": { "video_tokens": 108000, "cost_usd": 1.0978 }
}

Bản nháp (Seedance 2.5): tạo bản xem trước 480p giá rẻ trước, rồi chuyển bản ưng ý thành video chính thức 1080p với cùng seed và thiết lập.

# 1. the draft: 480p, at the 480p price
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "prompt": "A red paper boat on a lake", "seconds": 5, "resolution": "480p", "draft": true}'

# 2. when it is completed, the final video at 1080p
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "draft_id": "video_..."}'

Khi tác vụ bắt đầu, số dư bị giữ tạm chi phí ước tính: token video của (số giây video đầu vào + số giây đầu ra) theo giá của độ phân giải đó. Khi xong, bạn trả theo token thực tạo (khoảng 108K cho 5 giây 720p), phần còn lại được trả về; tác vụ lỗi không mất tiền. Trong Cài đặt bạn có thể chuyển cách tính video từ bảng giá token sang "theo USD": phí nhà cung cấp thu cho job theo giá niêm yết, trừ chiết khấu của bạn. Mỗi bản ghi tính tiền ghi rõ cách nào đã áp dụng.

Hướng dẫn theo model

Mỗi dòng model video mạnh ở đâu, giới hạn thế nào, và cách viết prompt để model làm đúng ý.

Seedance 2.5

Model cho video dài: tối đa 30 giây trong một tác vụ, nhận nhiều file tham chiếu, sửa hoặc nối dài video có sẵn. Viết và nói được 11 ngôn ngữ, trong đó có tiếng Việt và tiếng Anh.

Tóm tắt
Độ dài4 đến 30 giây, hoặc "auto" để model tự chọn
Độ phân giải480p, 720p, 1080p
Tỉ lệ21:9, 16:9, 4:3, 1:1, 3:4, 9:16 hoặc adaptive (theo file đầu vào)
Chế độVăn bản thành video; khung đầu hoặc khung đầu và khung cuối; tham chiếu; sửa video; nối dài video
Tham chiếuTối đa 30 ảnh, 10 video và 10 audio. Chấp nhận chỉ gửi audio
Âm thanhLời thoại, nhạc và hiệu ứng được tạo cùng hình (audio: true)
Bản nhápCó: xem trước 480p, rồi tạo video chính thức từ bản ưng ý

Cách viết prompt

  • Mở đầu bằng một câu. Nói ai, ở đâu, chuyện gì xảy ra, phong cách và máy quay trong một dòng. Chi tiết viết bên dưới.
  • Gắn từng file tham chiếu. Gọi mỗi file theo số và nói nó dùng để làm gì: "[Image 1] là nữ chính, [Image 2] là quán cà phê, máy quay theo [Video 1]". Đừng dựa vào chữ viết trong ảnh để chỉ ra ai là ai.
  • Dùng dòng thời gian cho video dài. Chia câu chuyện thành các khoảng giây tròn, liền nhau ("0-5 s", "5-12 s") hoặc các cảnh đánh số, mỗi phần ghi hình ảnh, máy quay, hành động, lời thoại và âm thanh. Quá ít nội dung thì model tự thêm; quá nhiều thì cắt cảnh liên tục.
  • Ít nhân vật. Một đến năm nhân vật là ổn định nhất. Đến năm nhân vật có thể gửi nhiều góc của cùng một người; nhiều hơn thì mỗi người một góc.
  • Sửa video (task_type: edit). Nói sửa gì, ở đâu, từ gì thành gì, kèm số giây nếu chỉ sửa một đoạn: "Trong [Video 1], từ giây 4 đến 6 cô ấy vẫy tay thay vì gật đầu; phần còn lại giữ nguyên". Kết quả giữ độ dài và tỉ lệ của video gốc nên không gửi seconds và ratio. Video dưới 20 giây sửa tốt nhất.
  • Nối dài (task_type: extend). Nói hướng nối và chuyện tiếp theo: "Nối dài [Video 1] về phía sau: cô ấy mở cửa và bước ra mưa". Tỉ lệ theo video gốc.
  • Khung đầu và khung cuối. Gửi bằng image và last_frame, cùng tỉ lệ, để video bắt đầu và kết thúc đúng ở đó. Ảnh tham chiếu được gọi là "khung đầu" trong prompt thì model bám kém chặt hơn.
  • Storyboard và keyframe. Một tấm storyboard (tối đa 15 ô, nét vẽ đơn giản, không có chữ) định hướng cốt truyện nhưng không được bám từng ô. Muốn bám chặt, gửi từng ảnh riêng và mở đầu bằng "Dùng Image 1 đến 5 theo thứ tự làm keyframe".
  • Máy quay. Thuật ngữ điện ảnh thông dụng dùng trực tiếp được: đẩy vào, lia, bám theo, quay vòng, cầm tay, góc thấp, cú máy dài. Thuật ngữ hiếm thì giải thích vài chữ; với chuyển cảnh, ghi cả thời điểm và cách chuyển.
  • Điều không muốn. Nên viết điều bạn muốn thay vì điều không muốn. Hai ngoại lệ dùng tốt: "Không phụ đề" và "Không nhạc nền, chỉ âm thanh môi trường".
  • Lời thoại. Viết theo dạng: tên, cảm xúc trong ngoặc, rồi câu nói. Mỗi câu một ngôn ngữ. Chữ cần hiện chính xác trên màn hình thì gửi dưới dạng ảnh.
Prompt mẫu
[Image 1] là người đánh cá, [Image 2] là chiếc thuyền. Phong cách phim tài liệu, ánh sáng tự nhiên.
0-6 s: toàn cảnh sát mặt nước, thuyền trôi trong sương sớm. Máy đẩy vào chậm.
6-14 s: trung cảnh, ông kéo lưới lên, từng nhịp tay. Nước nhỏ giọt từ sợi dây.
14-20 s: cận cảnh khuôn mặt, ông nhìn mẻ cá và mỉm cười.
Chỉ âm thanh môi trường: nước, gỗ, chim biển. Không phụ đề, không nhạc nền.

Seedance 2.0

Ba model nhận cùng một kiểu request, khác nhau về chất lượng, tốc độ và giá: Seedance 2.0 cho hình ảnh đẹp nhất, Seedance 2.0 fast cân bằng tốc độ và chi phí, Seedance 2.0 mini giá thấp nhất.

Tóm tắt
Độ dài4 đến 15 giây, hoặc "auto"
Độ phân giảiSeedance 2.0: 480p, 720p, 1080p, 4K. Fast và mini: 480p, 720p
Tỉ lệ21:9, 16:9, 4:3, 1:1, 3:4, 9:16
Chế độVăn bản thành video; khung đầu hoặc khung đầu và khung cuối; tham chiếu; sửa hoặc nối dài video qua prompt
Tham chiếuTối đa 9 ảnh, 3 video và 3 audio. Audio phải đi kèm ảnh hoặc video
Âm thanhLời thoại, nhạc và hiệu ứng được tạo cùng hình (audio: true)
Bản nhápKhông
File 4KH.265, màu 10-bit. Một số trình phát không mở được; VLC và Chrome, Edge, Safari bản mới mở được
Khuôn mặtẢnh và video tham chiếu có khuôn mặt người thật sẽ bị từ chối

Cách viết prompt

  • Công thức. Chủ thể, hành động, bối cảnh, ánh sáng và màu, máy quay, phong cách, chất lượng, rồi điều cần tránh. Chốt ai làm gì trước, sau đó ở đâu, rồi quay thế nào.
  • Định nghĩa mỗi chủ thể một lần. Cho hai ba đặc điểm cố định (quần áo, tóc, dáng người) và một tên gọi, rồi luôn dùng đúng tên đó: "Cô gái áo khoác đỏ trong [Image 1]".
  • Viết theo cảnh, không theo giây. Đánh số cảnh: "Cảnh 1: ... Cảnh 2: ...", mỗi cảnh ghi máy quay, hành động, vị trí và âm thanh. Mốc giây chính xác như "0-3 s" không được model này giữ ổn định.
  • Mỗi cảnh một chuyển động máy. Đẩy vào, hoặc lia, hoặc bám theo. Gộp nhiều chuyển động trong một cảnh làm kết quả kém ổn định.
  • Tả chuyển động cụ thể. Nêu bộ phận cơ thể, biên độ, tốc độ. Chuyển động chậm và liên tục cho kết quả tốt nhất. Thể hiện cảm xúc qua cơ thể ("cúi đầu, mắt đỏ lên") thay vì gọi tên cảm xúc.
  • Dùng ít tham chiếu. Bốn năm file là đủ: một hai file cho nhân vật, một cho bối cảnh, một video cho máy quay, một audio cho không khí. Hơn bốn người làm tham chiếu thì kém ổn định, và không nên gửi nhiều góc của cùng một người.
  • Giữ đúng khuôn mặt. Gửi một ảnh cận mặt và một ảnh toàn thân, nói rõ ảnh nào cho khuôn mặt, ảnh nào cho trang phục. Đặt file quan trọng nhất lên đầu.
  • Sửa video. Gọi thẳng tên video và nói sửa gì: "Sửa đúng [Video 1]: thay con mèo bằng con sư tử trong [Image 1], giữ nguyên phần còn lại". Đừng viết "tham chiếu [Video 1]" ở đây, nếu không video chỉ được dùng làm tham chiếu.
  • Nối dài. "Nối dài [Video 1] về phía sau" hoặc "về phía trước", rồi chuyện gì xảy ra. Có thể ghép hai ba đoạn với chuyển cảnh ở giữa, tổng cộng 15 giây. Thêm "kết thúc bằng [Video 1]" để giữ cảnh gốc trong kết quả.
  • Lời thoại và chữ. Đặt câu nói trong ngoặc nhọn và dùng một ngôn ngữ xuyên suốt: Cô ấy nói {Mình trễ rồi}. Với chữ trên màn hình, ghi nội dung, thời điểm, vị trí và cách xuất hiện. Dùng ký tự thông dụng.
  • Điều cần tránh. Phụ đề và logo vẫn có thể xuất hiện. "Không phụ đề" và "Không tạo logo hay watermark" giúp giảm; xóa chữ khỏi file tham chiếu cũng vậy.
Prompt mẫu
[Image 1] là cô gái áo khoác đỏ, [Image 2] là chợ đêm. Máy quay theo [Video 1].
Cảnh 1: toàn cảnh, cô bước vào giữa các gian hàng. Máy đẩy vào chậm.
Cảnh 2: trung cảnh, cô dừng ở gian đèn lồng và nhấc một chiếc lên. Máy cố định.
Cảnh 3: cận cảnh, ánh sáng ấm trên khuôn mặt. Cô nói {Cái này}.
Chất điện ảnh, tông ấm, nhiều chi tiết. Không phụ đề. Không tạo logo hay watermark.