API Tạo Video Seedance 2.0 Fast

Tham số Seedance 2.0 Fast, phương tiện tham chiếu, tác vụ không đồng bộ, tải xuống có xác thực và tính phí theo thời lượng trên APIMaster.

Tạo video Seedance 2.0 Fast

Sử dụng seedance-2.0-fast để tạo văn bản thành video, hình ảnh thành video, tạo khung hình đầu/cuối và tham chiếu video hoặc âm thanh. Fast hỗ trợ 480p và 720p, với thời lượng đầu ra từ 4 đến 15 giây.

Để tạo khung hình đầu/cuối, hãy đặt rõ ràng aspect_ratio: "adaptive". Âm thanh tham chiếu phải đi kèm với một hình ảnh hoặc video. Hãy giữ khóa API APIMaster của bạn trên máy chủ của bạn.

Điểm cuối và xác thực

URL cơ sở: https://apimaster.ai/v1. Gửi Authorization: Bearer YOUR_API_KEY khi gửi, truy vấn và tải xuống.

Hoạt động	Phương thức và đường dẫn
Tạo video	`POST /v1/videos/generations`
Truy vấn kết quả tương thích	`GET /v1/video/generations/{task_id}`
Truy vấn kết quả kiểu OpenAI	`GET /v1/videos/{task_id}`
Tải xuống video	`GET /v1/videos/{task_id}/content`
Tải xuống khung hình cuối được yêu cầu	`GET /v1/videos/{task_id}/last-frame`

Sử dụng task_id công khai được APIMaster trả về. Tác vụ video và tác vụ xem xét phương tiện là các tài nguyên khác nhau: sử dụng các điểm cuối truy vấn video ở trên cho video. Một yêu cầu được chấp nhận sẽ tạo ra một tác vụ không đồng bộ; thành công HTTP không có nghĩa là video đã hoàn thành.

Tham số

Trường	Kiểu	Bắt buộc / Mặc định	Mô tả
`model`	chuỗi	Bắt buộc	`seedance-2.0-fast`
`prompt`	chuỗi	Bắt buộc	Tối đa `4000` ký tự. Mô tả chủ thể, chuyển động, cảnh, máy ảnh và âm thanh mong muốn; lời nhắc ngắn gọn dễ kiểm soát hơn.
`duration`	số nguyên	`5`	Độ dài đầu ra, `4`–`15` giây. `-1` không được hỗ trợ.
`resolution`	chuỗi	`720p`	`480p` hoặc `720p`; `1080p` và `4k` không được hỗ trợ.
`aspect_ratio`	chuỗi	`16:9`	`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, hoặc `adaptive`.
`ratio`	chuỗi	Giống với `aspect_ratio`	Bí danh APIMaster. Nếu cả hai xuất hiện, giá trị của chúng phải khớp nhau.
`size`	chuỗi	Giống với `aspect_ratio`	Một tỷ lệ như `16:9` hoặc `adaptive`. Ưu tiên `aspect_ratio` và `resolution` để biểu thị hai kích thước riêng biệt. Các thông số mâu thuẫn sẽ trả về `400`.
`seed`	số nguyên	Bỏ qua	Kiểm soát biến thể; các hạt giống khớp nhau không đảm bảo đầu ra giống hệt nhau.
`generate_audio`	boolean	`true`	Tạo âm thanh đi kèm; sử dụng `false` để đầu ra im lặng.
`image_urls`	mảng chuỗi	Bỏ qua	Tối đa `9` hình ảnh tham chiếu. URL hình ảnh công khai hoặc ID `asset://` APIMaster đã được phê duyệt.
`image_with_roles`	mảng đối tượng	Bỏ qua	Các đối tượng hình ảnh với `url` và `role`; không thể xuất hiện cùng với `image_urls`. Xem quy tắc vai trò bên dưới.
`video_urls`	mảng chuỗi	Bỏ qua	Tối đa `3` video tham chiếu, với tổng thời lượng đầu vào có thể tính phí tối đa `15` giây. Xem yêu cầu về tài liệu.
`audio_urls`	mảng chuỗi	Bỏ qua	Tối đa `3` tệp âm thanh tham chiếu, tổng thời lượng kết hợp tối đa `15` giây. Yêu cầu có hình ảnh hoặc video tham chiếu.
`return_last_frame`	boolean	`false`	Khi hoàn thành thành công, trả về một URL tải xuống khung hình cuối APIMaster có xác thực khi kết quả bao gồm một khung hình cuối.
`nsfw_check`	boolean	`false`	Yêu cầu kiểm duyệt nội dung văn bản/hình ảnh trước khi tạo. Video và âm thanh không được bao gồm trong lượt kiểm duyệt này.
`tools`	mảng đối tượng	Bỏ qua	Khai báo công cụ tìm kiếm: `[{"type":"web_search"}]`.

