Video API Seedance chuyển tiếp chính thức

Trang này mô tả cách gọi các model video Seedance chuyển tiếp chính thức. Giống các model video khác, chúng được tạo bằng POST /v1/videos và truy vấn bằng GET /v1/videos/{id}; xác thực, tải lên tư liệu, trạng thái truy vấn định kỳ, tải kết quả và xử lý lỗi xem Quy chuẩn gọi Video API đầy đủ. Trang này chỉ trình bày các trường và quy tắc riêng của nhóm model này.

Cập nhật ngày 2026-10-13. Các model này chuyển tiếp API Seedance chính thức của Volcengine và là nhóm model khác với Seedance bản chính thức và SD bản đám mây; tham số và khả năng không dùng thay thế cho nhau được. Các model này không hỗ trợ callback_url: yêu cầu có callback_url không rỗng sẽ trả về 400, không tạo tác vụ và không bị trừ phí (chuỗi rỗng được coi như không truyền); hãy lấy kết quả bằng cách truy vấn định kỳ GET /v1/videos/{id}.

Model

Bảng dưới đây liệt kê ID model của nhóm này. Các ID chỉ hiển thị với API Key đã bật nhóm tương ứng; nếu chưa bật, GET /v1/models sẽ không trả về chúng.

Các ID model trước đây doubao-seedance-2-0-mini-260615, doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-5-260628 vẫn gọi được và hoàn toàn giống model cùng tên trong bảng trên; chúng không còn hiển thị trong quảng trường model, tích hợp mới hãy dùng ID trong bảng trên.

Quy tắc chung

• Độ phân giải: resolution chọn độ phân giải đầu ra trong phạm vi của bảng trên (không phân biệt hoa thường, ví dụ 720p, 4k); mặc định 720p.
• Thời lượng: số giây nguyên trong duration (hoặc seconds); -1 để model tự chọn thời lượng.
• Tỷ lệ khung hình: ratio (hoặc aspect_ratio) nhận 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive; mặc định adaptive (thích ứng theo tư liệu đầu vào). size cũng nhận tỷ lệ khung hình hoặc mức độ phân giải (ví dụ 16:9, 1080p); nếu mâu thuẫn với ratio, aspect_ratio hoặc resolution sẽ trả về 400.
• Prompt: có thể bỏ trống prompt khi có tư liệu tham chiếu hoặc khung hình đầu và cuối; nếu không có cả hai sẽ trả về 400.
• Tạo âm thanh: đặt generate_audio (boolean) là false để tắt âm thanh; mặc định video có âm thanh.
• Trường tùy chọn: watermark (boolean; khi là true sẽ thêm hình mờ “AI 生成” (do AI tạo) ở góc dưới bên phải, mặc định không thêm), priority (số nguyên 0–9, mức ưu tiên xếp hàng), return_last_frame (boolean, xem Khung hình cuối).
• Trường không hỗ trợ: seed, camera_fixed, frames, service_tier sẽ trả về 400; draft chỉ Seedance 2.5 hỗ trợ, xem Bản nháp và video chính thức.

Tính phí

Nhóm model này tính phí theo số Token đầu ra do nền tảng model trả về sau khi tác vụ hoàn tất, áp dụng mức đơn giá tương ứng với “độ phân giải × có video tham chiếu hay không”. Khi gửi yêu cầu sẽ không trừ trước phí; trong nhật ký sử dụng sẽ xuất hiện trước một bản ghi gửi “操作 …” (Thao tác …) với số tiền 0, sau khi tác vụ hoàn tất sẽ có thêm một bản ghi “任务用量表达式结算” (quyết toán theo biểu thức mức dùng của tác vụ) để trừ phí theo mức dùng thực tế.

Khi thời lượng do model quyết định (duration là -1, hoặc Seedance 2.5 không điền thời lượng), số giây trong bản ghi gửi là ước tính theo thời lượng tối đa, hiển thị là “seconds: 30（预估）” (ước tính); phí thực tế căn cứ theo bản ghi quyết toán. Tác vụ thất bại hoặc đã hủy không bị tính phí.

