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。
虚拟素材
虚拟素材不需要真人认证。你可以从公网 URL 创建，也可以上传本地文件，然后复用返回的 Flatkey 素材 URI。1. 用公网 HTTPS URL 创建虚拟素材
发送一个公网https:// URL。
id，例如 ast_1234567890abcdef1234567890abcdef，以及 Processing 等状态。在 ID 前加 asset://，就得到可复用 URI：
model。Flatkey 会根据这次请求使用的 API Key 自动确定相关的 Seedance 模型。
2. 上传本地虚拟素材
本地图片、视频或音频文件使用multipart/form-data 发送到 POST /v1/assets/upload。使用一个 file 字段；asset_type 可以是 Image、Video 或 Audio。
id 或 asset_url，后面用来轮询并创建视频。
3. 轮询到目标模型可用
用之后创建视频任务的同一个 API Key 查询每个素材。例如，分别查询两张图片素材：available_models。available_models 始终是数组，列出现在可以使用这个素材的模型。部分模型已经可用时，响应可能是：
status 是这个 API Key 相关 Seedance 模型的汇总状态：
如果目标模型已经出现在列表中，就不必等待汇总状态变成
Active。创建任务前，确认每个素材的 available_models 都包含目标模型：快速模型用 seedance-2.0-fast，专业模型用 seedance-2.0。创建任务时还会再次检查素材状态；如果查询后发生变化，请继续轮询再重试。
asset:// URI 只用于标识素材，本身不能证明素材已经可用。Deleting 表示删除中，不能再用于新任务。删除完成后，GET /v1/assets/{asset_id} 返回 404 asset_not_found；不要等待一个可轮询的 Deleted 状态。
4. 用两个虚拟素材调用 Seedance
把每个asset://ast_... 放入和素材类型匹配的媒体字段：Image 用 image_url.url，Video 用 video_url.url，Audio 用 audio_url.url。Seedance 请求需要文本，或至少一张图片/一个视频；只有音频不够。下面的例子需要两张素材的 available_models 都已经包含 seedance-2.0-fast。
task_...，再用第一部分的 GET /v1/videos/{task_id} 从 metadata.url 下载完成视频。
真人素材
真人素材用于特定真人的脸、声音或视频。这个能力受邀开放，需要 Flatkey 先为你的账号开通。 流程是：创建真人档案，把verification_url 交给真人本人认证，等档案变成 active，创建素材，轮询到素材 status 变成 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
真人素材响应不包含available_models。列出这个真人档案下的素材，直到素材 status 变成 Active：
Processing，稍后继续轮询。如果是 Failed，请用更好的参考素材重新创建。
素材变成 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。