Xác minh chủ thể và tài sản chân dung
Hướng dẫn APIMaster dùng chung cho xác minh, tài sản và tạo video Seedance.
Xác minh chủ thể và tài sản chân dung
Dùng thư viện tư liệu thống nhất cho hình ảnh, video và âm thanh thông thường. Khi tạo nhóm, chỉ gửi mô hình và tên, không gửi channel_id hoặc purpose. Máy chủ quản lý kiểm duyệt và các bản sao cho mô hình đích.
Quan trọng: người nổi tiếng và người bình thường sử dụng quy trình khác nhau
Chỉ người nổi tiếng mới cần dùng API xác minh người thật để bắt đầu xác minh người sống:
POST /v1/seedance2/private-avatar/verifications.Người bình thường gửi tư liệu trực tiếp để kiểm duyệt qua
POST /v1/seedance2/private-avatar/assets. Không dùng API xác minh người thật và không tạo phiên xác minh người sống. Có thể tham chiếu tư liệu khi trạng thái làActive.
Bốn mô hình dùng chung giao diện APIMaster. Máy chủ ánh xạ API, thông tin xác thực, ID và trạng thái của nhà cung cấp. Xác minh chính chủ chính thức, kiểm duyệt chân dung của kênh và tài sản thông thường hoặc ảo là các quy trình khác nhau. Chỉ gửi ảnh được chủ thể cho phép rõ ràng.
1. Khả năng và phạm vi
Với quy trình xác minh H5 chính thức riêng, hãy kiểm tra khả năng và dùng channel_id khả dụng có phương thức official_h5. Gửi tư liệu thông thường vào thư viện thống nhất không cần chọn kênh.
| model | duration | Image | Video | Audio |
|---|---|---|---|---|
| seedance-2.0 | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.0-fast | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.0-mini | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.5 | 4–30 s / -1 | ≤30 | ≤10 / ≤30 s | ≤10 / ≤30 s |
Tư liệu thống nhất: tạo, lưu và sử dụng lại
Dùng thư viện tư liệu thống nhất cho hình ảnh, video và âm thanh thông thường. Khi tạo nhóm, chỉ gửi mô hình và tên, không gửi channel_id hoặc purpose. Máy chủ quản lý kiểm duyệt và các bản sao cho mô hình đích.
export APIMASTER_KEY='<your APIMaster key>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/groups' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-d '{"model":"seedance-2.5","name":"My materials"}'
asset_type: Image / Video / Audio.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: unified-audio-001' \
-d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Audio","assets":[{"url":"https://your-storage.example/audio.mp3","name":"Reference audio"}]}'
Lưu group_id (data.id), asset_id và asset_url (tham chiếu asset://). Chủ động gửi tư liệu kiểm duyệt, rồi kiểm tra tác vụ, available_models và model_readiness trước khi tạo với mô hình đã sẵn sàng. Có thể sử dụng lại cùng ID khi tư liệu còn khả dụng; việc xóa, hết hạn hoặc tạo bản sao mới có thể cần bản gốc truy cập được. Xác minh chủ sở hữu H5 chính thức là quy trình riêng, không phải điều kiện kiểm duyệt tư liệu thông thường.
3. Xác minh trên điện thoại
Phần này chỉ dành cho người nổi tiếng. Người bình thường bỏ qua xác minh người sống và chuyển thẳng sang gửi tư liệu để kiểm duyệt.
Với official_h5, tạo phiên rồi chính chủ mở h5_link trên điện thoại của mình. APIMaster tiếp nhận callback HTTPS nên khách hàng không cần máy chủ callback riêng. Không gửi callback_url. Khóa dài hạn và BytedToken chỉ lưu trên máy chủ. Kết quả trình duyệt chưa đủ: máy chủ xác nhận với nhà cung cấp. Callback lặp lại không tạo tài nguyên mới.
export APIMASTER_KEY='<your APIMaster key>'
export APIMASTER_CHANNEL_ID='<available channel ID from the capability API>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/capabilities?model=seedance-2.5' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-session-001' \
-d "{\"model\":\"seedance-2.5\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"name\":\"My portrait\"}"
4. Xác nhận kết quả
Sau completed dùng group_id công khai. Trạng thái và thời hạn dưới đây khác thời hạn cho phép sử dụng chân dung. Lỗi mạng tạm thời giữ nguyên trạng thái; không tự tạo phiên mới. Bảng điều khiển: /console/seedance-materials. Phiên, nhóm, tài sản và tác vụ video có ID riêng.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications/verification_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
| API | fields / values |
|---|---|
| capabilities | model, channel_id, method, configured, reason, hosted_callback, real_person_verified |
| verification | session_id (id), method, status, h5_link (verification_url), created_at, expires_at, group_id |
| verification.status | creating, pending, completed, failed, expired, failed_unconfirmed, submission_unknown |
| Idempotency-Key | 8–128; same request → original receipt; changed request → 409 |
| verification rate | ≤3 / user / minute; upstream limits also apply |
| H5 / BytedToken | single-use H5; query credential ≤30 min; expires_at ≠ portrait authorization expiry |
5. Tải lên và kiểm duyệt tài sản
Người bình thường chỉ cần API gửi tư liệu trong phần này; không gọi API xác minh người thật trước đó.
POST /uploads lưu bản gốc; POST /assets gửi tư liệu kiểm duyệt. Nhóm thông thường dùng unified_virtual. Chỉ tạo khi mô hình đích đã sẵn sàng. Ảnh mới trong nhóm chính thức real_person vẫn phải kiểm tra cùng người. Kết quả thành công một phần giữ lại tư liệu đã được chấp nhận. Nếu chưa xác nhận được việc gửi, giữ ID tác vụ và tư liệu ban đầu, kiểm tra trạng thái và không tự động tải lại.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/uploads' \
-H "Authorization: Bearer $APIMASTER_KEY" -F 'file=@authorized-owner.png'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-asset-001' \
-d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Image","assets":[{"url":"<signed upload URL>","name":"Owner"}]}'
curl --fail-with-body 'https://apimaster.ai/v1/tasks/asset_task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
| API | fields / values |
|---|---|
| uploads | JPEG / PNG ≤10 MB; upload_id, url, url_expires_at, delete_after |
| groups | public id; group_type=unified_virtual / real_person |
| assets | public asset_id; status=Pending / Processing / Active / Failed / SubmissionUnknown |
| review task | asset_task_*; GET /v1/tasks/{id} |
6. Tạo và tải video
Trước khi tạo video, gọi /v1/videos/quote: báo giá không đảm bảo trần phí. Máy chủ giữ kênh, tài khoản và dự án tương thích. Tổ hợp không tương thích bị từ chối. Đổi mô hình vẫn kiểm tra giới hạn đầu vào riêng; ảnh mới cần kiểm duyệt mới. Sau thành công, xem biên nhận phí và tải video.
curl --fail-with-body 'https://apimaster.ai/v1/videos' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-video-001' \
-d '{"model":"seedance-2.5","prompt":"The person smiles naturally","image_urls":["asset://asset_PUBLIC_ID"],"resolution":"480p","duration":4,"generate_audio":false}'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/video-requests/video_request_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
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"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/content' -H "Authorization: Bearer $APIMASTER_KEY" -o owner.mp4
| API | fields / values |
|---|---|
| generation | Idempotency-Key required; no automatic POST retry |
| receipt | video_request_*; X-Seedance-Request-Id; replay → 202 + original receipt |
| video task | task_*; separate from receipt, verification and asset IDs |
7. Quyền riêng tư và xóa
Liên kết có chữ ký là thông tin nhạy cảm: người giữ liên kết có thể tải trong thời hạn hiệu lực. Không ghi log liên kết H5, URL có chữ ký hay thông tin callback. Xóa bản gốc không xóa tài sản nhà cung cấp. Xóa tài sản loại bỏ ánh xạ APIMaster và dùng API xóa nhà cung cấp nếu hỗ trợ; không hứa khả năng xóa từ xa chưa có. Xóa tài sản trước nhóm. Video đã tạo không tự biến mất. Không lưu mẫu sinh trắc học; duyệt thành công không thay thế sự cho phép sử dụng.
| API / storage | values |
|---|---|
| signed original URL | 1 h |
| hosted original | access ≤24 h; deletion ≤25 h |
| DELETE /uploads/{upload_id} | hosted original |
| DELETE /assets/{asset_id} | APIMaster mapping; upstream deletion if supported |
| DELETE /groups/{group_id} | empty group |
8. Chi phí và lỗi
Kiểm tra ngày 2026-10-07: tài liệu chính thức mô tả xác minh miễn phí có thời hạn. Phí thực tế của phiên, duyệt, tải lên, lưu trữ và quản lý tùy ngữ cảnh và chưa xác nhận đầy đủ. Không tự mua gói quyền lợi. Tạo video dùng cơ chế báo giá, tạm giữ, quyết toán và hoàn tiền hiện có; kiểm tra biên nhận thực tế. Lỗi phân biệt quyền, khả năng không hỗ trợ, xác minh hoặc duyệt chờ/thất bại, tài sản không tương thích và kết quả nhà cung cấp chưa rõ. Không truy cập tài nguyên người dùng khác.
| HTTP | context |
|---|---|
| 400 | input / callback |
| 403 | permissions |
| 404 | resource |
| 409 | pending / failed review / incompatible context |
| 429 | rate limit |
| 502 / 503 | uncertain upstream result / unavailable |
Seedance: gửi bất biến và khôi phục yêu cầu
Tư liệu ảo và khôi phục tự động
Nhóm ảo không có channel_id cho phép dùng cùng ID asset:// với mô hình tương thích. available_models, model_readiness, all_models_ready thể hiện trạng thái sẵn sàng. Mỗi dịch vụ duyệt bản sao độc lập. Truy vấn tác vụ duyệt để cập nhật; tạo bản sao cần bản gốc còn truy cập được. Kênh chỉ định, các nhóm tư liệu hiện có và tư liệu H5 chính thức giữ giới hạn ràng buộc.
Tạo video cần Idempotency-Key. Trước khi tiếp nhận, chỉ có thể chuyển dịch vụ sau từ chối giới hạn tốc độ rõ ràng, không có ID tác vụ. Tác vụ đã nhận kết thúc do tài khoản bị vô hiệu hóa, thông tin xác thực không hợp lệ hoặc lỗi dịch vụ được xác nhận có thể tự khôi phục tối đa một lần nếu có dịch vụ tương thích. Giữ ID công khai và mức giá người dùng đã chốt, không giữ trước tiền tạo video lần hai. Tiếp tục truy vấn tác vụ gốc và biên nhận tính phí.
Dịch vụ đích cần bản sao tương thích đã duyệt hoặc hoàn tất duyệt tư liệu độc lập. Không chuyển kết quả duyệt hay xác thực H5 chính thức giữa dịch vụ hoặc tài khoản. Lỗi tham số, kiểm duyệt, bản quyền, hết thời gian, mất kết nối và tiếp nhận chưa rõ bị loại trừ. Trước khi gửi lại thủ công, kiểm tra biên nhận; chỉ dùng khóa mới khi new_submission_safe=true.