Tư liệu tham chiếu

• Ảnh tham chiếu đặt trong images, video tham chiếu đặt trong metadata.referenceVideos, âm thanh tham chiếu đặt trong metadata.referenceAudios.
• Cũng có thể dùng các trường số ít: image, input_reference làm ảnh tham chiếu, video làm video tham chiếu, audio làm âm thanh tham chiếu. Cùng một tư liệu điền ở nhiều trường chỉ được tính một lần.
• Mỗi phần tử có thể là chuỗi URL hoặc đối tượng { "url": "...", "role": "..." }.
• Ảnh nhận URL https:// công khai hoặc Data URI data:; âm thanh nhận URL https:// công khai hoặc Data URI data:.
• Video tham chiếu chỉ nhận URL https:// công khai, không nhận http://, data:, Base64 hay tệp cục bộ; với video cục bộ, hãy lấy URL trước theo Tải lên tư liệu cục bộ. Liên kết phải truy cập được mà không cần đăng nhập và còn hiệu lực cho đến khi tác vụ hoàn tất.
• Dòng 2.0 (Mini, 2.0, Fast) không nhận riêng âm thanh tham chiếu; cần kèm ảnh hoặc video tham chiếu.
• Khuyến nghị tổng thời lượng video tham chiếu và tổng thời lượng âm thanh tham chiếu mỗi loại không quá 15 giây với dòng 2.0, không quá 30 giây với 2.5; vượt quá có thể khiến tác vụ thất bại sau khi đã tạo.
• Cũng có thể dùng trực tiếp cách viết mảng content của Volcengine Ark (các mục nội dung text, image_url, video_url, audio_url; role của ảnh có thể là first_frame, last_frame hoặc reference_image), đặt ở cấp cao nhất hoặc trong metadata đều được.

{
  "model": "doubao-seedance-2.0",
  "prompt": "Người trong ảnh nhảy theo nhịp của âm thanh tham chiếu, động tác theo phong cách của video tham chiếu",
  "duration": 8,
  "resolution": "1080p",
  "ratio": "16:9",
  "images": ["https://cdn.example.com/dancer.jpg"],
  "metadata": {
    "referenceVideos": ["https://cdn.example.com/dance-motion.mp4"],
    "referenceAudios": ["https://cdn.example.com/music.mp3"]
  }
}

Thư viện chân dung ảo (chế độ nhập thư viện)

Mặc định, tư liệu tham chiếu được gửi thẳng tới API tạo video để kiểm duyệt. Bạn cũng có thể đưa tư liệu vào thư viện chân dung ảo trước, sau khi qua kiểm duyệt nhập thư viện mới dùng để tạo video:

