Hướng dẫn API Seedance 2.5 Flash: Tác vụ bất đồng bộ, giới hạn, lỗi

AIHubMixĐọc 8 phút
Hướng dẫn API Seedance 2.5 Flash: Tác vụ bất đồng bộ, giới hạn, lỗi

Dùng doubao-seedance-2-5-flash với POST /ai/v1/videos, thăm dò trạng thái tác vụ, rồi tải kết quả xuống. Lược đồ AIHubMix hiện tại hỗ trợ đầu ra 480p/720p, clip dài 4–30 giây và tối đa 10 hình ảnh, 5 video cùng 5 tham chiếu âm thanh. Các client cũ dùng /v1/videos cần đổi cả endpoint lẫn ID model.

Hướng dẫn này được kiểm tra vào ngày 16 tháng 11 năm 2026. Cả ID ngắn ở trên và doubao-seedance-2-5-flash-261115 đều trả về lược đồ model và từ chối yêu cầu 1080p bằng 400 schema_violation. Một lần thử tạo riêng với thời lượng 4 giây, độ phân giải 480p trả về 402 insufficient_quota; video không được tạo. Quy trình bên dưới tuân theo lược đồ và tài liệu hiện tại, nhưng việc tạo thành công, độ trễ, đầu ra MOV và chỉnh sửa chưa được xác minh từ đầu đến cuối trong lần kiểm tra này.

Điều kiện tiên quyết và khám phá lược đồ

Trang model Seedance 2.5 Flash liệt kê model này bằng ID ngắn được dùng xuyên suốt hướng dẫn. Trước khi gửi tác vụ:

  1. Bật tính năng tác vụ đa phương tiện bất đồng bộ trong bảng điều khiển AIHubMix. Lỗi được ghi nhận cho tài khoản chưa bật tính năng này là 403 async_not_enabled.
  2. Đảm bảo khóa API có quyền truy cập và tài khoản có đủ tín dụng. Lần kiểm tra trực tiếp trả về 402 insufficient_quota cùng thông báo Your account has insufficient quota. Add credits and try again.
  3. Xuất AIHUBMIX_API_KEY trong shell. Không để lộ khóa trong tệp mã nguồn hoặc mã chạy trên trình duyệt.
  4. Lấy lược đồ hiện tại; yêu cầu khám phá không cần xác thực.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

Lược đồ ngày 16 tháng 11 chỉ liệt kê /ai/v1/videos cho Flash. Lược đồ chấp nhận các giá trị resolution là 480p và 720p (mặc định là 720p), giá trị nguyên duration từ 4 đến 30 hoặc -1 để model tự chọn thời lượng. Hãy dùng thời lượng cụ thể nếu bạn cần ngân sách có thể dự đoán.

Tạo, thăm dò trạng thái và tải xuống

API tạo video AIHubMix tách riêng các bước tạo, truy vấn trạng thái và tải xuống. Phản hồi HTTP thành công khi tạo có nghĩa là tác vụ đã được chấp nhận; chỉ status: "completed" mới xác nhận tác vụ hoàn tất. Truy vấn có thể trả về HTTP 200 trong khi tác vụ có status: "failed".

Gửi tác vụ chuyển văn bản thành video

Ví dụ này yêu cầu một clip sản phẩm 10 giây, 720p, tỷ lệ 16:9 có âm thanh. Ví dụ chỉ dùng văn bản nên không phụ thuộc vào hình ảnh tham chiếu được lưu trữ ở nơi khác.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

Lưu ngay id tác vụ được trả về. Thăm dò GET /ai/v1/videos/{id} mỗi 15 giây cho đến khi trạng thái là completed, failed hoặc cancelled. Dùng endpoint chi tiết video để thăm dò tác vụ đang chạy: endpoint này làm mới trạng thái từ nhà cung cấp, còn danh sách tác vụ hợp nhất không thể thay thế việc kiểm tra đó. Sau khi hoàn tất, tải video qua GET /ai/v1/videos/{id}/content, sử dụng cùng tiêu đề Bearer.

Client Python hoàn chỉnh

Cài đặt phần phụ thuộc bằng python3 -m pip install requests, lưu nội dung sau thành seedance_flash.py, rồi chạy python3 seedance_flash.py trong shell có khóa API. Ví dụ này triển khai quy trình được tài liệu hướng dẫn; lỗi hạn ngạch ở trên khiến chúng tôi không thể kiểm tra quá trình tạo hoàn chỉnh.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

