Seedance: gửi bất biến và khôi phục yêu cầu

Thêm Idempotency-Key cho seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5. POST /v1/videos, POST /v1/videos/generations, POST /v1/video/generations dùng chung không gian khóa. Không áp dụng cho ảnh, báo giá, remix hay mô hình video khác. Yêu cầu không có khóa không được bảo đảm chống gửi trùng chung.

Phạm vi và khóa

Khóa thuộc tài khoản APIMaster và thao tác tạo video Seedance, không thuộc riêng API Key hay mô hình. Mỗi lần tạo mới dùng khóa ngẫu nhiên mới gồm 8–128 ký tự ASCII hiển thị. Thông tin xác thực hợp lệ của cùng tài khoản có thể tra cứu. Token hết hạn mức vẫn có thể tra cứu hoặc phát lại biên nhận cũ; khóa hết hạn, bị thu hồi, bị xóa và tài khoản bị khóa không thể. Tạo mới vẫn cần xác thực hợp lệ và đủ hạn mức.

Phát lại nguyên tử và xung đột

Lưu bản ghi nguyên tử trước định tuyến, tính phí và liên hệ nhà cung cấp. Cùng khóa và nội dung trả HTTP 202, biên nhận gốc và ID tác vụ cấp trước, không gửi hay giữ tiền lần nữa, kể cả đồng thời và khởi động lại. Đổi nội dung trả HTTP 409 (idempotency_conflict). Bỏ qua thứ tự thuộc tính JSON và khoảng trắng; so sánh thứ tự mảng, số, giá trị bỏ qua hay mặc định rõ ràng, mô hình, thông báo và nhóm/kênh định tuyến. multipart so sánh byte và thứ tự tệp, không so ranh giới hay tên. Giữ nguyên nội dung và định tuyến; JSON và multipart khác nhau. Lưu ít nhất 30 ngày; phiên bản này không tự xóa hoặc tái sử dụng khóa.

Phản hồi

Yêu cầu đầu giữ phản hồi tạo thông thường. Lưu X-Video-Submission-Id, ID yêu cầu và tác vụ. Phát lại trả biên nhận, định dạng có thể khác lần đầu. ID cấp trước không chứng minh nhà cung cấp đã nhận. accepted không có nghĩa tạo xong. Chỉ tra tác vụ khi task_ready=true; nếu không, liên hệ hỗ trợ và không gửi lại.

Trạng thái gửi

pending: đã ghi ở cổng, chưa gửi. submitting: bắt đầu gửi, chờ kết quả. accepted: đã nhận ID nhà cung cấp. not_accepted: chưa gửi nhà cung cấp; sửa lỗi rồi tạo bằng khóa mới. acceptance_unknown: có thể đã nhận nhưng thiếu xác nhận; không tạo lại. Sau sự cố, tra cứu sau 30 phút phân loại bản ghi: trước gửi thành not_accepted, sau gửi thành acceptance_unknown. Không tự gửi lại. Đây là trạng thái gửi, không phải trạng thái tính phí; giữ tiền, quyết toán và đối soát hoàn tiền vẫn áp dụng.

Khôi phục

Sau timeout hoặc 5xx, tra bằng khóa cũ dù chưa có ID. Phát lại giống hệt an toàn nhưng không khởi động lại yêu cầu lỗi. 404, danh sách rỗng hoặc không có phí không chứng minh chưa nhận: yêu cầu còn đang truyền, không có khóa hoặc trước tính năng này. same_key_replay_safe chỉ lấy lại biên nhận; new_submission_safe=true chỉ với not_accepted. Với kết quả không rõ hoặc accepted và task_ready=false, gửi hỗ trợ ID biên nhận/yêu cầu, mô hình và giờ UTC, không gửi API Key. Không bảo đảm tính bất biến của nhà cung cấp chính thức. Biên nhận chân dung cũ giữ quy trình phát lại và có thể trả cấu trúc cũ.

Ví dụ

curl --fail-with-body 'https://apimaster.ai/v1/videos' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: seedance-order-20261014-001' \
  -d '{"model":"seedance-2.0","prompt":"A paper boat on a pond","duration":4,"resolution":"480p","generate_audio":false}'

curl --fail-with-body 'https://apimaster.ai/v1/video-submissions/by-key' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Idempotency-Key: seedance-order-20261014-001'

{
  "code": 200,
  "data": {
    "submission_id": "HASH",
    "task_id": "task_PUBLIC_ID",
    "request_id": "ORIGINAL_REQUEST_ID",
    "model": "seedance-2.0",
    "status": "accepted",
    "task_ready": true,
    "created_at": 1791936000,
    "updated_at": 1791936001,
    "next_action": "query_task",
    "same_key_replay_safe": true,
    "new_submission_safe": false,
    "retention": "at_least_30_days_no_automatic_key_reuse"
  }
}

curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' \
  -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' \
  -H "Authorization: Bearer $APIMASTER_KEY"