• Với ảnh, đặt "image_source_mode": "asset"; với video tham chiếu, đặt "video_source_mode": "asset" (video vẫn phải là URL https:// công khai). Hai trường này có thể đặt ở cấp cao nhất hoặc trong metadata, độc lập với nhau.
• Ảnh cục bộ tải lên bằng multipart/form-data sẽ tự động được đưa vào thư viện chân dung ảo và gửi theo chế độ nhập thư viện, không cần thiết lập thêm, xem Tải tệp lên.
• Kiểm duyệt nhập thư viện chỉ kiểm tra tư liệu có dùng được hay không, không phải xác minh danh tính, nhận diện khuôn mặt hay xác thực người thật; hiện chưa cung cấp quy trình nhập thư viện có ủy quyền của người thật, ảnh người thật ở chế độ nhập thư viện cũng có thể không qua kiểm duyệt.
• Hiện chưa có chức năng quản lý tư liệu riêng (tải lên riêng, danh sách tư liệu, ID tư liệu); mỗi yêu cầu tạo video đều phải kèm tư liệu.

{
  "model": "doubao-seedance-2.5",
  "prompt": "Người trong ảnh 1 đeo chiếc vòng cổ ở ảnh 2, chậm rãi xoay người trong studio sáng sủa",
  "duration": 6,
  "resolution": "720p",
  "ratio": "9:16",
  "image_source_mode": "asset",
  "images": [
    { "url": "https://cdn.example.com/model.png", "role": "reference_image" },
    { "url": "https://cdn.example.com/necklace.png", "role": "reference_image" }
  ]
}

Nhiều ảnh tham chiếu được giữ theo thứ tự gửi; hãy ghi rõ trong prompt nội dung tương ứng với “ảnh 1”, “ảnh 2” để tránh nhầm lẫn người hoặc đồ vật.

Khung hình đầu và cuối

Khung hình đầu và khung hình cuối đặt trong metadata.firstFrame và metadata.lastFrame, được tính vào giới hạn ảnh.

• lastFrame phải đi kèm firstFrame.
• Khung hình đầu và cuối không thể dùng chung với ảnh, video hoặc âm thanh tham chiếu.
• Khi dùng khung hình đầu và cuối, Seedance 2.5 (đa độ phân giải) yêu cầu ratio là adaptive (hoặc không truyền).

{
  "model": "doubao-seedance-2.0-fast",
  "prompt": "Chuyển mượt từ quảng trường vắng lúc sáng sớm sang cùng bố cục vào ban đêm khi đèn bật sáng",
  "duration": 5,
  "resolution": "720p",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

Chỉnh sửa và kéo dài video với Seedance 2.5

Khi Seedance 2.5 (đa độ phân giải) nhận video tham chiếu, có thể dùng omni_reference_task_type để chọn loại tác vụ:

Ngoài ra có thể dùng output_format để chọn mp4 hoặc mov. Hai trường này chỉ áp dụng cho 2.5; dòng 2.0 sẽ trả về 400 nếu gửi chúng.

{
  "model": "doubao-seedance-2.5",
  "prompt": "Đổi cảnh ban ngày thành đêm mưa, giữ nguyên động tác của nhân vật",
  "omni_reference_task_type": "edit",
  "duration": -1,
  "ratio": "adaptive",
  "metadata": {
    "referenceVideos": ["https://cdn.example.com/source.mp4"]
  }
}

Bản nháp và video chính thức (Seedance 2.5)

Seedance 2.5 (đa độ phân giải) có thể tạo trước một bản nháp 480p chi phí thấp, sau khi xác nhận hiệu quả mới dựa trên bản nháp để tạo video chính thức 1080p. Các model khác không hỗ trợ bản nháp.

1. Tạo bản nháp: thêm "draft": true vào yêu cầu, đầu ra cố định 480p. Bản nháp không thể đồng thời đặt return_last_frame.
2. Chờ bản nháp thành công: truy vấn định kỳ GET /v1/videos/{id} như bình thường; khi trạng thái là completed thì xem bản nháp.
3. Tạo video chính thức: trong content chỉ đặt một mục draft_task, id điền id của tác vụ bản nháp (giá trị task_… trả về khi tạo bản nháp). Video chính thức cố định 1080p; prompt, tư liệu, thời lượng, tỷ lệ khung hình, âm thanh… đều kế thừa từ bản nháp, không truyền lại prompt, tư liệu, duration, ratio, generate_audio, omni_reference_task_type hoặc return_last_frame, nếu không sẽ trả về 400.

{
  "model": "doubao-seedance-2.5",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_REPLACE_WITH_YOUR_DRAFT_TASK_ID" } }
  ],
  "watermark": false
}

• Chỉ dùng được tác vụ bản nháp do chính tài khoản này tạo và đã thành công; hãy tạo video chính thức trong vòng 7 ngày sau khi tạo bản nháp.
• Bản nháp và video chính thức là hai tác vụ tính phí độc lập; video chính thức tính theo mức 1080p, nếu bản nháp có video tham chiếu thì video chính thức cũng tính theo mức có video tham chiếu.

Khung hình cuối

Đặt "return_last_frame": true trong yêu cầu; sau khi tác vụ thành công có thể lấy ảnh khung hình cuối cùng của video, dùng để quay tiếp hoặc làm khung hình đầu cho đoạn video tiếp theo:

curl https://api.88api.ai/v1/tasks/task_xxx/artifacts \
  -H "Authorization: Bearer sk-khoa-api-cua-ban"

Trong artifacts trả về, mục có key là last_frame chính là ảnh khung hình cuối; tải xuống theo content_url của mục đó (cũng kèm API Key). Khung hình cuối không được trả về trong phản hồi của GET /v1/videos/{id}. Định dạng ảnh căn cứ theo Content-Type của kết quả tải xuống, không đảm bảo là PNG.

Tìm kiếm web

Dòng Seedance 2.0 và 2.5 hỗ trợ tìm kiếm web qua tools, phù hợp với prompt cần thông tin thời gian thực:

{
  "model": "doubao-seedance-2.0",
  "prompt": "Dựa vào thời tiết hôm nay ở Thượng Hải, tạo một đoạn video cảnh phố Bến Thượng Hải",
  "duration": 5,
  "resolution": "720p",
  "tools": [{ "type": "web_search" }]
}

• tools chỉ hỗ trợ {"type": "web_search"}.
• Có thực sự tìm kiếm hay không do model quyết định dựa trên prompt; chỉ khi thực tế có tìm kiếm mới tính thêm phí theo số lần tìm kiếm (đơn giá xem phần giải thích giá trong bảng điều khiển), không tìm kiếm thì không thu thêm phí.

Hủy tác vụ

Khi tác vụ còn đang xếp hàng và chưa bắt đầu tạo, có thể hủy:

curl -X DELETE https://api.88api.ai/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-khoa-api-cua-ban"

• Hủy thành công sẽ trả về {"id": "task_xxx", "object": "video", "status": "cancelled", "cancelled": true}, sau đó tác vụ hiển thị là thất bại (lý do “任务已被用户取消” — tác vụ đã bị người dùng hủy), không bị tính phí.
• Tác vụ đã bắt đầu chuẩn bị hoặc đang tạo, hoặc đã kết thúc thì không thể hủy, sẽ trả về 409 task_not_cancellable; hãy tiếp tục truy vấn kết quả tác vụ.
• DELETE /v1/video/generations/{id} có tác dụng tương tự.

ID tác vụ chính thức

Sau khi Volcengine Ark tiếp nhận tác vụ, GET /v1/videos/{id} sẽ trả về official_task_id (ví dụ cgt-20261012120000-abcde), nhật ký tác vụ trong bảng điều khiển cũng hiển thị “官方任务 ID” (ID tác vụ chính thức). Khi cần đối chiếu vấn đề tạo video, hãy cung cấp cả id của tác vụ và ID tác vụ chính thức. Khi tác vụ còn đang xếp hàng, chưa được tiếp nhận thì không trả về trường này.

Tải tệp lên

Có thể tải ảnh cục bộ trực tiếp bằng multipart/form-data, hỗ trợ nhiều ảnh: tải lên lặp lại với cùng một tên trường (ví dụ image), theo thứ tự gửi sẽ tương ứng với “ảnh 1”, “ảnh 2”. Ảnh tải lên sẽ tự động được đưa vào thư viện chân dung ảo và gửi theo chế độ nhập thư viện.

curl https://api.88api.ai/v1/videos \
  -H "Authorization: Bearer sk-khoa-api-cua-ban" \
  -F model=doubao-seedance-2.5 \
  -F "prompt=Người trong ảnh 1 đeo chiếc vòng cổ ở ảnh 2, chậm rãi xoay người" \
  -F duration=6 \
  -F resolution=720p \
  -F "image=@./model.png" \
  -F "image=@./necklace.png"

• Khi dùng tệp cục bộ, không được đồng thời gửi ảnh trong images, image, input_reference hoặc content.
• Mỗi tệp không quá 64 MB, toàn bộ yêu cầu không quá 128 MB.
• Video và âm thanh cục bộ không thể tải trực tiếp bằng multipart/form-data: hãy lấy URL https:// trước theo Tải lên tư liệu cục bộ, rồi điền vào trường video tham chiếu hoặc âm thanh tham chiếu; âm thanh tham chiếu cũng có thể dùng Data URI data:.