Thời hạn 20 phút là giới hạn chờ ở phía client, không phải lệnh hủy phía máy chủ hay cam kết về thời gian tạo. Nếu thăm dò trạng thái hoặc tải xuống thất bại, hãy giữ lại ID tác vụ và thử lại thao tác đó. Không tự động gửi yêu cầu tạo mới sau khi hết thời gian chờ hoặc khi trạng thái từ nhà cung cấp chưa rõ ràng.

Theo mức giá suy luận trực tuyến chính thức của BytePlus, Flash có giá $7.00 cho mỗi triệu token nếu không có đầu vào video hoặc $4.30 nếu có đầu vào video ở 480p/720p. Với ví dụ chỉ dùng văn bản, ước tính là 10 × 1280 × 720 × 24 / 1024 = 216,000 token: $1.51 với Flash so với $2.31 với flagship 2.5 ở 720p. Đây là các ước tính được tính theo mức giá BytePlus, không phải hóa đơn AIHubMix được đo thực tế.

Tham chiếu và webhook

Để định hướng clip bằng nội dung đa phương tiện, hãy thêm các mục input_references gồm type (image_url, video_url hoặc audio_url) và url trỏ đến nội dung đa phương tiện mà hệ thống có thể truy cập. Lược đồ giới hạn số lượng các loại này lần lượt là 10 / 5 / 5. Để kiểm soát khung hình đầu/cuối, hãy dùng frame_images thay thế; mỗi mục có frame_type và image_url.url lồng bên trong. Không kết hợp frame_images và input_references nếu cả hai đều không rỗng. Quy trình dùng khung hình yêu cầu aspect_ratio: "adaptive", và nếu có khung hình cuối thì phải có cả khung hình đầu.

Tài liệu về tác vụ bất đồng bộ mô tả callback HTTPS qua webhook_url. Lược đồ hiện tại của Flash có trường này nhưng bỏ qua webhook_events_filter và đặt additionalProperties: false, vì vậy hãy bỏ qua bộ lọc khi làm theo lược đồ model này. Theo tài liệu, mặc định hệ thống gửi các sự kiện completed, failed và cancelled. Việc gửi được thực hiện ít nhất một lần, tối đa sáu lần thử, với khoảng thời gian thử lại là 1, 4, 16, 64 và 256 giây; hãy loại bỏ sự kiện trùng lặp dựa trên event_id. Callback cấp tác vụ không có khóa bí mật ký riêng, vì vậy hãy truy vấn tác vụ để xác nhận trạng thái cuối cùng. Tài liệu mô tả các đăng ký cấp tài khoản dành cho ứng dụng cần xác minh chữ ký.

Lỗi: kết quả đo được và nội dung tài liệu mô tả

1080p: lược đồ từ chối trong lần kiểm tra

Cả hai ID model AIHubMix đều trả về HTTP 400 với yêu cầu 4 giây có resolution: "1080p". Các trường lỗi được trả về gồm:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

Phản hồi cũng có một ID truy vết yêu cầu, được lược bỏ ở đây. Đây là trường hợp cổng API từ chối được ghi nhận, không phải lỗi phía thượng nguồn được suy đoán. Kết quả này không chứng minh việc tạo thành công hay đo lường tốc độ.

Các giới hạn khác bên dưới lấy từ lược đồ Flash hiện tại; những tổ hợp không hợp lệ này chưa được gửi riêng trong lần kiểm tra trực tiếp.

Vấn đề đầu vào Yêu cầu của lược đồ Cách khắc phục
Đầu ra 4K 480p hoặc 720p Giảm độ phân giải
Quá nhiều tham chiếu 10 hình ảnh / 5 video / 5 âm thanh Giảm số lượng
Hai mảng tham chiếu Chỉ một mảng không rỗng Chọn một quy trình
Chỉ có khung hình cuối Cũng cần khung hình đầu Cung cấp cả hai khung hình
Tỷ lệ cố định khi dùng khung hình Tỷ lệ thích ứng Dùng tỷ lệ thích ứng

Tham chiếu người thật: dùng tài sản đã xác minh

AIHubMix ghi nhận lỗi doubao_real_person_required khi Doubao trả về lỗi từ chối quyền riêng tư cụ thể đối với hình ảnh người thật. Lỗi này không xuất hiện trong lần kiểm tra. Thông báo được ghi nhận là:

Yêu cầu này sử dụng hình ảnh người thật. Hãy hoàn tất xác minh người thật và dùng tham chiếu tài sản đang hoạt động. Xem https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Làm theo Hướng dẫn về tài sản người thật của Doubao: tạo nhóm tại /ai/v1/asset-groups, tạo phiên xác minh tại /ai/v1/asset-groups/{id}/verification-sessions, để người xuất hiện trong hình hoàn tất xác minh trên web, đăng ký tài sản tại /ai/v1/asset-groups/{id}/assets rồi đợi đến khi tài sản hoạt động. Dùng asset://<ASSET_ID> làm tham chiếu khi tạo. URL ảnh gốc không thể thay thế quy trình xin đồng ý và đăng ký tài sản.

