Tài liệu API · Tác vụ

Tác vụ bất đồng bộ và trạng thái

Máy trạng thái, mã lỗi tác vụ và các trường yêu cầu.

POST /v1/videos/generations trả về ngay 202 cùng đối tượng tác vụ khi kiểm tra hợp lệ thành công. Lỗi phát sinh sau khi tiếp nhận không làm thay đổi mã 202 đã trả về mà chỉ thể hiện ở trường error của đối tượng tác vụ. Khi số tác vụ đang chạy đồng thời của tài khoản hoặc Key đạt giới hạn, API trả về 429 rate_limited (Retry-After: 10).

Trạng thái tác vụ

status	Mô tả
Đang xếp hàng	Đã tiếp nhận, đang chờ xử lý
Đang chuẩn bị	Đang chuẩn bị tài nguyên đầu vào trên kênh xử lý
Đang tạo	Đang tạo video
Đang khôi phục	Kênh hiện tại gặp sự cố, nền tảng đang khôi phục xử lý trên kênh khác; mã tác vụ không đổi
Đang đối soát	Nền tảng đang đối soát kết quả cuối cùng từ upstream để tránh tạo trùng hoặc tính phí trùng
Đang quyết toán	Đang lưu kết quả và quyết toán
Thành công	Thành công, result chứa địa chỉ video; trạng thái cuối
Thất bại	Thất bại, error chứa mã lỗi và mô tả; trạng thái cuối

Chỉ succeeded và failed là trạng thái cuối. Đừng dựa vào thứ tự của các trạng thái trung gian: nền tảng có thể bỏ qua một số trạng thái, hoặc quay từ running về recovering khi khôi phục.

Mã lỗi tác vụ

error.code	Cách xử lý
`no_available_channel`	Trạm này tạm thời không có tuyến xử lý khả dụng. Hãy gửi lại sau với khóa lũy đẳng mới.
`upstream_status_unknown`	Nền tảng chưa xác nhận được kết quả tạo. Hãy xem chi tiết chi phí, rồi gửi lại với khóa lũy đẳng mới.
`task_deadline_exceeded`	Tác vụ vượt quá thời hạn xử lý mà chưa hoàn tất. Có thể giảm thời lượng hoặc độ phân giải rồi gửi lại.
`content_rejected`	Prompt hoặc nội dung tạo ra không vượt qua kiểm duyệt. Hãy điều chỉnh mô tả trước khi gửi lại; gửi lại nội dung cũ vẫn sẽ thất bại.
`asset_rejected`	Tài nguyên đầu vào không vượt qua kiểm duyệt hoặc kiểm tra định dạng. Hãy thay tài nguyên rồi thử lại.
`invalid_parameter`	Tổ hợp tham số không được hỗ trợ. Hãy đối chiếu bảng năng lực mô hình để kiểm tra độ phân giải, tỉ lệ, thời lượng và số lượng đầu vào.
`account_suspended`	Tài khoản đã bị tạm ngưng, vui lòng liên hệ đội ngũ vận hành.
`result_unavailable`	Không thể lấy được kết quả tạo. Vui lòng gửi lại.
`internal_error`	Lỗi nội bộ của nền tảng. Hãy thử lại sau; nếu lỗi lặp lại, hãy liên hệ đội ngũ vận hành kèm mã yêu cầu (request ID).

Các trường yêu cầu

Trường	Mô tả
`model`	Bắt buộc, ID mô hình; phải nằm trong danh sách được phép của Key và đã được cấp quyền cho tài khoản (nếu không sẽ nhận 403 permission_denied)
`prompt`	Prompt; bắt buộc với tác vụ tạo video từ văn bản không có inputs nào, độ dài tối đa xem trong bảng năng lực
`inputs`	Mảng tài nguyên đầu vào { type, asset_id, role }, tối đa 20 phần tử; khung hình đầu, khung hình cuối không dùng chung với các vai trò tham chiếu
`duration`	Bắt buộc, thời lượng (giây); khi bảng năng lực cho phép, có thể truyền -1 để mô hình tự quyết định
`resolution / ratio`	Bắt buộc, độ phân giải và tỉ lệ khung hình; giá trị hợp lệ xem trong bảng năng lực
`max_budget`	Tùy chọn, ngân sách tối đa cho một tác vụ (số tiền dạng chuỗi); nếu mức tạm giữ tối đa vượt quá giá trị này sẽ nhận 402 quota_exceeded
`callback_url`	Tùy chọn, nhận Webhook khi tác vụ đến trạng thái cuối
`metadata`	Tùy chọn, cặp khóa–giá trị dạng chuỗi, được trả về nguyên vẹn; tối đa 32 cặp, khóa ≤ 64 ký tự, giá trị ≤ 512 ký tự, tổng cộng ≤ 8 KiB
`provider_options`	Tùy chọn, tham số riêng của mô hình (cặp khóa–giá trị phẳng, như seed); các khóa và kiểu dữ liệu được phép xem trong bảng năng lực; giá trị là boolean, số nguyên hoặc chuỗi không quá 32 ký tự
`fallback_models`	Tùy chọn, dự phòng giữa các mô hình: khi mô hình yêu cầu không có kênh khả dụng, lần lượt dùng các mô hình này (tối đa 3). Tính phí theo mô hình thực tế, mức tạm giữ theo ứng viên đắt nhất; model_used trong phản hồi cho biết mô hình đã chạy
`allow_fallback`	Tùy chọn; true dùng chuỗi dự phòng mặc định của nền tảng cho mô hình (default_fallbacks trong danh sách mô hình). Bỏ trống hoặc false thì không dự phòng

Các trường kết quả

Khi tác vụ thành công, result gồm video_url, last_frame_url, url_expires_at và retained_until; thời hạn hiệu lực xem tại Lưu giữ kết quả. Nếu tài khoản được bật trả về liên kết gốc từ upstream, kết quả còn có upstream_video_url và upstream_url_expires_at (liên kết gốc từ upstream thường có hiệu lực trong 24 giờ sau khi tạo xong).

Ảnh tham chiếu + âm thanh tham chiếu

POST https://cn-api.aitoken.tools/v1/videos/generations
{
  "model": "seedance-2.0-standard",
  "prompt": "Nhân vật nhìn vào ống kính và mỉm cười, hậu cảnh mờ",
  "inputs": [
    { "type": "image", "asset_id": "asset_xxx", "role": "reference_image" },
    { "type": "audio", "asset_id": "asset_yyy", "role": "reference_audio" }
  ],
  "duration": 8,
  "resolution": "1080p",
  "ratio": "9:16",
  "max_budget": "30.000000",
  "callback_url": "https://example.com/hooks/video",
  "metadata": { "order_id": "A-1001" }
}