API Tạo Video Seedance 2.0 Mini

Tham số Seedance 2.0 Mini, 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 Mini

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

Để tạo khung đầ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.

Thao tác	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 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 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-mini`
`prompt`	chuỗi	Bắt buộc	APIMaster không áp đặt giới hạn độ dài lời nhắc cụ thể cho mô hình. 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 như `aspect_ratio`	Bí danh APIMaster. Nếu cả hai xuất hiện, giá trị của chúng phải khớp.
`size`	chuỗi	Giống như `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	Điều khiển 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` cho đầu ra không có âm thanh.
`image_urls`	string[]	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`	object[]	Bỏ qua	Đố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`	string[]	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 là `15` giây. Xem yêu cầu về tài liệu.
`audio_urls`	string[]	Bỏ qua	Tối đa `3` tệp âm thanh tham chiếu, tổng thời lượng 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ề URL tải xuống khung cuối APIMaster có xác thực khi kết quả bao gồm một khung 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`	object[]	Bỏ qua	Khai báo công cụ tìm kiếm: `[{"type":"web_search"}]`.

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 đầy đủ, tránh các tệp bị hỏng hoặc không hoàn chỉnh, và giữ chuyển động 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 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ó khung hình đầu tiên
`reference_image`	Hình ảnh tham khảo, bao gồm tài sản nhân vật đã được phê duyệt

Đối với các tác vụ khung hình đầu/cuối, đặ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 truyền thêm image_urls.

{
  "model": "seedance-2.0-mini",
  "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 đa phần 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, 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 model: "seedance-2.0-mini" một cách rõ ràng. 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 Mini. Một đánh giá thất bại có thể không trả về lý do chi tiết; 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 một tác vụ nhiều lần 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-mini",
    "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-mini",
  "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":138,
    "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 với khóa API của cùng một tài khoản. Chỉ mở một URL kết quả mà không có ủy quyền là không đủ. 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-mini",
    "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 mức: 480P, 720P, 480P-input và 720P-input. Một mức được gắn nhãn "video đã tải lên" có nghĩa là yêu cầu chứa đầu vào video tham chiếu. Hãy chọn 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ị của độ phân giải tương ứng.
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 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 dùng 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 có thể tính phí ở mức đầu vào. Đơn giá đơn vị của mức đầu vào có thể khác với mức thông thường; không chỉ tính thời lượng đầu ra hoặc áp dụng mức thông thường cho 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 không tạo ra một mức có tiếng/không tiế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. Nếu bỏ qua thời lượng đầu ra, hệ thống 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ế. Nếu tạo video thất bại, phí cho tác vụ video sẽ được hoàn lại.

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 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 xóa 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 định dạng và yêu cầu 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 thêm 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 cơ chế backoff; tránh gửi trùng lặp sau khi hết thời gian chờ mơ hồ.

Các yêu cầu tham số không hợp lệ đồng bộ sẽ 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 về tạo video, Seedance 2.0, Seedance 2.0 Fast và Seedance 2.5.