Hạn ngạch, kích thước yêu cầu và tải xuống

Lỗi 402 insufficient_quota được ghi nhận đã khiến yêu cầu có độ phân giải hợp lệ không thể chuyển sang bước tạo. Hãy nạp thêm tín dụng trước khi thử lại; thay đổi prompt đúng hoặc ID model không khắc phục được phản hồi này. 403 async_not_enabled là lỗi điều kiện tiên quyết khác đã được ghi nhận, yêu cầu bật tính năng trong bảng điều khiển.

AIHubMix ghi nhận giới hạn kích thước phần thân yêu cầu là 32 MiB và lỗi 413 request_too_large. URL công khai giúp phần thân yêu cầu không bị phình to do mã hóa Base64, nhưng nội dung đa phương tiện được tham chiếu vẫn phải đáp ứng các giới hạn riêng về kích thước và định dạng của model.

Hãy lưu video ngay sau khi hoàn tất. Hướng dẫn tích hợp Seedance 2.5 hiện có của AIHubMix cảnh báo URL đầu ra chỉ có hiệu lực trong thời gian ngắn, khoảng 30 phút; thời hạn lưu trữ cụ thể của Flash chưa được xác minh tại đây. API video có thể trả về expires_at: null, nhưng điều đó không đảm bảo lưu trữ vô thời hạn. Các lỗi tải xuống được ghi nhận gồm 410 artifact_expired và 429 too_many_downloads. Nếu dịch vụ gặp lỗi tạm thời khi tải xuống, hãy thử tải lại từ tác vụ hiện có thay vì tạo lại clip.

Những vấn đề khi di chuyển mà yêu cầu hợp lệ vẫn có thể gặp

Hướng dẫn Seedance 2.5 của Volcengine nêu rõ Flash thuộc dòng model này và xác nhận hỗ trợ đầu ra MOV, chỉnh sửa và kéo dài video; tuy nhiên, cần phân biệt các khả năng do nhà cung cấp công bố với những gì đã được xác minh qua cổng API.

  • Các trường MOV và chỉnh sửa có trong lược đồ, nhưng chưa được kiểm tra từ đầu đến cuối tại đây. Lược đồ Flash chấp nhận extra.output_format: "mp4" hoặc "mov" và các giá trị extra.omni_reference_task_type là auto, reference, edit và extend. Nếu gửi rõ trường loại tác vụ, lược đồ yêu cầu input_references không được rỗng. edit còn cần tham chiếu video, tỷ lệ thích ứng và duration: -1; extend cần tham chiếu video và tỷ lệ thích ứng.
  • Việc chỉ định rõ loại tác vụ không đảm bảo model chấp nhận. Ark ghi nhận lỗi bất đồng bộ InvalidParameter.TaskTypeConstraint khi loại tác vụ được suy ra không khớp với tham số, và InvalidParameter.TaskTypeMismatch khi loại được suy ra khác với loại được yêu cầu rõ ràng. Ánh xạ chính xác sang AIHubMix chưa được đo; hãy kiểm tra error được trả về trong tác vụ thay vì mặc định rằng cổng API chỉ trả về một mã lỗi.
  • Flash không hỗ trợ nâng cấp từ Draft. Nhà cung cấp giới hạn quy trình hai giai đoạn từ Draft 480p lên bản cuối ở flagship 2.5. Flash không hỗ trợ tính năng này, và lược đồ AIHubMix hiện tại cho cả hai model đều không có draft và draft_task.
  • Đầu vào video làm thay đổi cách tính phí. Cách tính phí chính thức dựa trên tổng thời lượng video đầu vào và đầu ra, đồng thời có thể áp dụng mức sàn token tối thiểu. Mức giá $4.30/M không đảm bảo một tác vụ có video làm dữ liệu hướng dẫn sẽ rẻ hơn tác vụ chỉ dùng văn bản tương đương. Hãy kiểm tra mức sử dụng thực tế và khoản phí trên tài khoản thay vì chỉ dựa vào công thức.
  • Một số mô tả vẫn còn mơ hồ. Lược đồ gateway của Flash hiển thị extra.priority, extra.safety_identifier và extra.tools, nhưng phần mô tả của chúng vẫn ghi “chỉ dành cho dòng 2.0”. Tài liệu tham khảo về tác vụ tạo của Ark cũng liệt kê priority và tools cho cả dòng 2.5. Việc lược đồ hiển thị các trường này không đủ để xác minh tác dụng của chúng trên AIHubMix; hãy kiểm tra tính năng cụ thể trước khi dựa vào đó trong môi trường production.