Việc tạo bản nháp và nâng cấp bản nháp chỉ dành riêng cho Seedance 2.5. Không truyền draft: true hoặc draft_task_id cho mô hình này.

Tài liệu tham khảo

Cung cấp các URL HTTPS có thể truy cập công khai hoặc các ID đã được phê duyệt từ thư viện phương tiện APIMaster của bạn. Các tệp đằng sau trang đăng nhập hoặc yêu cầu tiêu đề ủy quyền riêng của bạn không thể được tải xuống. Việc tải lên hình ảnh thành công không ngụ ý nội dung được phê duyệt hoặc tuân thủ mọi yêu cầu của mô hình.

Tài liệu	Yêu cầu
Hình ảnh tham khảo	Tối đa `9`; sử dụng hình ảnh JPEG/PNG RGB dễ đọc. Điểm cuối tải lên hình ảnh APIMaster có giới hạn riêng là `20 MiB` và chấp nhận JPEG, PNG, GIF và WebP.
Video tham khảo	Tối đa `3`; video MP4/MOV, H.264/H.265; âm thanh AAC/MP3 khi có. Sử dụng video tham khảo từ `480p` đến `720p`. Tổng thời lượng tham khảo phải nằm trong `15` giây tính phí. APIMaster xác minh thời lượng MP4/MOV có thể truy cập trước khi tính phí; thời lượng clip đầu vào được làm tròn lên đến giây nguyên cho việc kiểm tra và tính phí này.
Âm thanh tham khảo	Tối đa `3`; WAV hoặc MP3, tối đa `20 MB` mỗi tệp, tổng thời lượng tối đa `15` giây. Luôn đi kèm với một hình ảnh hoặc video tham khảo.

Sử dụng hình ảnh rõ ràng với đủ chi tiết, tránh các tệp bị hỏng hoặc không đầy đủ, và giữ cho chuyển động trong video tham khảo phù hợp với lời nhắc của bạn. Phương tiện có thể không vượt qua được bài đánh giá định dạng hoặc nội dung không đồng bộ ngay cả khi bài nộp được chấp nhận.

Vai trò hình ảnh

`role`	Ý nghĩa
`first_frame`	Khung hình bắt đầu; tối đa một
`last_frame`	Khung hình kết thúc; tối đa một và yêu cầu có một khung hình đầu tiên
`reference_image`	Hình ảnh tham khảo, bao gồm tài nguyên nhân vật đã được phê duyệt

Đối với các tác vụ khung đầu tiên/cuối cùng, đặt aspect_ratio thành adaptive và bỏ qua video_urls và audio_urls. Sử dụng image_with_roles cho các vai trò rõ ràng; không đồng thời truyền image_urls.

{
  "model": "seedance-2.0-fast",
  "prompt": "A paper boat drifts gently from the starting composition to the ending composition",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "image_with_roles": [
    {"url": "https://your-storage.example/start.png", "role": "first_frame"},
    {"url": "https://your-storage.example/end.png", "role": "last_frame"}
  ],
  "generate_audio": false
}

Tải lên và thư viện phương tiện

Tải lên một hình ảnh cục bộ với POST /v1/uploads/images bằng cách sử dụng trường multipart file và ủy quyền Bearer. url cấp cao nhất được trả về có thể được sử dụng làm đầu vào hình ảnh công khai.

curl "https://apimaster.ai/v1/uploads/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@reference.png"

Đối với tài liệu có thể tái sử dụng hoặc nhân vật, hãy tạo một nhóm với POST /v1/seedance2/private-avatar/groups, gửi tài liệu với POST /v1/seedance2/private-avatar/assets, truy vấn đánh giá với GET /v1/tasks/{asset_task_id} và chỉ sử dụng các tài sản Active làm asset://{asset_id}. Các tài nguyên này thuộc về tài khoản của bạn. Chỉ định rõ ràng model: "seedance-2.0-fast". ID tài sản từ nền tảng hoặc tài khoản khác không thể được sử dụng ở đây.

Xem quy trình làm việc thư viện phương tiện để biết về việc tạo, gửi, đánh giá, lỗi một phần và xóa. Các điểm cuối tải lên và quản lý tài sản được chia sẻ; các giới hạn tạo trên trang này áp dụng cho Fast. Một đánh giá thất bại có thể không trả về lý do chi tiết; hãy sử dụng tài liệu rõ ràng, tuân thủ trong định dạng được hỗ trợ và gửi một đánh giá mới. Không tạo lại nhiều lần một tác vụ trong khi một đánh giá hiện có vẫn đang được xử lý.

Gửi một video

