https://router.flatkey.ai
这篇指南从最短可运行流程开始，带你通过 Flatkey 调用 Seedance。复制示例，把 YOUR_FLATKEY_API_KEY、task_...、ast_... 和 rph_... 换成你自己的值，然后运行命令。
本指南里的每个 API 请求都要带这个鉴权头。唯一例外是 metadata.url 返回的视频下载地址：
调用 Seedance
如果你只想用文字生成视频，并下载完成后的视频，从这里开始。1. 创建文生视频任务
用seedance-2.0 模型向 POST /v1/videos 发送文字提示词。
task_...，保存到你的数据库或笔记里，后面查询视频要用。
2. 轮询任务
用保存好的任务 ID 调这个接口：status 变成 completed 后，从 metadata.url 读取下载 URL。如果状态是 failed，读取 error.message，修正请求后重新创建任务。
metadata.url 可以直接下载 MP4 文件，不需要鉴权头。请把这个 URL 当作私密信息，不要公开。
使用素材库
当你想先登记一个参考素材、等待它可用、然后在 Seedance 请求里反复使用时，用素材库。素材库分两类：
在 Seedance 请求中，请使用 Flatkey 返回的
asset://ast_... URI。
虚拟素材
虚拟素材不需要真人认证。你可以用它复用商品图、背景视频或音频参考。1. 用公网 HTTPS URL 创建虚拟素材
发送一个公网https:// URL。虚拟素材通过 JSON 请求使用 URL 创建，不上传本地 multipart/form-data 文件。
id，例如 ast_1234567890abcdef1234567890abcdef，以及 Processing 等状态。在 ID 前加 asset://，就得到可复用 URI：
2. 轮询到 Active
Active 素材可以用于视频生成。Creating、Processing 和 Deleting 都还不能用。删除完成后，GET /v1/assets/{asset_id} 返回 404 asset_not_found；不要等待一个可轮询的 Deleted 状态。
3. 用虚拟素材调用 Seedance
把asset://ast_... 放入和素材类型匹配的媒体字段：Image 用 image_url.url，Video 用 video_url.url，Audio 用 audio_url.url。Seedance 请求需要文本，或至少一张图片/一个视频；只有音频不够。
task_...，再用第一部分的 GET /v1/videos/{task_id} 从 metadata.url 下载完成视频。
真人素材
真人素材用于特定真人的脸、声音或视频。这个能力受邀开放，需要 Flatkey 先为你的账号开通。 流程是：创建真人档案，把verification_url 交给真人本人认证，等档案变成 active，创建素材，等素材变成 Active，最后用 asset://ast_... 调用 Seedance。
文件大小限制：
本节的写入请求必须带
Idempotency-Key。每次新建数据时，都要把示例里的 YOUR_UNIQUE_KEY_... 换成一个新的 UUID。只有重试完全相同的请求时，才复用同一个 key。
1. 创建真人档案
id、status 和一次性的 verification_url。把 verification_url 交给本人，让本人打开并完成认证。不要公开这个链接。
如果链接过期，或本人需要新的链接，创建一个新的认证会话：
2. 轮询到 active
active 后再创建素材。如果还是 pending_verification 或 verifying，稍后继续查。如果是 failed 或 expired，重新创建认证会话。
3. 用公网 URL 创建真人素材
4. 上传本地文件
本地上传使用multipart/form-data，只用于真人素材。使用一个 file 字段，并让 curl 自动设置 multipart boundary。
asset_uri，例如 asset://ast_1234567890abcdef1234567890abcdef。
5. 轮询素材并调用 Seedance
用素材查询接口轮询，直到状态变成Active：
Active 后，用 asset://ast_... 调用 Seedance：
task_...，再用第一部分的 GET /v1/videos/{task_id} 从 metadata.url 下载完成视频。
6. 不再需要时删除素材
204 No Content。删除完成后，GET /v1/assets/{asset_id} 返回 404 asset_not_found。