Danh sách kiểm tra trước khi chạy

  • Bật tác vụ bất đồng bộ và kiểm tra số dư tài khoản.
  • Dùng ID Flash rút gọn với /ai/v1/videos và truy xuất lược đồ hiện tại.
  • Chọn 480p hoặc 720p và đặt thời lượng cụ thể trong khoảng 4–30 giây.
  • Giới hạn số tham chiếu ở mức tối đa 10 ảnh, 5 video và 5 đoạn âm thanh.
  • Tách riêng các tham chiếu khung hình và dùng tỷ lệ khung hình thích ứng cho chúng.
  • Chuyển các tham chiếu hình ảnh người thật qua những tài sản đã xác minh và đang hoạt động.
  • Lưu ID tác vụ, kiểm tra trạng thái cuối cùng của tác vụ và tải xuống sớm.
  • Nếu trạng thái tạo không chắc chắn, hãy thử truy vấn lại hoặc tải xuống từ tác vụ hiện có.

Câu hỏi thường gặp

Tôi có thể dùng đường dẫn tương thích với OpenAI /v1/videos cho Flash không?
Lược đồ Flash hiện tại chỉ liệt kê /ai/v1/videos. Hãy dùng đường dẫn bất đồng bộ gốc này cho các ví dụ trong hướng dẫn.

Tại sao yêu cầu có ảnh khung hình lại thất bại với aspect_ratio: "16:9"?
Lược đồ Flash yêu cầu aspect_ratio: "adaptive" khi có cung cấp frame_images không rỗng. Khung hình cuối cũng yêu cầu phải có khung hình đầu, và không thể kết hợp tham chiếu khung hình với input_references không rỗng.

Làm thế nào để khắc phục doubao_real_person_required?
Làm theo quy trình xác minh danh tính và đăng ký tài sản, chờ đến khi tài sản được kích hoạt rồi tham chiếu đến tài sản đó bằng URI. Mã này biểu thị trường hợp từ chối vì quyền riêng tư cụ thể của Doubao; lỗi này không xuất hiện lại trong lần kiểm tra này.

Tại sao video tham chiếu ngắn lại có thể tốn nhiều hơn mức công thức dự đoán?
Quy tắc tính phí của nhà cung cấp có thể áp dụng mức sàn token tối thiểu khi đầu vào có video. Công thức chỉ là ước tính; hãy kiểm tra mức tiêu thụ thực tế và lịch sử thanh toán của tài khoản để biết số tiền đã tính.

Các lần tạo thất bại hoặc bị kiểm duyệt từ chối có tốn tiền không?
Quy tắc tính phí chính thức của BytePlus và Volcengine tính phí các lần tạo thành công, đồng thời nêu rõ rằng các lần tạo thất bại và bị từ chối qua kiểm duyệt nội dung sẽ không bị tính phí. Tài liệu về lỗi của AIHubMix khuyên nên kiểm tra lịch sử thanh toán để biết các khoản phí trước đây; trong lần kiểm tra này, không có khoản phí nào cho lần tạo thành công hay thất bại được ghi nhận.

Tôi có bao lâu để tải kết quả Flash xuống?
Hãy tải xuống ngay sau khi hoàn tất. Hướng dẫn Seedance 2.5 hiện có cảnh báo rằng URL có thời hạn khoảng 30 phút, nhưng chưa xác minh thời gian lưu chính xác của Flash; trường hết hạn có giá trị null cũng không có nghĩa là kết quả được lưu vĩnh viễn.

AIHubMix có hỗ trợ đầu ra MOV và chỉnh sửa/mở rộng không?
Lược đồ Flash hiện tại hiển thị các trường tương ứng trong extra, và nhà cung cấp có tài liệu về những tính năng này. Chưa xác minh được hoạt động đầu cuối của chúng qua AIHubMix vì thử nghiệm tạo đã dừng ở phản hồi không đủ hạn mức.

Đọc tiếp: loạt bài Seedance 2.5 Flash

Nguồn

Tài liệu và lược đồ được kiểm tra ngày 16 tháng 11, 2026; phản hồi xác thực được ghi nhận lúc 08:26 UTC. Giá là mức ước tính chính thức của BytePlus, không phải khoản phí thực đo qua gateway.

Một cổng duy nhất tới nhiều nhà cung cấp AI. Sẵn sàng cho môi trường production.

Truy cập AIHubMix