curl "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.0-fast",
    "prompt":"A small paper boat on calm water at sunrise, gentle tracking shot",
    "duration":5,
    "resolution":"720p",
    "aspect_ratio":"16:9",
    "generate_audio":true,
    "return_last_frame":true
  }'

Phản hồi tạo:

{"code":200,"data":[{"status":"submitted","task_id":"task_PUBLIC_VIDEO_ID"}]}

Thời gian chờ gửi là không rõ ràng: yêu cầu có thể đã được chấp nhận. Kiểm tra lịch sử tác vụ của bạn trước khi gửi lại; một lần gửi thành công khác sẽ tạo ra một tác vụ tính phí riêng biệt.

Video và âm thanh tham khảo

{
  "model": "seedance-2.0-fast",
  "prompt": "Follow the reference motion and keep the scene consistent with the image",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "image_urls": ["https://your-storage.example/reference.png"],
  "video_urls": ["https://your-storage.example/reference.mp4"],
  "audio_urls": ["https://your-storage.example/reference.mp3"],
  "generate_audio": true
}

Truy vấn và tải xuống

Thăm dò mỗi 3–5 giây. Dừng lại khi thành công hoặc thất bại.

curl "https://apimaster.ai/v1/video/generations/task_PUBLIC_VIDEO_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Truy vấn thành công tương thích:

{
  "code":"success",
  "message":"",
  "data":{
    "error":null,
    "format":"mp4",
    "metadata":null,
    "status":"succeeded",
    "task_id":"task_PUBLIC_VIDEO_ID",
    "url":"https://apimaster.ai/v1/videos/task_PUBLIC_VIDEO_ID/content",
    "actual_time":118,
    "last_frame_url":"https://apimaster.ai/v1/videos/task_PUBLIC_VIDEO_ID/last-frame"
  }
}

Ví dụ bao gồm các trường hoàn thành tùy chọn. actual_time là thời gian trôi qua từ lúc gửi đến khi hoàn thành tính bằng giây, không phải thời lượng video tính phí. last_frame_url bị bỏ qua nếu khung hình cuối cùng không được yêu cầu hoặc không có sẵn. Các tác vụ thất bại không bao gồm các trường thời gian trôi qua hoặc khung hình cuối chỉ dành cho thành công.

Truy vấn kiểu OpenAI:

curl "https://apimaster.ai/v1/videos/task_PUBLIC_VIDEO_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ý nghĩa	`data.status` Tương thích	`status` Kiểu OpenAI
Đang chờ	`queued`	`queued`
Đang tạo	`processing`	`in_progress`
Thành công	`succeeded`	`completed`
Thất bại	`failed`	`failed`

Đối tượng theo phong cách OpenAI sử dụng id cho ID tác vụ công khai và url cho URL tải xuống video. Các trường tùy chọn actual_time và last_frame_url xuất hiện ở cấp cao nhất. Khi thất bại, hãy đọc error.message trong đối tượng kết quả tương ứng. Các phản hồi không bao gồm các trường tiền tệ.

Tải xuống bằng khóa API của cùng tài khoản. Chỉ mở một URL kết quả mà không có ủy quyền là không đủ. Hãy lưu đầu ra ngay lập tức.

curl -L "https://apimaster.ai/v1/videos/task_PUBLIC_VIDEO_ID/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o output.mp4
curl -L "https://apimaster.ai/v1/videos/task_PUBLIC_VIDEO_ID/last-frame" \
  -H "Authorization: Bearer YOUR_API_KEY" -o last-frame.jpg

Quy trình làm việc đầy đủ bằng Python

import os
import time
import requests

base = "https://apimaster.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['APIMASTER_API_KEY']}"}
response = requests.post(base + "/videos/generations", headers=headers, json={
    "model": "seedance-2.0-fast",
    "prompt": "A small paper boat on calm water at sunrise",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": True,
    "return_last_frame": True,
}, timeout=90)
response.raise_for_status()
task_id = response.json()["data"][0]["task_id"]
for _ in range(240):
    response = requests.get(base + "/video/generations/" + task_id,
                            headers=headers, timeout=30)
    response.raise_for_status()
    task = response.json()["data"]
    if task["status"] == "failed":
        raise RuntimeError((task.get("error") or {}).get("message", "Video failed"))
    if task["status"] == "succeeded":
        print("Elapsed seconds:", task.get("actual_time"))
        for field, filename in [("url", "output.mp4"), ("last_frame_url", "last-frame.jpg")]:
            if task.get(field):
                with requests.get(task[field], headers=headers, stream=True, timeout=120) as result:
                    result.raise_for_status()
                    with open(filename, "wb") as out:
                        for chunk in result.iter_content(1024 * 1024):
                            out.write(chunk)
        break
    time.sleep(5)
else:
    raise TimeoutError("Task still processing; query the same task_id later")

Tính phí theo thời lượng

Có bốn hạng mức: 480P, 720P, 480P-input, và 720P-input. Một hạng mức được gắn nhãn "uploaded videos" có nghĩa là yêu cầu chứa đầu vào video tham chiếu. Hãy chọn hạng mức đầu vào cho độ phân giải đầu ra được yêu cầu ngay cả khi cũng có mặt các tham chiếu hình ảnh/âm thanh.

Không có video tham chiếu: giây video được tạo × đơn giá đơn vị tương ứng của độ phân giải đó.
Có video tham chiếu: (tổng giây video tham chiếu + giây video được tạo) × đơn giá đơn vị của hạng mức đầu vào tương ứng.
Đơn giá đơn vị cơ sở được cấu hình sẽ được nhân với các hệ số kênh và tài khoản/nhóm áp dụng để có được đơn giá đơn vị cuối cùng của bạn. Kiểm tra thẻ mô hình và hồ sơ tiêu thụ ví của bạn để biết giá áp dụng.

Ví dụ, một video tham chiếu 4 giây và đầu ra 5 giây sử dụng 9 giây tính phí ở hạng mức đầu vào. Đơn giá đơn vị của hạng mức đầu vào có thể khác với hạng mức thông thường; không chỉ tính thời lượng đầu ra hoặc áp dụng hạng mức thông thường cho các video tham chiếu. Hình ảnh và âm thanh không cộng thêm giây video tham chiếu. Âm thanh được tạo ra không tạo ra một hạng mức âm thanh/im lặng riêng biệt cho bốn mức giá được cấu hình này.

Việc gửi yêu cầu sẽ tạm giữ thời lượng đầu ra được yêu cầu, cộng với thời lượng video đầu vào đã được xác minh khi có mặt. Thời lượng đầu ra bị bỏ qua sẽ tạm giữ 5 giây đầu ra. Tác vụ giữ nguyên biểu giá tại thời điểm gửi; việc hoàn thành sẽ điều chỉnh theo thời lượng thực tế. Tạo video thất bại sẽ hoàn lại phí cho tác vụ video.

Lỗi và khắc phục sự cố

Các yêu cầu không hợp lệ sẽ trả về lỗi HTTP. Hãy đọc thông báo lỗi JSON cũng như mã trạng thái. Việc xác thực tham số sử dụng trình bao bọc lỗi của APIMaster, ví dụ:

{"code":"invalid_request","message":"First/last-frame tasks require adaptive aspect_ratio","data":null}

Vấn đề	Hành động
Độ phân giải / thời lượng không được hỗ trợ	Chọn `480p` hoặc `720p`, và một thời lượng số nguyên từ `4` đến `15`.
Tỷ lệ hoặc kích thước xung đột	Sử dụng `aspect_ratio`, `ratio`, `size`, và `resolution` nhất quán; tốt nhất là chỉ giữ cặp tỷ lệ/độ phân giải rõ ràng.
Ràng buộc khung đầu/cuối	Sử dụng `adaptive`, tối đa một vai trò mỗi loại, và bỏ qua các tham chiếu video/âm thanh.
Không thể kiểm tra video tham chiếu	Cung cấp một tệp MP4/MOV hoàn chỉnh có thể truy cập được với thời lượng hợp lệ.
Âm thanh tham chiếu không có hình ảnh/video	Thêm tham chiếu hình ảnh/video hoặc loại bỏ tham chiếu âm thanh.
Yêu cầu bị từ chối do kiểm duyệt nội dung	Sửa đổi văn bản hoặc hình ảnh và gửi yêu cầu mới. Một lỗi dịch vụ kiểm duyệt có thể cho phép quá trình tạo tiếp tục; đây không phải là đảm bảo an toàn tuyệt đối.
`FormatUnsupported` / Từ chối định dạng/nội dung không đồng bộ	Đọc `error.message` của tác vụ thất bại, kiểm tra các yêu cầu về định dạng và tài liệu, và thay thế nguồn.
`401`	Cung cấp khóa API Bearer hợp lệ.
Số dư không đủ	Nạp tiền hoặc sử dụng khóa có hạn ngạch đủ.
`429` / lỗi dịch vụ tạm thời	Chờ và thử lại với độ trễ tăng dần; tránh gửi trùng lặp sau khi hết thời gian chờ không rõ ràng.

Các yêu cầu tham số không hợp lệ đồng bộ không tạo tác vụ video hoặc tính phí tạo. Các tác vụ đã được chấp nhận vẫn có thể thất bại không đồng bộ; hãy kiểm tra trạng thái cuối cùng của tác vụ trước khi sử dụng kết quả.

Xem thêm: Tổng quan tạo video, Seedance 2.0, Seedance 2.0 Mini, và Seedance 2.5.