更新日期：2026-10-31

版本说明：本次源码更新包含素材引用索引修复和 Dreamina 视频参考，须同步部署 API 与 Worker 后生效。两图、两视频、两音频的混合生成和官网再次编辑回填已通过真实验收；历史任务仍按原任务 ID 查询。

第 1～10 节保留 Dreamina Seedance 2.5 的完整调用说明；第 11 节介绍 AKOOL Seedance 2.0。两平台在同一管理网站维护账号，凭证、地区要求和上游协议各自独立。

新调用统一使用 POST /v1/videos/generations/async 和 GET /v1/videos/generations/async/{task_id}。请求体以 provider 选择平台，省略时默认 dreamina；Dreamina 原有的 international 提交与查询路径继续兼容。

1. 基础信息

新版本支持纯文字生成、图片/视频/音频全能参考和首尾帧；首尾帧模式不混用全能参考素材。

2. 身份认证

方式一：账号池自动选择账号（推荐）

Authorization: Bearer <POOL_API_KEY>

POOL_API_KEY 是服务调用密钥，保存在项目 .env 中。此方式不需要传邮箱、sessionid 或额外的 X-API-Key。

方式二：自己指定 sessionid

Authorization: Bearer us-<sessionid>
X-API-Key: <POOL_API_KEY>

管理后台选择美国区后，添加、编辑和批量导入可直接粘贴官网复制的原始 sessionid，系统自动补上 us-。已有前缀不会重复添加。

直接调用生成 API 时，Authorization 仍需使用 Bearer us-<sessionid>。后台复制的凭证已经包含 us-，直接使用即可。

指定 sessionid 后，默认仍允许积分不足时切换到池内其他账号。如果只允许使用指定账号，在完整请求体中增加 "failover": false。

3. 提交生成任务

请求地址：

POST http://154.36.171.58:8001/v1/videos/international/generations/async

请求头（账号池自动选账号）：

Authorization: Bearer <POOL_API_KEY>
Content-Type: application/json
Idempotency-Key: <本次任务的唯一标识>

Idempotency-Key 可选，但建议填写：

• 新任务使用新值，例如 UUID。
• 同一请求因网络异常重试时，保持原值和请求体不变。
• 相同键、相同请求返回原任务，不重复创建。
• 相同键、不同请求返回 HTTP 409。
• 键区分大小写。不传时，多次提交可能创建多个任务。

示例一：纯文字生成

{
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "一只猫坐在窗边晒太阳，镜头缓缓推进，画面自然真实。",
  "images": [],
  "audios": [],
  "videos": null,
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

示例二：图片和音频参考

将示例 URL 替换为服务器可以访问的真实素材地址。

{
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "让@图片1中的人物站在@图片2的场景中自然说话，音色参考@音频1。",
  "images": [
    {
      "url": "https://example.com/person.jpg",
      "role": "reference_image"
    },
    {
      "url": "https://example.com/background.jpg",
      "role": "reference_image"
    }
  ],
  "audios": [
    {
      "url": "https://example.com/voice.wav",
      "role": "reference_audio"
    }
  ],
  "videos": null,
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

素材编号规则：

• @图片1 对应 images[0]，@图片2 对应 images[1]。
• @视频1 对应 videos[0]，@音频1 对应 audios[0]，三类素材分别从 1 编号。
• 内部按“图片 → 视频 → 音频”组成总素材表，所有明确引用均转换为该表中从 0 开始的 material_idx。用户无需改写编号。
• 未在提示词中引用的素材也会上传，不会自动删除。
• 保留重复 URL；单项素材失败会明确报错，不会删除该项后重新编号。
• 提示词内容、空白、换行和请求时长按原请求保留；素材引用标记会转换为上游结构化引用。

示例三：图片、视频和音频混合参考

{
  "provider": "dreamina",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "人物参考@图片2，场景参考@图片1，动作参考@视频2和@视频1，音色参考@音频2和@音频1。",
  "images": [
    { "url": "https://example.com/scene.jpg", "role": "reference_image" },
    { "url": "https://example.com/person.jpg", "role": "reference_image" }
  ],
  "videos": [
    { "url": "https://example.com/motion-1.mp4", "role": "reference_video" },
    { "url": "https://example.com/motion-2.mp4", "role": "reference_video" }
  ],
  "audios": [
    { "url": "https://example.com/voice-1.mp3", "role": "reference_audio" },
    { "url": "https://example.com/voice-2.mp3", "role": "reference_audio" }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 4
}

该示例对应 @图片1→0、@图片2→1、@视频1→2、@视频2→3、@音频1→4、@音频2→5。重复引用同一素材始终指向同一索引。

示例四：首尾帧生成

{
  "model": "seedance-2.5",
  "mode": "first_last_frames",
  "prompt": "从起始画面自然过渡到结束画面，动作流畅，镜头稳定。",
  "first_frame": "https://example.com/first.jpg",
  "last_frame": "https://example.com/last.jpg",
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

• first_frame 必填，last_frame 可选。
• 此模式不混用全能参考图片、视频或音频。
• 图片比例不符时，等比缩放并补黑边，保留完整图片，不裁剪。

示例四：指定 sessionid，禁止换号

请求头：

Authorization: Bearer us-<sessionid>
X-API-Key: <POOL_API_KEY>
Content-Type: application/json
Idempotency-Key: <本次任务的唯一标识>

请求体：

{
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "一只猫坐在窗边晒太阳，镜头缓缓推进。",
  "images": [],
  "audios": [],
  "videos": null,
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5,
  "failover": false
}

多地区调用

在原请求体中加入 "region": "SG" 即可选择新加坡区账号。也可以直传 Authorization: Bearer sg-<sessionid> 并携带 X-API-Key，未传地区时自动使用 SG。指定池内 account_id 时自动使用该账号地区；显式 region 必须与指定账号或凭证一致。纯服务密钥调用且未指定账号或地区时仍默认 US。

支持地区：US、HK、JP、SG、AL、AZ、BH、CA、CL、DE、GB、GY、IL、IQ、IT、JO、KG、OM、PK、PT、SA、SE、TR、TZ、UZ、VE、XK。代码复用已有地区路由及 Seedance 2.5 载荷；已记录 US 及 JP 的 720p 真实成片，其他规格和地区的上游可用性以实际验收为准。

自动换号只在任务地区内发生，仍仅接受明确积分不足拒绝；提交未知不重复生成。账号在关联任务结束前不能改变地区。同一原始 sessionid 不能通过更换前缀重复导入增加容量。

提交与查询返回 region。地区参与幂等校验；同键不同地区返回 HTTP 409。显式 US 与旧版缺省 US 请求兼容，旧幂等键继续可用。

4. 请求参数

图片、视频和音频数组中的每一项：

三类素材合计最多 50 项：图片最多 30 张、视频最多 10 段、音频最多 10 段。单个 URL 下载限制为图片 30MB、视频 200MB、音频 15MB；multipart 仍受服务器现有单文件 100MB 限制。

视频支持 MP4/MOV，参考时长 1.8～30.2 秒，视频合计不超过 30.2 秒；尺寸 300～6000 像素，宽高比 0.4～2.5，帧率 24～60，总像素 409600～8295044。音频支持 WAV/MP3，每段 1.8～30.2 秒，音频合计不超过 30.2 秒。视频与音频时长分别统计；元数据不完整时明确失败，不填 0、不猜时长、不裁剪或重新编号。素材格式还需通过上游上传校验。

本地音视频使用 multipart 字段 video_file_1、video_file_2、audio_file_1 等，不将本机 E:/... 路径填入 JSON 的 url。URL 下载逐次检查重定向目标和网络地址；素材请求不会附带平台登录凭证。

当视频上传回执缺少帧率时，从原始 MP4/MOV 的帧时间表读取平均帧率，不使用固定帧率或文件大小估算。2026-10-08 已验证两段 MP4、两段 MP3 的真实上传、返回元数据及载荷索引；尚未提交真实混合生成。

480p / 720p 是上游输出档位，不保证所有比例的短边恰好等于档位数值。两档均适用于纯文字、图片/音频/视频全能参考及首尾帧模式，支持六种现有比例。首尾帧图片按所选分辨率等比补边；参考素材顺序、引用索引和提示词保持原有约定。

分辨率别名在保存任务及幂等比较前归一化：同一幂等键下，480p、480P、480 表示同一请求；480p 改成 720p 则属于不同请求，返回 HTTP 409。2026-10-29 的 480p 支持为本地开发变更，部署后生效；本轮没有新增付费生成，不能视为全部组合已真实出片。

Dreamina 的调度预算仍按管理员配置的每秒估算值计算，账号级估算覆盖值继续有效。此次没有更改单价或把其他平台的计费规则套用到 Dreamina；不同地区、分辨率、优惠及参考视频的真实消耗需另行核实。

duration 必须显式填写。缺省、null、空字符串或全空白字符串会返回 HTTP 400，不会创建任务：

{
  "code": "DURATION_REQUIRED",
  "message": "duration 为必填项，请提供 4～30 秒整数",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

示例中的 "duration": 5 是明确指定生成 5 秒，不是默认值。

账号套餐与支持规格

管理员可以在账号池为 Dreamina 账号设置 subscription_tier（basic、standard、advanced、ultra）以及最终的 supported_resolutions（480p、720p 多选）。套餐未配置时，两字段均为 null；已选套餐可保存空列表，表示没有可分配规格。它们是管理员维护的账号能力标记，不是上游实时报价或自动识别的会员证明。

账号页显示套餐与支持规格，支持按两项筛选。管理员可逐号编辑，或选择筛选范围内最多 200 个 Dreamina 账号统一设置；批量保存使用账号版本检查，冲突时整批拒绝，刷新后重新核对。上号人员可以查看本人账号的套餐与规格，不能修改；旧助手导入时未携带新字段，不会覆盖已有配置。

调度设置中的“严格要求账号配置支持规格”默认关闭。已完整配置套餐与支持规格的账号始终按最终列表接单，不受开关影响；例如 Basic 账号只配置 480p，关闭严格要求也不会接到 720p。支持列表为空，或套餐与规格只配置其中一项的账号，始终不接新任务。开关关闭时，仅套餐与支持规格均为 null 的未配置旧号兼容原规则；开启后，所有账号都必须完整配置支持规格。已提交的生成任务继续按原记录处理。

套餐模板初始为 Basic 支持 480p、Ultra 支持 720p，Standard 和 Advanced 为空，需管理员按实际能力补充。选择或切换账号套餐时带出当前模板，最终列表仍可按账号调整；修改模板不会批量改写已有账号。账号修改携带 expected_subscription_revision，模板设置携带自己的 revision，避免旧页面覆盖新配置。

以上能力字段只供管理端维护，不接受生成请求自行覆盖。管理员任务详情保留分配时的 subscription_snapshot（严格配置开关 enabled、实际过滤标记 enforced、规则版本、账号配置版本、套餐、支持规格、请求分辨率）；执行尝试分别留存，不混入对外请求或暴露给普通调用方。历史快照缺少 enforced 时兼容按 enabled 展示，缺少整个快照时显示“—”。本功能不修改积分估算系数，不新增自动生成或重试。

5. 提交响应

以下为示意响应，具体阶段可能随调度进度变化：

{
  "created": 1790913600,
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "processing",
  "stage": "queued",
  "wait_reason": null,
  "account_id": null,
  "attempts": 0,
  "reused": false
}

提交成功仅表示任务已被接收，不代表视频已生成完成。

6. 查询任务

请求：

GET http://154.36.171.58:8001/v1/videos/international/generations/async/<task_id>
Authorization: Bearer <POOL_API_KEY>

不需要请求体。建议每隔 15 秒查询一次。无论提交时使用哪种认证方式，查询都可以使用上述服务密钥。

成功响应示例

{
  "created": 1790913600,
  "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "succeeded",
  "stage": "succeeded",
  "wait_reason": null,
  "account_id": "当前账号ID",
  "attempts": 1,
  "data": [
    {
      "url": "https://service.example/v1/video-results/<task_id>/<signature>.mp4",
      "revised_prompt": "原始提示词"
    }
  ]
}

视频地址读取：data[0].url。当前账号池 Dreamina 任务在上游生成完成后，先进入 stage: "saving"，对外仍为 status: "processing"，不返回上游成片地址。服务器完成下载、完整性及 MP4 文件头校验后才返回成功，链接格式为 /v1/video-results/{task_id}/{signature}.mp4，支持 GET、HEAD 和 Range；result_storage 提供保存状态、保存时间与到期时间。

Dreamina 成片保存与清理

转存需要服务配置有效的固定 HTTPS 公网地址 POOL_PUBLIC_BASE_URL，并沿用账号池加密密钥生成下载签名；配置无效时不受理新生成任务，不静默回退到上游地址。

单次保存最多 30 分钟。下载失败只有限次重试保存；成片源链接失效时只查询原上游任务刷新地址，不重新生成、不因保存失败换号重提。达到保存失败限制后，任务明确标记为“视频已生成但服务器保存失败”，业务响应使用 GENERATION_FAILED，增加 reason_code: "RESULT_DELIVERY_FAILED"，管理员仍可查看保存错误。

视频从保存成功时间起计算 24 小时到期，服务运行期间每小时检查并删除已到期成片。磁盘空间不足时，按已到期优先、最接近到期的顺序，每批清理 100 条；未满 24 小时的成片也可能被提前删除。正在写入或读取的文件受到保护。清理保留账号、任务、原始请求与诊断记录，不改已成功任务的生成状态；查询可见 result_storage.state: "deleted" 与 deletion_reason: "expired" 或 "disk_pressure"，原下载链接返回 HTTP 410。访问链接不会延长保留时间。

已成功且没有缓存记录的历史任务保留原链接，不自动批量回填；历史上游链接仍可能过期。此处为账号池 Dreamina 成片的行为，其他渠道及非账号池直连入口不因本节说明而改变。

状态说明

待核实任务可在后台关联已查到的上游任务 ID 继续查询；确认上游未生成或明确拒绝本次请求后，也可填写原因并“核实为失败”，释放本地占用。该操作不会自动重新生成或换号。

Dreamina 的生成提交已开始，但本次提交以错误结束或响应中没有可用的上游 history_record_id 时，任务直接返回 status: "failed"，释放我方账号名额和积分预约并安排余额刷新；不会为这条任务自动重新生成或换号。明确积分不足仍保留账号异常及余额刷新处理，后续新任务继续按可用余额调度。

管理员诊断区分“上游明确业务拒绝”和“尚未取得有效 ID、受理结果未知”。后者即使我方任务已失败，也不能据此认定上游一定没有受理或扣费；不把它自动记为退款或已证实的零消费。已经取得有效 ID、但随后回执文件或数据库保存失败的情况，继续保留原回执并核实原任务，不适用“未取得 ID 直接失败”。此次升级不批量更改历史待核实任务；进程崩溃且没有捕获到提交结果的恢复流程也继续保守核实。

业务错误与后台诊断

生成和查询业务接口的即时错误格式统一为固定 code、固定 message 和 UUID request_id。保留 request_id，供管理员定位服务日志；业务错误不返回上游原始错误码、平台名称、内部路径、堆栈或原始响应内容。

{
  "code": "INVALID_REQUEST",
  "message": "请求参数无效，请检查请求参数",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

常见即时错误：

已接受的任务在查询响应中继续使用字符串 error 和分类 error_code。新记录的 Dreamina 上游明确生成失败，error_code 保持 GENERATION_FAILED，error 使用 失败码：fail_msg fail_starling_message，例如 2053：OutputVideoCopyright The video may contain third-party content。说明保留上游原文，不翻译、不根据数字猜原因；平台名称、地址和凭据仍脱敏。缺少说明时返回 失败码：未提供具体错误信息，请联系管理员核实，缺少有效失败码时使用 UNKNOWN。后台任务及执行记录保存所选失败字段的脱敏诊断；不回查已结束的历史任务，不触发重新生成。

其他错误继续按下表处理；已知参数错误也可能使用对应的固定参数错误码。

查询未返回原任务记录、缺失状态、未知状态或明确成功但暂未取得成片地址时，任务保留原有生成记录，返回 STATUS_QUERY_FAILED / 任务查询结果待核实，请稍后继续查询或联系管理员，后台保存查询异常与脱敏结构摘要。后续只退避查询原任务，不因查询不明判定生成失败、释放生成名额或重新生成。明确失败即使缺少错误说明，也正常结束；只有可识别的正常处理中状态才清除查询错误。上游审核失败状态同样归入明确失败。

Dreamina 国际区图片、视频与音频上传时，经上传权限接口返回的 tiktokcdn.com 子域节点使用独立的可信加密 DNS；请求地址、Host、SNI及完整证书校验保持原样，解析失败不会退回系统 DNS。国内区和其他上传域名保留原路线，显式代理遵循原有优先级。客户素材下载、上传权限申请与确认的签名、生成提交与查询、成片转存以及其他渠道保持原逻辑。上传连接失败时，后台任务及执行记录保存 material_upload 阶段诊断，包括图片／视频／音频类型、节点域名、DNS模式、耗时和有界底层错误码；不保存请求凭据、签名URL或完整原始错误。此修复不自动重试上传、重新生成或重跑历史失败任务。

例如待核实响应仍是 status: "processing" / stage: "submission_unknown"，不是可以盲目重试的新请求失败。已有 task_id 时继续查询或在后台核实；管理员可凭 request_id、task_id 查看原始诊断。

仅业务错误字段使用上述公共约定。管理接口仍返回 POOL_ERROR 和原有经过 safeError 处理的详情，管理任务详情保留原始 error 和详细原因。模型的 provider、管理页面与请求参数保持原有约定；Dreamina 新转存成片使用上述中性签名链接，不表示其他响应字段也已隐藏平台信息。

7. PowerShell / curl 调用示例

将完整请求体保存为 UTF-8 编码的 video.json。把下面的密钥占位值和文件路径替换为实际值。

$env:JIMENG_API_KEY = "替换为你的POOL_API_KEY"
$requestId = [guid]::NewGuid().ToString()

# 保存此标识；同一请求重试时不要重新生成。
Write-Output $requestId

curl.exe "http://154.36.171.58:8001/v1/videos/international/generations/async" `
  -H "Authorization: Bearer $env:JIMENG_API_KEY" `
  -H "Content-Type: application/json" `
  -H "Idempotency-Key: $requestId" `
  --data-binary "@C:/requests/video.json"

查询任务：

$taskId = "替换为提交返回的task_id"

curl.exe "http://154.36.171.58:8001/v1/videos/international/generations/async/$taskId" `
  -H "Authorization: Bearer $env:JIMENG_API_KEY"

8. Python 调用示例

安装依赖：

pip install requests

提交并查询：

import time
import uuid
import requests

BASE_URL = "http://154.36.171.58:8001"
API_KEY = "替换为你的POOL_API_KEY"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

body = {
    "model": "seedance-2.5",
    "mode": "omni_reference",
    "prompt": "一只猫坐在窗边晒太阳，镜头缓缓推进。",
    "images": [],
    "audios": [],
    "videos": None,
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5,
}

# 每个新任务生成一次；同一请求重试时必须保留此值。
# 重新运行整个脚本会生成新的标识，请勿将其作为原任务的重试方式。
idempotency_key = str(uuid.uuid4())
print("请保存请求标识：", idempotency_key)

response = requests.post(
    f"{BASE_URL}/v1/videos/international/generations/async",
    headers={**headers, "Idempotency-Key": idempotency_key},
    json=body,
    timeout=60,
)
response.raise_for_status()

task_id = response.json()["task_id"]
print("任务ID：", task_id)

while True:
    response = requests.get(
        f"{BASE_URL}/v1/videos/international/generations/async/{task_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    result = response.json()

    print("当前阶段：", result.get("stage"))

    if result["status"] == "succeeded":
        print("视频地址：", result["data"][0]["url"])
        break

    if result["status"] == "failed":
        print("失败原因：", result.get("error"))
        break

    if result.get("stage") == "submission_unknown":
        print("提交结果需要在管理后台核实，请勿重复生成。")
        break

    time.sleep(15)

9. 使用注意事项

• 当前为 HTTP 服务，地址必须带 :8001。
• 使用服务密钥 POOL_API_KEY 调用；邮箱无需放入生成请求。
• 当前账号池只开放异步生成。
• 没有可用账号、积分不足或名额已满时，任务可能排队。
• 只有明确的上游积分不足拒绝才允许自动换号；网络超时不会盲目重提。
• 提交超时且未拿到任务 ID 时，可使用原幂等键和原请求体重试。
• 已有任务 ID 时继续查询该任务，不要重复创建。
• 视频 URL 可能过期，成功后应及时下载保存。
• 文档中的密钥、素材地址和任务 ID 均为占位值，需要替换。
• 示例代码执行提交请求会创建真实生成任务并可能消耗积分。

10. 实测记录

2026-10-02 使用原始完整提示词、4 张图片和 2 段音频，在指定美国区账号上完成 duration: 4 的真实生成验证。账号完成官网确认后，新任务一次提交成功，未换号。

• 视频轨：720×1280，H.264，4.016667 秒。
• 音频轨：AAC，4.063991 秒。
• 请求时长仍为 4 秒，媒体轨道及容器时长存在帧和音频编码尾部差异。
• 验收任务 ID：35a88569-3223-4d88-9c90-d2857319f707。
• 缺省、null、空白时长均已在线验证返回 HTTP 400，不创建生成任务。

本次实测验证了 4 秒请求；接口允许的 4～30 秒范围不代表每个时长都已逐一付费实测。

11. AKOOL Seedance 2.0

AKOOL 使用独立平台适配器，与 Dreamina 共用账号管理网站、持久队列、幂等和任务恢复。业务调用使用本服务的 POOL_API_KEY，上游 Token 由后台保存。

账号准备

• 在管理后台添加账号时选择 AKOOL。
• 从已登录 AKOOL 网页的浏览器开发者工具中打开 Application / 应用 → Cookies，复制名称为 token 的 Cookie 的 Value。只填写 Token 的完整值，不填写 token=，不粘贴整段 Cookie，也不增加 Dreamina 地区前缀。
• 邮箱可选，不需要地区。工作空间由上游身份接口识别，后台只读显示。
• 新账号默认并发 1，可在后台调整；按凭证健康和并发名额调度，不使用 Dreamina 的积分估算、积分预留和余额门槛。
• 后台显示上游剩余额度及付费、赠送、透支分项，点击“刷新额度”同时校验身份并查询余额。未知、0、小数和负余额分别按真实状态显示，不伪造余额。
• 账号健康与余额查询分开记录。普通余额查询失败保留上次成功值和余额时间，并单独显示失败提示；健康校验时间另列。余额为零或余额获取失败不会把有效账号标为失效，也不阻止其按并发名额调度。
• 同一工作空间的付费积分可能由多个账号共享，统计卡只显示 AKOOL 已查询账号数，不跨账号汇总额度；剩余及分项余额请看各账号记录。
• 相同 UID 的不同 Token 合并到同一账号，更新凭证保留其并发占用。编辑 Token 时必须属于原 UID；有关联未结束任务时不能切换工作空间。账号的平台归属固定。
• 有效 Token 的身份校验可能返回轮换 Token，服务会加密保存。过期 Token 的续期尚未验证；凭证失效时由管理员重新登录网页并更新。
• 临时网络故障、HTTP 403 / 500 等显示“健康状态未知，等待重试”，服务自动再次验证；只有明确认证失效时才提示更新 Token。

提交图片和音频参考

POST http://154.36.171.58:8001/v1/videos/generations/async
Authorization: Bearer <POOL_API_KEY>
Content-Type: application/json
Idempotency-Key: <本次任务的唯一标识>

{
  "provider": "akool",
  "model": "seedance-2.0",
  "mode": "omni_reference",
  "prompt": "让@图片1中的人物站在@图片2的场景中自然说话，音色参考@音频1。无字幕，无背景音乐，保留自然环境音。",
  "images": [
    { "url": "https://example.com/person.jpg", "role": "reference_image" },
    { "url": "https://example.com/background.jpg", "role": "reference_image" }
  ],
  "audios": [
    { "url": "https://example.com/voice.wav", "role": "reference_audio" }
  ],
  "videos": null,
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 4,
  "generate_audio": true,
  "web_search": false
}

替换素材 URL 为服务器可访问的真实地址。设置 images: [] 和 audios: []，并使用不引用素材的提示词，即为纯文字生成。生成请求不需要上游 Token、邮箱、地区或工作空间。

AKOOL 参数与素材规则

• @图片1 对应 images[0]，@音频1 对应 audios[0]，分别编号。
• 按原顺序上传全部素材，保留未引用素材和重复 URL；任何一项失败都不删除素材或重新编号后继续生成。
• 兼容已有请求的 mode: "pro" 和 input_type: "reference"，归一化为参考模式。channel 等旧字段不会透传给 AKOOL；新调用应使用上述标准字段。
• AKOOL 不接受 Dreamina 的 region 约定。本次暂不开放首尾帧、视频参考、Mini / Fast。
• seed、face_processing_mode、super_resolution_config 的非空值尚不支持；旧请求可省略或使用 null。

查询与恢复

GET http://154.36.171.58:8001/v1/videos/generations/async/<task_id>
Authorization: Bearer <POOL_API_KEY>

提交后保存本地 task_id，建议每隔 15 秒查询。成功视频地址继续读取 data[0].url，status 和 stage 的含义沿用第 6 节。AKOOL 无可用账号或无并发名额时排队，不因为缺少积分数据而阻塞。

任务持久化保存 AKOOL 上游任务 ID，调用方无需自己处理批次或上游轮询。account_id 或直传 Token 指定的是优先账号：任务仍在提交前排队、该账号暂不可用且 failover 未设为 false 时，可以分配其他 AKOOL 账号。请求提交后，AKOOL 明确拒绝时终止并释放本地名额，不自动换号；submission_unknown 时保留并发占用，不能盲目重提。后台关联 AKOOL 已核实任务时，填写 24 位十六进制任务 ID；Dreamina 的 history ID 仍使用数字。人工确认上游未受理或明确拒绝后，可以填写原因并核实为失败，释放本地占用。

同一幂等键和相同请求返回已有任务；不同平台或不同生成参数不能复用同一个键。同一请求重试时保持原键和原请求体。

兼容直传 Token

推荐在后台维护 Token。确需直传时，请求体仍须包含 provider: "akool"，并使用：

Authorization: Bearer <AKOOL_TOKEN>
X-API-Key: <POOL_API_KEY>
Content-Type: application/json

Token 不补 us- 等前缀。直传 Token 会验证并匹配/加入本服务账号池，作为优先账号；与 account_id 二选一。查询仍使用本服务的 POOL_API_KEY，业务响应不返回上游凭证。

验证范围

2026-10-06，在本次服务代码封装前，已用授权账号通过纯 HTTP 完成身份、模型配置、纯文字生成及图片/音频参考链路。参考案例保留完整原提示词，全部 6 张图片和 2 段音频按原顺序上传，包括未引用的图片 3 和音频 2；请求 4 秒、720p、9:16，成片 720×1280、约 4 秒，含 AAC 音轨。

以上是历史上游实测；本次账号池封装的单元、后台和数据库/队列验证使用虚构凭证及模拟上游，结果以本次验证记录为准。另已完成 AKOOL 余额接口只读验证；余额查询及其失败处理与生成提交分别验证，不创建视频任务。历史实测不代表所有分辨率、时长、比例、音色效果或真实 300 并发均已验收。服务没有新增价格承诺，也不把未知余额解释为零或无限额度。

Dreamina 官方成片与预览水印（2026-11-01修复）

Dreamina Seedance 2.5 成功后的结果使用原任务的官方下载接口 /mweb/v1/get_local_item_list，请求带 is_for_video_download: true；不会因历史查询已返回预览链接而直接保存预览。国际版同步路径、账号池轮询和过期源地址刷新使用同一规则。

系统核对原作品 ID、可用时的视频 ID以及明确的水印元数据，只取该生成作品的官方下载视频，不扫描参考素材、封面或任意 JSON 地址。已观察到的新账号预览为 watermark_type=3、logo_type=display_watermark_aigc；同作品官方下载为 watermark_type=1、logo_type 为空。管理员填写的订阅等级以及 CDN 域名均不是无水印证明。

生成已成功但官方下载暂不可用时，任务继续查询原记录，后台保存下载阶段的脱敏原因，不自动重提生成，也不静默返回带水印预览。平台未提供可核实的无水印下载时，不通过修改签名 URL、图像遮挡或视频重编码伪造无水印结果。

成片仍采用本服务中性签名链接、24小时保留及原清理规则。修复历史成片只补下载原生成结果，不再次生成；保留原任务 ID、链接、生成次数和原到期时间。历史账号的会话无效时，需要更新同账号会话后才能补下载。

OpenArt Seedance 2.5 调用文档

OpenArt 使用独立平台适配器，共用现有账号管理页面、异步任务、幂等键和任务查询。业务请求明确填写 provider: "openart" 与 model: "seedance-2.5"；省略 provider 仍选择 Dreamina，旧请求不会自动切换平台。

添加账号与凭证

在管理网站“添加账号”中选择 OpenArt。填写已登录官网 Cookie __Secure-next-auth.session-token 的完整 Value，仅填写值，不粘贴 Cookie 名称、Cookie: 或整段 Cookie。它是 NextAuth 会话凭证，不是 AKOOL 的 token，也不需要 Dreamina 地区前缀。

邮箱和备注用于管理，邮箱可选。默认并发为 1。工作空间用户 ID、团队 ID、默认项目 ID 和默认文件夹 ID 可选，保存时验证账号身份与资源权限：用户留空使用已验证账号；团队留空使用个人空间；项目留空选择可写默认项目；文件夹留空使用项目根目录。需要特定团队、项目或文件夹时先取得官网的对应 ID，再填写表单。

账号平台归属固定，不能在普通编辑中改变。更新 Cookie 或上下文时重新校验；有未结束任务时不能改变其查询依赖的上下文。有效会话的滚动续期与认证失效分开处理，过期会话无法恢复时重新登录官网并更新 Cookie。

批量导入每行一个会话 Cookie，或“邮箱 Cookie”，支持空格、Tab、英文逗号分隔，每批最多 50 行。批量导入使用个人空间及可写默认项目；其他上下文使用单账号表单配置。凭证在数据库加密保存，业务请求使用服务的 POOL_API_KEY。

提交视频任务

POST http://154.36.171.58:8001/v1/videos/generations/async
Authorization: Bearer <POOL_API_KEY>
Content-Type: application/json
Idempotency-Key: <本次逻辑任务的唯一标识>

Idempotency-Key 由调用方生成，例如 UUID。同一个任务网络重试使用同一个值；新任务使用新值。同 key 与不同参数冲突时拒绝，防止同一次任务重复入队。它不代表上游支持幂等，也不能让不明提交安全重发。

推荐使用 POOL_API_KEY，请求体填写 provider: "openart"，按需指定 account_id。兼容直传 Authorization: Bearer <会话 Cookie 或规范会话配置 JSON> 时，还需 X-API-Key: <POOL_API_KEY>；只复用后台已添加、Cookie 匹配且上下文一致的账号，不自动注册账号。第一次使用或更新 Cookie 时先在管理页面添加或更新，避免直传请求覆盖已选工作空间。直传凭证与 account_id 二选一；其他平台已有直传方式保持原状。

纯文字示例：

{
  "provider": "openart",
  "model": "seedance-2.5",
  "prompt": "晴日下午，一只猫缓慢抬头，镜头固定。",
  "duration": 4,
  "resolution": "480p",
  "ratio": "9:16",
  "generate_audio": true
}

图片与音频参考示例：

{
  "provider": "openart",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "让@图片2中的人物与@图片1中的猫互动，音色参考@音频1。",
  "images": [
    { "url": "https://example.com/cat.jpg", "role": "reference_image" },
    { "url": "https://example.com/person.jpg", "role": "reference_image" }
  ],
  "audios": [
    { "url": "https://example.com/voice.wav", "role": "reference_audio" }
  ],
  "videos": null,
  "duration": 4,
  "resolution": "720p",
  "ratio": "9:16",
  "generate_audio": true
}

替换素材地址为服务端可访问的地址。@图片1 对应 images[0]，@音频1 对应 audios[0]，各类型独立编号。每项素材都保留，包括重复和未引用项；上传失败不会通过删除素材改变编号。仅明确引用转换为上游素材 ID，其余提示词正文、空白和换行保留，关闭自动润色。

参数与首版边界

每次只生成 1 条视频。图片支持 JPEG、PNG、WEBP，单张最多 30 MB；音频支持 WAV、MP3，单段最多 15 MB，时长 2～30 秒，全部参考音频合计不超过 30 秒。实际图片尺寸、比例及元数据还需通过上游限制校验；配置项开放不代表全部组合已完成真实生成。

兼容既有 multipart image_file_1、audio_file_1 等图片和音频上传字段。同类型数组与旧字段不能混用。不接收内部 visualReferences，业务请求不能覆盖账号的工作空间、项目或文件夹。首版不开放 seed、自动润色和额外视频增强参数。

查询、恢复与错误

GET http://154.36.171.58:8001/v1/videos/generations/async/<task_id>
Authorization: Bearer <POOL_API_KEY>

保存提交返回的 task_id，每 5～10 秒查询一次。processing 表示处理中；succeeded 的 data[0].url 是成片；failed 返回固定业务错误与 error_code。提交结果未知时保留任务及可能占用，后台核实原任务，不换账号重提。OpenArt 上游任务 ID 为 20 位字母数字，后台关联已核实 ID 后只恢复查询。已获得上游任务 ID 的任务在 Worker 重启后只恢复查询。

业务错误继续使用项目固定 code、message、request_id，不透传上游平台详情；任务错误使用固定 error 与 error_code。管理员可查看安全脱敏后的原始错误。此处理仅隐藏错误，其他 provider 字段、模型列表、管理页面和结果域名保持现状。

额度与调度

“刷新额度”校验身份并查询所选工作空间的视频额度。OpenArt 当前可用视频额度按赞助、一次性、有效订阅月额度、试用额度的优先级选择一个字段，不把历史免费、图片额度或各类套餐相加。

页面展示该视频额度及来源，并分别记录健康校验时间、余额成功时间和余额错误。普通余额查询失败保留上次成功值和原成功时间；未知额度显示未知。余额查询失败或数值为零不改变有效账号的并发调度；明确认证失效要求更新 Cookie。同一工作空间额度可能共享，统计只显示已查询账号数，不重复累加。

验证范围

2026-10-06 的研究已验证登录身份、个人工作空间、额度字段选择、最小会话 Cookie 认证及有效会话的滚动续期，并完成 JPEG、WAV 上传与素材元数据读取。纯文字、1 张图片加 1 段音频的两条 4 秒、480p、3:4 真实任务均完成，各返回恰好 1 个完成状态的视频资源与 URL；上游保存的输入提示词与实际提交文本完全一致。模型页面和第一方协议提供参数边界证据，以上不代表所有组合或真实并发均已验证。

代码验收、真实素材上传和真实生成记录需分别记录。生产发布还需同步更新 API 与 Worker，备份数据库与原加密主密钥，并保持旧 Dreamina、AKOOL 任务及幂等记录兼容。

Sunra 网页 Video Gen 调用文档

更新日期：2026-10-09

本适配器使用 Sunra 网页会话和网页订阅积分，通过现有账号池提交及查询视频任务。请求必须明确指定 provider: "sunra"；省略 provider 仍选择 Dreamina。

当前真实验证：Creator 月付账号的身份与余额、纯 HTTP 文生视频提交及完成查询已跑通。6 秒、720p、16:9、生成音频的文字任务实际消耗 140 积分，其中每日额度消耗 20、订阅额度消耗 120。此费用只代表该次任务，不是其他参数组合的固定单价。

上传对照发现 Node 原生 FormData 与上游不兼容，返回 HTTP 500；改为显式构造浏览器兼容的 multipart 后，同一素材上传成功，且无需浏览器 User-Agent。该修复已纳入客户端。

已完成六条真实生成：文生、单首帧图生、双图参考、图片加音频、图片加视频、三图加两段视频加两段音频。均为 6 秒、720p 档位，均在网页历史中匹配了原 taskId 和 batchId。首尾双帧尚未真实验收。生产部署版本与上线验收结果以 docs/sunra-deployment-verification.json 为准。

添加账号

管理后台选择 Sunra，填写 Cookie ponpon_session 的值，或登录助手导出的会话 JSON。不需要地区、工作空间、项目 ID 或开发者 API Key。登录助手读取 Sunra 域名范围内的 ponpon_session 和可选的 ponpon_refresh，由服务端验证真实身份后加密保存。

账号按身份去重，任务绑定经验证的账号。余额显示上游可用总额和订阅、每日、奖励、充值分项，不将分项再加到总额。未知余额不显示为零；普通余额失败保留上次成功快照。新增账号默认并发 1，管理员可编辑；当前 Creator 账号已核实上游视频与总并发上限均为 15。仅修改并发或备注不重新提交未变更的会话。采用并发调度，不套用 Dreamina 的费用预留规则。

会话刷新成功后必须再次验证身份，禁止刷新时切换到另一个账号。刷新恢复过期会话的真实验收尚未完成，不能据此承诺长期免重新登录；明确失效时由管理员更新会话。

提交与查询

POST /v1/videos/generations/async
Authorization: Bearer <POOL_API_KEY>
Content-Type: application/json
Idempotency-Key: <本次逻辑任务的唯一标识>

{
  "provider": "sunra",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "云海环绕雪山，镜头缓缓推进，远处古建筑清晰可见。",
  "duration": 6,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true
}

保存返回的本地 task_id，调用 GET /v1/videos/generations/async/{task_id}，使用相同服务 API Key 查询。成功时取得 data[0].url。每个新任务使用新幂等键；原请求网络重试保留原键与原请求体，同键不同请求返回冲突。

图生视频与首尾帧

图片作为首帧时使用 first_last_frames；一张全能参考图仍是参考模式，不自动转成首帧。

{
  "provider": "sunra",
  "model": "seedance-2.5",
  "mode": "first_last_frames",
  "prompt": "保持首帧布局，云雾自然流动，镜头缓缓推进。",
  "first_frame": "https://example.com/scene.jpg",
  "duration": 6,
  "resolution": "720p",
  "ratio": "16:9"
}

可选 last_frame。第一方路由为 Seedance 双帧使用 adaptive，因此双帧请求必须明确使用 ratio: "adaptive"；省略比例时该模式选择 adaptive。首尾帧不能混用 images、videos、audios。

全能参考

{
  "provider": "sunra",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "让@图片2中的人物站在@图片1的场景中，运镜参考@视频1，声线参考@音频1。",
  "images": [
    {"url": "https://example.com/scene.jpg", "role": "reference_image"},
    {"url": "https://example.com/person.png", "role": "reference_image"}
  ],
  "videos": [{"url": "https://example.com/motion.mp4", "role": "reference_video"}],
  "audios": [{"url": "https://example.com/voice.mp3", "role": "reference_audio"}],
  "duration": 6,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true
}

替换示例地址为可访问素材。沿用 multipart image_file_1、video_file_1、audio_file_1、first_frame、last_frame 等字段。同类型数组与旧字段不能混用。

@图片1、@视频1、@音频1 按各类型独立编号，转换为网页的 @Image1、@Video1、@Audio1；其余提示词、空白、换行保持原文。重复及未引用素材保留，素材准备失败不会删去对应条目或重新编号。

参数和素材边界

resolution 接受 480p/480P/数字 480（720、1080 同理），统一为小写 480p/720p/1080p。ratio 的全角冒号会转换为半角，例如 9：16 → 9:16。等价写法在保存和幂等比较前统一，不影响提示词。比例仍使用 ratio 字段，本次没有增加字段别名。

图片宽或高超过 6000 像素时，生成等比缩小的上传副本，保留完整画面及 PNG 透明通道；符合要求的图片保持原字节，原文件和原链接不改变。原始图片总像素上限为 6400 万，输入和输出均受 20MB 限制。宽高比不符合 0.4～2.5、最短边不足 300 像素、损坏或超出输入安全上限的图片明确报错；超限多帧图片暂不自动处理。后台任务详情显示图片处理前后的尺寸和字节数。

视频尺寸、比例、帧率继续校验，本次不增加自动截取或转码。素材顺序、重复项及未引用项继续保留。本地测试的两段 14 秒视频是明确创建的独立副本，原文件没有改变。

内部 apiModelId、settings、feature、cost、projectId、上传令牌等字段不能由业务调用方覆盖。暂不开放自动润色、web_search、seed 和额外增强参数。

错误、恢复和验收

素材准备完成后，服务先持久化提交边界，再请求上游。取得有效上游 taskId 后只查询原任务；网络异常或不明确回执保留 submission_unknown，不能自动换号重提。Worker 重启复用现有回执。管理员核实的 Sunra taskId 可以通过现有后台关联恢复查询。

普通业务错误沿用固定文案和错误码；管理员任务详情额外显示持久化的上游原始 JSON 与诊断信息。上游 error 为 JSON 字符串时保留其字符串类型，并提供解析阅读视图。任务与执行尝试分别保存诊断快照，业务生成及查询接口不返回这些字段。诊断中的 Cookie、Token 和签名 URL 脱敏，原始正文有受控大小限制。新凭证与已有账号身份不一致时拒绝更新。

上游历史 effectCost 仅表示记录费用，不单独作为最终实扣或退款证明；缺少逐笔退款流水时，退款状态为未知。本次不增加自动重新生成或后台重试入口，收集 retryable 等原始字段仅用于管理员诊断。

本地 HTTP 测试验证了路由、认证、参数、任务 DTO 与幂等，但使用隔离的模拟仓库；没有把它当作真实 MySQL/Redis 恢复验收。长期会话续期、首尾双帧、全部规格、真实并发、完整数据库恢复及生产发布仍需分别完成验证。

单首帧图生此次输出为 1276×722，其他已检查样例为 1280×720；图生的 720p 是上游分辨率档位，本适配器不通过事后裁剪或重编码改变结果尺寸。

ElevenLabs 视频 API

ElevenLabs 使用已登录网页账号的会话，接入项目现有异步接口与统一账号池。首版模型为 seedance-2.5，上游网页模型标识为 bytedance-seedance-v2.5-us。省略 provider 仍选择 Dreamina。

账号与登录环境

后台选择 ElevenLabs，填写登录会话 JSON 并验证保存。为复用管理接口，凭证字段名仍为 session_cookie，内容为 Access Token / Refresh Token JSON，并非 Cookie。登录助手的 ElevenLabs 环境从官网读取该会话，由服务器验证真实账号和工作空间；更新会话保留原账号的并发设置。

只有 Access Token 时，失效后需要重新导入。包含有效 Refresh Token 时，服务器通过平台使用的 Firebase 项目续期，再核验原绑定身份。凭证在账号池加密保存，不进入任务参数、公开接口、诊断或日志。

账号并发默认 1，可在后台修改。该值是本服务调度设置，尚未测得上游套餐实际并发上限。首版仅接入已验证的 api.us.elevenlabs.io 网页会话，不接受自定义请求域名或地区。

统一异步接口

提交：POST /v1/videos/generations/async。查询：GET /v1/videos/generations/async/{task_id}。使用项目服务 API Key；无需让调用者直接持有网站会话。

{
  "provider": "elevenlabs",
  "model": "seedance-2.5",
  "prompt": "海边日落，海浪轻轻拍岸，镜头缓缓推进。",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": true,
  "mode": "text_to_video"
}

可使用 account_id 指定已管理账号。建议提供 Idempotency-Key；同一个业务请求重试使用同一个 key。每个任务只生成一条视频，服务器不自动重试失败生成，也没有新增重试按钮。

三种生成模式与默认视频

text_to_video：纯提示词，服务器自动附加默认黑色视频。

image_to_video：图片作为参考，与默认黑色视频一起提交。通过 images 数组或 image_file 等 multipart 字段传入图片。

omni_reference：支持图片、视频、音频混合参考，同样附加默认黑色视频，也是省略 mode 时的默认模式。

默认视频不能关闭；上传后按已验证账号、工作空间和文件哈希缓存，跨工作空间不能共用素材 ID。用户素材顺序、重复项和未被提示词引用的素材均保留。默认视频追加在用户视频之后，不改变用户 @视频1 等引用编号。

首尾帧模式与视频参考互斥，因此 first_frame、last_frame、first_last_frames 不支持。需要图片参与时请使用图片参考，不会静默把首帧请求改为其他模式。

{
  "provider": "elevenlabs",
  "model": "seedance-2.5",
  "prompt": "以@图片1为外观参考，镜头平稳移动。",
  "images": [{"url": "https://example.com/reference.png"}],
  "duration": 4,
  "resolution": "480P",
  "ratio": "9：16",
  "mode": "image_to_video"
}

示例图片 URL 需替换为实际可公开访问的素材地址。支持标准编号引用 @image_file、@image_file_1、@图片1、@Image1，视频、音频同理；不存在的引用会在入队前拒绝。服务器仅在发送给 ElevenLabs 的提示词前追加 生成 {最终比例} 的视频，，再把必要引用转为上游媒体引用对象。用户原文、换行和空白保留，不自动润色；任务记录及幂等判定继续使用原始提示词。上游实际提示词及展示提示词使用同一份带前缀内容，且不改变用户素材编号。

例如 ratio=9:16、prompt=以@图片1为外观参考。 的上游文字顺序为 生成 9:16 的视频，以@图片1为外观参考。，其中素材标记仍会转换为对应媒体引用。固定比例覆盖 21:9、16:9、4:3、1:1、3:4、9:16；缺省比例使用 16:9。前缀与原文合计最多 10,000 字符，超长直接拒绝，不截断原文；adaptive 在解析出具体比例后、上传素材前完成该校验。

参数与素材限制

duration：4～30 秒整数。resolution：480p、720p、1080p；兼容 480P、数字 480 等写法。ratio：21:9、16:9、4:3、1:1、3:4、9:16、adaptive，兼容全角冒号。generate_audio 默认为 true。

上游带视频参考时使用自动比例。服务器为指定比例选择对应的默认黑色视频副本，原始默认视频保持不变。有用户视频时，首个视频决定比例：其比例需与显式 ratio 一致，否则拒绝；adaptive 按首个视频选择对应黑色视频，没有用户视频时选 16:9。提示词前缀使用这个最终解析出的具体比例，不会写入 adaptive。前缀是额外引导，实际输出尺寸仍需真实生成验收。

最多 30 张图片、9 个用户视频、10 个音频；第 10 个视频位置为默认视频保留。参考视频总时长含默认视频，不能超过 30 秒；参考音频总时长独立计算，不能超过 30 秒。

当前支持静态 JPEG/PNG/WEBP 图片（30MB）、MP4/MOV 视频（100MB）、MP3/WAV 音频（15MB），单个任务处理后素材合计不超过 128MB。图片原始像素上限为 6400 万，边长超过 6000 时等比缩小，保留 PNG 透明度，不修改原素材。上述是本适配器当前输入约束，并非声明平台全部格式能力。

成片保存与服务器链接

生成成功后，服务器先登记成片保存任务并释放账号生成并发，接口暂时返回 status=processing、stage=saving，此时不返回上游视频地址。文件下载和 MP4 校验完成后才返回 status=succeeded，data[0].url 使用本服务地址，路径为 /v1/video-results/{task_id}/{signature}.mp4。链接支持 GET、HEAD 和单范围 Range；持有链接即可访问对应视频，请勿公开分享。

成片复用 Picsart／Heyoz 的保存队列和保留规则：保留单次下载 30 分钟的超时设置，默认全局下载并发 2，默认每个文件最多 2GiB。多平台共同使用这两个下载位置，等待保存不占账号生成名额。保存失败只处理原视频的下载，链接失效时仅核对原账号、工作空间和生成 ID，再查询原任务取得新链接；不会重新生成。

文件保存成功后保留 24 小时，每小时检查一次，正常情况下实际约 24～25 小时。磁盘空间不足时，按现有规则每批最多清理 100 个最接近到期的可清理视频，可能提前失效；正在写入或读取的文件受到租约保护。查询结果的 result_storage 提供保存、到期和清理状态；文件删除后任务仍保留生成成功记录，旧链接返回 HTTP 410。

提交前需配置有效的固定 HTTPS 公网服务地址和签名密钥，避免消耗生成额度后无法提供服务器链接。适配生效后新进入生成成功处理的任务使用上述流程；历史已经成功、但未登记转存的任务不自动补下载，其原有链接保持原样。

状态、费用与错误

上游提交回执包含会话 ID、迭代 ID和生成 ID，查询使用生成 ID。拿到有效回执后只查询原任务；提交超时或回执异常可能已经生成任务，保留 submission_unknown，不会换号再次提交。

额度来自工作空间订阅上限减已用量，后台显示剩余、上限和已用。不同账号在同一工作空间可能共享额度，不累计为独立积分来源。报价是估算，不等于实际扣费；未知额度不显示为 0，也不套用其他平台的每秒计费调度规则。

失败任务的脱敏原始 JSON 保存在管理员诊断中。对外保留项目原有统一错误格式。首次使用需本人在官网确认生成条款和使用政策；API 不代为确认。上游如果要求验证或拒绝请求，收集原始错误并停止，不绕过验证、不自动重提。

若视频已经生成，但服务器最终保存失败，任务会显示失败并返回 RESULT_DELIVERY_FAILED 原因，说明“视频已生成，但文件保存失败，请联系管理员处理”。这不表示生成本身失败或已经退款；不得因此自动创建新的生成请求。

验证状态

已通过网页真实提交取得任务 ID，默认视频上传及参考检查通过；该次任务最终 provider_moderation，官网显示未扣费。该结果证明了失败任务链路，尚未证明成功出片。独立 HTTP、账号池、登录助手和三种模式的验收记录随实现更新，不能把模拟测试当作真实生成次数。

Picsart 网页会员视频 API

更新日期：2026-10-21。本文描述 Picsart 渠道的本地接入契约；是否已部署、真实平台验收覆盖哪些组合，以独立验收记录为准。

Picsart 使用网页会员登录会话和会员积分。调用方通过现有统一接口选择 provider: "picsart"，模型填写 seedance-2.5。省略 provider 继续沿用原默认渠道。

账号管理和会话交接

后台选择 Picsart，使用登录小助手交接网页会员会话，或在已停止原浏览器同链续期后导入完整会话 JSON。管理接口凭据字段名为 session_cookie，内容是 JSON，并非单项 Cookie 或开发者 API Key：

{
  "access_token": "<CURRENT_ACCESS_TOKEN>",
  "refresh_token": "<CURRENT_REFRESH_TOKEN>",
  "expires_at": 2000000000000,
  "device_id": "<DEVICE_ID>",
  "app_authorization": "<DYNAMIC_WEB_APP_TOKEN>"
}

expires_at 是 Unix 毫秒有效期，示例只表示结构。应用身份随官网动态获取，不能把示例或历史捕获值作为固定密钥。服务器通过会员身份接口核实真实账号；账号列表不自动返回旋转凭据。支持上号人员权限的版本增加显式只读凭证接口，管理员和该账号所属人员可请求当前已确认、服务器托管且未过期的版本；读取不会续期或暂停接单，状态不明确时只返回异常说明，不回退到历史凭证。

首版每个会员只托管一个会话。重复导入同一会员更新原账号；修改并发可以保持凭据输入为空，保留服务器当前会话。存在未结束或受理未知任务时，不切换另一独立登录会话。并发为管理员在本服务配置的调度值，尚未测得 Picsart 官方并发上限。

已被替换、轮换或进入待核实状态的历史 Refresh Token 不允许重新导入，也不能用旧 Access Token 仍有效作为恢复依据。首版需重新登录采集新会话；未结束任务仍受原会话绑定约束。

登录助手使用自己的专用 Chrome 环境，被动观察第一方认证请求并读取当前 Refresh Token。首次导入前暂停该环境网络并关闭窗口，再发送服务器导入请求。服务器托管后的账号可在 1.0.8 小助手中“暂停并打开”：账号空闲且没有待核实的任务或续期时，服务器把最新会话独占交还原登录环境，浏览器联网前同步当前凭据。查看期间该号停止接单和服务器续期，其他账号照常运行。使用“关闭并交回”冻结窗口并交回最新会话，服务器核验原会员身份后恢复托管；原停用状态和并发配置保留。断网或助手崩溃不会自动把同一旋转链抢回服务器，应使用原小助手查询交接状态并继续交回。日常 Chrome 不受影响。本轮仅有合成环境验证，真实账号兼容性仍待验收。

交回期间断网导致 Access Token 过期，或身份核验明确失败时，可点击“核实交接 / 恢复”。助手先确认服务器仍由本机独占，再通过服务器递增交接版本，阻止旧核验请求迟到后激活；使用最新已保存的会话恢复原窗口，完成正常官网续期或修正登录后再交回。续期结果未知时不会重放旧 Refresh Token。

小助手 1.0.11 新增“重新登录恢复”，用于浏览器续期结果待核实且原窗口已经退出的情况。助手先确认该环境及其恢复目录下没有仍在运行的专用 Chrome，再持久保存恢复意图，调用管理接口 POST /admin/accounts/:id/picsart-handover/reauthenticate，正文为 {operation_id, client_id, epoch, browser_closed: true}。服务器核查同一交接所有权、在途任务、并发占用和续期租约后，递增交接版本，创建独立会话并隔离旧凭据。接口不返回旧会话；相同请求在恢复未推进时只确认同一次操作，不重复建立会话。管理员可以调用；支持 1.0.13 上号人员权限的服务器也允许有效上号码为本人所属、且在允许平台范围内的账号调用，仍需满足原交接所有权及上述安全条件。

恢复打开新的空白专用档案，保留原档案用于排查，不复制旧 Cookie、LocalStorage 或历史凭据。用户手工登录原会员账号并完成官网验证后，点击“关闭并交回”。服务器先加密保存新会话，再仅用 Access Token 核实会员身份；账号不匹配时继续暂停，不激活新会话。恢复窗口断网或助手重启后应继续使用该恢复档案；已经冻结的回交请求只查询或重发同一份候选，不能从旧档案重新取凭据。旧版本助手无法完成此恢复，应先退出旧助手并更新至 1.0.11。恢复不会自动启用管理员原本停用的账号，也不改变并发配置、历史任务或既有额度不足标记。

后台会员余额使用接口的 credits + addonCredits，tierCredits 是套餐分配量，不再次相加。查询失败保留最后成功快照及原时间；未知余额不显示为零。Picsart 新任务按管理员配置的消耗规则选号并进行本地额度预留，用于避免并发超额派单；预留不代表上游实际扣费、结算或退款，不新增调用方的充值或报价确认流程。

积分规则与多账号调度

管理员在“调度设置 → Picsart 积分规则”分别配置三档每秒积分系数，默认值来自本次用户指定规则：

无视频参考时，预计积分为 生成秒数 × 系数。有视频参考时，预计积分为 (ceil(全部参考视频实际总时长) + 生成秒数) × 系数：先合计所有参考视频，再统一向上取整，图片和音频不加入参考视频时长。例如 480p、参考视频总计 10 秒、生成 4 秒，预计积分为 (10 + 4) × 4 = 56；两条各 2.2 秒参考视频、生成 4 秒，则为 (ceil(4.4) + 4) × 4 = 36。同一视频出现在多个素材槽位时，各槽位计入总时长。

视频时长由服务器读取实际媒体获取，覆盖 videos 与旧的 video_file / 编号上传字段；调用方不能提供价格或时长覆盖计分结果。参考视频在账号分配前完成时长核实，提交前再校对实际使用的素材。时长读取失败不会按零秒继续提交。

系数支持最多四位小数，必须大于零且不超过 100000；留空保存为 null，表示该档未配置，对应任务等待规则配置。该配置独立于 Dreamina 的预计积分设置，保存后由所有 Worker 从数据库读取。每次价格变更带规则版本，分配任务时保存 pricing_snapshot，包括分辨率、系数、生成时长、参考总时长及取整结果、计分秒数和预计积分。未分配任务使用最新规则，已有预留、已提交及历史任务不因改价而追改；请求正文及幂等摘要保持原样。后台可查看任务价格快照，普通调用响应不返回内部规则和预留记录。

账号按当前任务预计积分与可分配额度筛选。每个账号分别比较，不能合计多个账号的余额；可分配额度已经扣除其他任务的积分预留，不能重复扣减。额度足够支付低消耗任务的账号仍可接这类任务，即使无法支付更昂贵的任务。

所有合规候选账号的可信可分配积分均不足时，任务直接变成 failed，不等待充值、积分恢复或在途任务释放预留，也不创建执行尝试、占用生成并发或调用上游生成。无视频参考的任务在入队时判断；有视频参考的任务先核实实际总时长再判断；分配时在事务内再次校验。积分足够但账号或全局并发已满时继续等待名额，并发满的账号仍纳入资金判断。指定账号、平台、服务器会话归属及视频历史资格限制继续生效；初始没有合法候选账号时仍等待可用账号，不伪称积分不足。

上游汇总余额、保守调度预算和未结算预留分别保存。保守预算已经按配置扣除预计费用，低于本次费用并不能独立证明上游余额不足；预算使用自己的对账时间，不因忙时余额查询成功而重新变新。诊断分别记录预算、独立余额观测、未反映占用、可用余额上界及各自时间。任务详情支持尚未分配账号的情况，账号为 null 时仍能查看价格、错误和原始诊断。

未知、过期、会话版本不符、正常续期暂态或待重新核对的余额不视作零，也不简单排除正常续期中的账号后宣布全部不足。没有可信足额账号时，每个任务最多开启一次 30 秒余额核实窗口，持久保存开始时间，Worker 重启及反复检查不延长窗口；账号级刷新租约和节流合并并发核实。没有充值等待或自动重新生成。已有可信足额账号时继续等待并发；核实后确认全部不足则立即失败；仍不能确认安全支用时以 CREDIT_BALANCE_UNVERIFIED 失败。

余额观测回写要求查询前后会话、epoch 与账本 revision 一致；期间新增分配或提交会使迟到观测失效。只扣明确未包含在观测中的未发送预留、观测后提交的预留，不能再次减去全部历史预计费用。旧数据缺少水位时按未知处理，不臆造扣费或退款记录。空闲时保留既有安全对账流程，忙时成功读取余额不直接增加调度预算。/guard/credits 当前只提供汇总余额，缺少逐任务扣费与退款流水，因此“上游余额足够但忙时旧预算不足”的情况仍可能在限时核实后失败；本版修正误报不足，不宣称已证明安全的忙时增额。查询非 2xx 的本地失败不作为退款证据，不自动加回预计积分。

后台保留预计积分、规则快照及本地准入原因 INSUFFICIENT_ACCOUNT_CREDITS / CREDIT_BALANCE_UNVERIFIED。普通调用方沿用任务失败响应及主码 GENERATION_FAILED，额外通过 reason_code 区分 GENERATION_CAPACITY_UNAVAILABLE（资源不足）与 GENERATION_SERVICE_UNAVAILABLE（资源状态暂未核实），不返回内部费用、账号数量或原始错误。失败任务即使后来充值也不自动恢复，同一幂等键继续返回原失败任务。本次规则仅作用于 Picsart，其他渠道沿用原调度逻辑。

有视频参考的任务额外排除曾明确返回 NOT_ENOUGH_AVAILABLE_CREDITS 的账号。该历史标记独立持久保存，普通余额刷新和重启不会清除；已有明确错误记录也纳入标记。无视频参考任务继续按可支付额度判断。规则只作用于新任务选号，已受理或提交待核实任务继续保持原账号、原上游 ID 和原执行尝试。

额度预留与选号在同一事务内处理，生成请求发出前再次核实，以防多个任务同时使用同一笔可分配积分。余额快照与本地在途记录分别保存，查询失败保留最后成功值；已有提交或待核实占用不会因普通余额刷新而重新释放。明确积分不足直接让当前任务失败，不自动换号或重生成。

提交和查询

使用服务调用密钥并指定后台已添加账号，或由 Picsart 账号池调度：

POST /v1/videos/generations/async
Authorization: Bearer <POOL_API_KEY>
Content-Type: application/json
Idempotency-Key: <UNIQUE_TASK_KEY>

文本请求：

{
  "provider": "picsart",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "一只猫坐在窗边，镜头缓缓推进，画面自然稳定。",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": true
}

图片、视频和音频参考使用现有素材字段，可按需提供一种或多种：

{
  "provider": "picsart",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "人物参考@图片1，动作参考@视频1，声音参考@音频1。",
  "images": [{ "url": "https://example.com/person.png", "role": "reference_image" }],
  "videos": [{ "url": "https://example.com/motion.mp4", "role": "reference_video" }],
  "audios": [{ "url": "https://example.com/voice.mp3", "role": "reference_audio" }],
  "duration": 4,
  "resolution": "480P",
  "ratio": "16x9",
  "generate_audio": false
}

以上混合示例说明请求结构，不表示该组合已经真实生成验收。素材地址需要替换成服务器可访问的真实 HTTP(S) 地址；素材会先上传至 Picsart。提示词原文、空白、各类素材顺序、重复项和未提及素材保留，不润色、不转换引用标记。Picsart 不自动附带 ElevenLabs 的黑色视频。

JPEG、PNG、WebP 图片在上传前读取实际媒体尺寸。超过最大边 6000 像素、总像素 3600 万或文件 30MiB 时，服务器在原格式内等比例缩小上传副本，不裁剪、不放大，也不覆盖原文件或 URL。未超限图片的上传字节保持原样。字节仍超限时最多进行 6 次受控缩小，失败则在生成提交前明确报错；需要缩小的多帧图片会被拒绝，避免丢失动画帧。原始图片解码安全上限为 1.28 亿像素，单素材及单任务原始素材总字节仍受本服务 100MiB 保护限制。本轮不新增最短边或极端宽高比的自动适配。

每个原图片槽位在后台保留 material_processing：处理动作，以及处理前后尺寸、像素数、字节数和 SHA-256。记录在生成提交前保存，提交响应丢失时仍可排查；记录不包含素材 URL 或会员凭据，普通调用方的响应格式保持原样。重复图片可以复用一次上传，原素材槽位和提示词引用顺序继续保留。

duration 必填，为 4–30 秒整数；duration: 0 明确拒绝。分辨率输入兼容大小写与数字形式，例如 480P、480；比例兼容 16x9、16X9、16：9，上游发送规范值。显式 generate_audio: false 保留。首版不开放首尾帧、自动时长 -1、视频编辑或其他模型。

分辨率允许 480p、720p、1080p，默认 1080p；比例允许 16:9、9:16、1:1、4:3、3:4、21:9，默认 16:9。这些选项有第一方源码依据，交接中的真实完成样本仅为 4 秒、480p。调用方应显式填写需要的分辨率。

素材数量等规则区分第一方源码证据与真实生成验收；当前不套用其他平台的限制，本轮未增加素材数量校验。账号 RPM 和最大并发尚无已核实规则。服务基础设施的请求体、下载字节及公网地址保护仍适用，其限制不代表 Picsart 官方限额。/options 仅在证实为上游提交依赖时使用，不引入本地报价确认或扣费流程。

提交响应取得本服务 task_id 后查询：

GET /v1/videos/generations/async/<TASK_ID>
Authorization: Bearer <POOL_API_KEY>

相同幂等键和归一化后相同请求返回原任务；同键不同请求返回冲突。提交发送后断连、超时或无法确认受理时，不自动换号或重新生成，保留提交待核实状态。

提交接口明确返回 HTTP 402、同一错误对象的 status: "error" 和 reason: "NOT_ENOUGH_AVAILABLE_CREDITS"，且响应不含任何可能的任务 ID 时，按可用积分不足直接结束本地任务并释放并发占用，后台保留原始符号原因。此分类不启用自动换号或重试，不改写历史待核实任务。裸 HTTP 402、其他错误、冲突回执及网络超时继续保留待核实；普通调用方沿用通用生成失败格式。余额快照不代表本次费用、扣费或退款凭证。

按管理员指定策略，Picsart 原任务结果查询收到任何实际 HTTP 非 2xx 响应（包括 3xx、401、403、404、422、429、5xx），均结束本地任务并在后台显示“异常”，停止该任务的自动轮询，释放本地并发占用。后台保存 HTTP 状态和安全的上游原因，例如 bytedance_output_audio_sensitive、invalid_text；非 JSON、空响应或响应读取失败也记录对应原因。查询异常表示本次结果查询失败，不证明上游任务已停止、生成失败或退款，原上游任务 ID 会保留；不自动重新生成。401 / 403 仍会按账号凭据版本检查暂停未获授权的账号。

未收到实际 HTTP 响应的连接断开、超时，以及 2xx 回执尚不能确认结果的情况仍保留查询待核实。该策略仅作用于 Picsart 任务结果查询，不改变提交、登录、续期和素材上传的处理；其他平台沿用原规则。对普通调用方保持 status: "failed" 和原有 error_code，可识别原因以中性 reason_code 及固定中文提示补充，不透出 HTTP 原因或上游错误文本；未知查询异常使用 TASK_RESULT_UNVERIFIED，不推断已生成、未生成或扣费结果。

{
  "status": "failed",
  "error_code": "GENERATION_FAILED",
  "reason_code": "OUTPUT_AUDIO_CONTENT_REJECTED",
  "error": "输出音频未通过内容审核，请检查提示词或参考素材"
}

视频保存、下载链接与清理

本次更新后的新 Picsart 任务，上游完成后先进入 status: "processing" / stage: "saving"，释放会员生成并发，再由独立下载队列保存成片。服务器文件完整落盘后才返回 status: "succeeded"，data[0].url 为服务器 HTTPS 签名链接，路径统一为 /v1/video-results/{task_id}/{signature}.mp4。历史已登记缓存视频在查询响应中转换为中性路径，复用原文件和签名，不改数据库原链接、不重新下载，也不延长保留时间；无缓存记录的外部结果不自动迁移。旧带平台路径继续按原有效期使用。

部署时 API 和 Worker 必须使用相同的 POOL_PUBLIC_BASE_URL（例如 https://api.example.com）、加密密钥和结果持久卷；缺少有效 HTTPS 下载地址时，在提交生成前拒绝新 Picsart 请求。成片放在 POOL_DATA_DIR/results/picsart，默认每个文件最多 2 GiB，下载并发 2。链接支持 GET、HEAD 和单范围 Range；链接本身授予该视频的访问权限，不要公开分享。

从文件保存完成起计 24 小时，每小时批量检查删除，正常文件实际保存约 24～25 小时。可从查询响应的 result_storage.saved_at、expires_at 查看毫秒时间戳。空间不足允许提前清理，保留 24 小时不构成硬性保证：默认可用余量扣除正在保存的预留空间后低于 10 GiB，先删已过期视频，再按到期时间从早到晚，每批最多 100 个（不足 100 个清理剩余可清理项），每批后重新检查，直到目标余量 20 GiB 或无可清理项。阈值通过 POOL_RESULT_MIN_FREE_BYTES、POOL_RESULT_TARGET_FREE_BYTES 调整。

清理只处理已登记的 Picsart 成片和失效临时文件，保护仍在写入或读取的文件，保留账号、任务、原请求和诊断记录。删除后任务仍为生成成功，result_storage.state 为 deleted，deletion_reason 为 expired 或 disk_pressure，旧链接返回 HTTP 410。后台显示对应清理原因。服务器停止期间不会执行检查，恢复后补扫。

下载失败只重试保存，签名地址失效时只查询原上游任务获取新地址，绝不重新生成。保存连续失败达到限制后，后台明确区分“已生成但服务器保存失败”；对外沿用 GENERATION_FAILED 主码，增加 reason_code: "RESULT_DELIVERY_FAILED" 和固定中文提示。磁盘所有可清理视频删除后仍不足时同样明确记录保存失败。其他可识别的审核、文本、参数、素材异常同样使用中性细分原因，完整码表见统一号池调用说明；后台继续保留原始原因。

验证范围

交接记录中的文本、单图、单音频已真实完成，视频参考只确认受理及处理中；五图加两音频仅上传和报价成功。它们属于历史协议证据，不能作为本项目新增生成次数。视频原任务应查询已有 ID，不重新提交。

本轮使用本地合成素材、模拟上游和独立数据库验证积分规则与调度，不新增真实付费生成；部署状态以对应发布验证记录为准。真实成功出片、视频参考终态、图/视频/音频混合效果、完整取消和审核状态、长期续期、服务器出口、结果地址有效期及退款规则仍需分别验收。模拟响应、数据库测试、HTTP 验证与真实平台结果必须分开记录。

第一方构建源码显示，x-app-authorization 来自网页构建配置，会员续期不会更新该值。小助手捕获当前网页使用的应用头；后台尚未实现跟随官网新构建自动更新应用身份，长期有效性仍待验收。当前默认生成链路未调用 /options，不依赖该步骤能否被上游接受仍需真实协议验收。

Heyoz Seedance 2.5 接入

Heyoz 调用方式

使用现有异步接口，生成请求明确填写 provider: "heyoz"、model: "seedance-2.5"，认证仍为本服务 API Key。旧调用的默认渠道保持不变。每次只生成一条视频；提交后保存 task_id，查询原任务，不因请求超时重复生成。

{
  "provider": "heyoz",
  "model": "seedance-2.5",
  "mode": "text_to_video",
  "prompt": "清晨山间云雾缓缓流动，镜头平稳推进",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": false
}

提交：POST /v1/videos/generations/async。查询：GET /v1/videos/generations/async/{task_id}。建议为同一逻辑请求使用相同 Idempotency-Key；同键不同参数会被拒绝。

Heyoz 模式和参数

文生不带素材。图生使用一张首帧或两张首尾帧，可用 images 数组或 first_frame、last_frame 字段；尾帧必须有首帧。全能参考使用 images、videos、audios，不能与首尾帧混用。也支持既有 multipart 的 image_file_1、video_file_1、audio_file_1 等字段。

{
  "provider": "heyoz",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "参考@图片1的场景和@视频1的运动，使用@音频1作为氛围参考",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "images": [{"url": "https://media.example.com/scene.jpg"}],
  "videos": [{"url": "https://media.example.com/motion.mp4"}],
  "audios": [{"url": "https://media.example.com/mood.mp3"}]
}

提示词只转换必要的素材引用，保留其他文字及空白，明确关闭自动润色。不会附加默认黑色视频或品牌描述。

图片最多30张、视频10条、音频10条，合计50份。视频及音频每段2～30秒，同类总时长不超过30秒。图片处理后最大20MiB，视频100MiB、音频25MiB；图片支持静态JPEG、PNG、WEBP，超限时等比例压缩，不能处理的素材明确报错。上传完成后还需通过平台素材核验，未通过不会提交生成。

图片原始解码保护上限为2亿像素，原图文件读取仍受本服务64MiB保护；这与上传副本的20MiB限制分开。超出上传范围的静态图片在上传前从原图等比缩到最长边6000以内，必要时有限轮次继续减小体积，不裁剪、不放大；JPEG、PNG、WEBP保持原格式，透明通道保留。符合范围的图片保留原字节，原文件及引用顺序不变。大图处理限制并发；超过解码保护、损坏、多帧或无法缩到目标范围的图片明确报错。后台记录处理前后尺寸、像素、体积和摘要。

以上参数范围来自当前前端和本地校验。真实验收覆盖480p、4秒、16:9、关闭生成音频的三种模式；其他档位及组合没有全部实际生成过。

Heyoz 账号和积分调度

通过小助手1.0.15的Heyoz专用登录环境导入，或后台填写会话JSON。凭证只包含所需登录Cookie及已验证的账号、品牌上下文，服务器加密保存。单品牌自动识别；多品牌须指定 product_id。业务生成请求不能覆盖品牌或认证信息。

会话有效时，接收官网返回的新Cookie，更新受身份校验和版本检查保护。过期会话需要重新登录，不承诺无需登录即可无限续期。账号在途任务的品牌绑定不能更换。

tokTokens 是当前总积分，purchasedTokens 已包含其中，不能再叠加；套餐上限也不计入余额。查询失败保留上次成功值和时间，不把未知余额当零。

预计积分＝生成时长×对应系数；参考视频素材时长不叠加。默认系数由管理员确认，可在调度设置修改并按版本保存。本服务仅做账号池和预算调度，不新增充值或用户扣费系统。

分配任务时在事务中预留积分。为避免上游已扣费余额和本地预留重复相减，账号存在在途生成时不覆盖预算余额；任务结束后刷新。所有合规账号的可分配积分均不足时立即失败；余额过期或未知时先核实；有足够积分但没有空闲并发时等待名额。明确失败不自动重新生成，未知提交保留占用并等待核实。

Heyoz 成片保存和清理

上游生成完成后进入服务器保存阶段，下载及校验成功后才对外返回成功，结果为本服务器 /v1/video-results/{task_id}/{signature}.mp4 中性签名链接，支持GET、HEAD和Range。历史缓存视频查询同样返回中性路径，旧带平台路径继续按原有效期使用，不改文件、消费或过期时间。后台可区分生成失败和“已生成但保存失败”，后者对外保留 GENERATION_FAILED 并增加 reason_code: "RESULT_DELIVERY_FAILED"；保存重试仅下载原视频，不重新生成。

与Picsart共用存储维护：每小时清理保存满24小时的成片；磁盘不足时按最接近过期的顺序每批清理100条，保护正在下载或读取的文件。过期清理后链接返回410，任务及错误记录仍保留。旧Picsart链接及其签名保持兼容。

Heyoz 本次真实验收

2026-10-23北京时间完成文生、图生和图/视频/音频全能参考各一条，均480p、4秒、16:9、关闭生成音频。积分542→538→534→530，共消耗12积分；三条均完成出片并已实际下载、校验MP4及206分段读取。查询使用提交回执的 creationId，不能使用另一个提交标识 id。

研究、验收记录中不保存真实凭证或私人素材签名链接。长期会话、平台并发上限、其他分辨率实际扣费、退款及上游链接寿命仍需后续观察。

ModelFlare Seedance 2.5 API

接入范围与验证状态

本渠道使用 ModelFlare 官方 API Key，通过现有账号池提交和查询任务。2026-10-30 的首次接入已经完成图片、MP4 视频及 WAV 音频全能参考的上游真实生成和本地下载，并在发布时验证了服务器转存与公网下载。文生视频、图生视频按用户要求未做真实生成。本轮将 URL 参考素材改为由 ModelFlare 自行拉取；新 URL 路径在生产服务器的完整成片交付仍待验收，真实 URL 入库结果和发布状态以本次验证记录为准。

首次真实验证使用的是由我方上传文件字节的旧素材路径，仅提交一次生成，参数为 480p、4 秒、关闭生成音频，三份素材均确认 Active 后提交。下载文件经 FFprobe 核实为 854×480、24fps、4.041667 秒、617359 字节；上游返回 completion_tokens = total_tokens = 67652，实际金额未核实。这些数据仅代表原路径的本次样本，不能换算成固定每秒价格，也不能作为 URL 自行拉取路径或其他档位已经真实出片的证明。

生成请求填写 provider: "modelflare"、model: "seedance-2.5"，使用本服务的调用密钥；ModelFlare API Key 仅由管理员保存在账号池，不放入业务请求、素材 URL 或对外结果链接。该渠道不使用 Chrome 登录环境。

• 提交：POST /v1/videos/generations/async。
• 查询：GET /v1/videos/generations/async/{task_id}。
• 同一逻辑请求建议使用固定的 Idempotency-Key；同键不同参数会被拒绝。
• 保存提交返回的本服务 task_id，后续查询原任务；连接中断或受理结果未知时，不重复提交生成。

账号与计费

后台添加账号时，选择 ModelFlare，填入完整 sk-... API Key，或以下 JSON：

{"api_key":"sk-替换为完整密钥","base_url":"https://origin.modelflare.dev"}

新建条目时，默认网关为 https://origin.modelflare.dev；管理员也可显式配置官方主源 https://modelflare.dev。条目创建后固定绑定该 API Key 和网关，编辑界面中凭证只读、可复制；如需更换 Key 或网关，必须新增账号条目，不能替换原条目。本服务尚不能证明不同 Key 或不同网关属于同一个钱包，不能把这种更换视为同账号续期。原任务的执行、查询与成片下载继续绑定原 Key、原网关，不自动换域。业务请求不能覆盖 API Key、网关或账号资产组。

ModelFlare 按其 Token 规则计费，不能套用 Picsart 或 Heyoz 的“每秒积分”系数。当前尚未核实可供本服务使用的余额查询接口，因此后台显示“余额未知”，不把未知值记作零，也不承诺预先判断余额是否足够。后台“验证密钥”仅核实鉴权和模型权限，不代表已核实余额或真实生成能力；本服务不新增充值功能。

参数

每次生成一条视频，不接受地区参数、编辑或续写模式。图生视频的首尾帧模式必须显式设置 ratio: "adaptive"；若希望保留指定横竖比例，可使用图片全能参考模式。

文生视频

文生视频不传参考素材，也不会自动附加黑色视频。

{
  "provider": "modelflare",
  "model": "seedance-2.5",
  "mode": "text_to_video",
  "prompt": "清晨山间云雾缓慢流动，镜头平稳推进",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": true
}

图生视频

使用一张首帧或两张首尾帧图片；尾帧不能单独提交。也可用 images 数组依次提供一张或两张图片；首尾帧不能混用其他参考图片、视频或音频。

{
  "provider": "modelflare",
  "model": "seedance-2.5",
  "mode": "image_to_video",
  "prompt": "场景缓慢移动，光线自然变化",
  "duration": 4,
  "resolution": "720p",
  "ratio": "adaptive",
  "first_frame": "https://media.example.com/first.png",
  "last_frame": "https://media.example.com/last.png"
}

全能参考

通过 images、videos、audios 提供公网 HTTP(S) 素材 URL，或使用既有 multipart 的 image_file_1、video_file_1、audio_file_1 等字段。同类素材不要同时使用数组和旧字段。全能参考至少需要一份素材，不能与首尾帧字段混用。

URL 参考素材由平台拉取

新 URL-only 任务先把原始参考地址按顺序放入视频请求的 content[]，图片、视频和音频均由平台自行拉取。我方不向素材地址发起 GET、HEAD 或 DNS 探测，不下载或解码参考文件，不为了选择路径进行人脸检测。

首次视频创建返回可解析的 HTTP 400／422 错误，且没有任何生成回执或受理信号时，直接检查错误文字中的 content[n]。不要求固定的人像报错文案或特定错误码：存在有效的原始图片位置时启动一次指定图片纠正；没有有效图片位置时，当前任务直接失败，不继续挂在待核实。

1. 根据实际发出的 content[n] 定位图片项，不根据用户侧 images 数组直接猜下标。当前 content[0] 为提示词，content[1] 对应图片 1。 2. 只将错误明确指出的图片交给 CreateAsset，保存原组和原 ID，继续沿既有节流、批量审核和持久恢复逻辑等待其全部 Active。 3. 仅替换这些项的 image_url.url 为 asset://<ID>。其余图片、视频、音频的原 URL、角色、位置、提示词和生成参数保持不变。 4. 在同一业务任务、同一账号与同一 attempt 中记录首次明确拒绝和第二次提交边界，再发送一次更正后的创建请求。最多触发一次纠正；第二次仍明确拒绝时直接失败，即使错误中出现新的 content[n] 也不继续入库或第三次创建。

例如上游指出 content[2]、content[3]、content[4]、content[7]、content[8]、content[9]、content[10]，则仅准备图片 2、3、4、7、8、9、10；图片 1、5、6 和音频仍使用原 URL。请求索引必须有界、对应图片、仍为直接 URL，重复索引合并；文字、音视频、越界位置或已经是 asset 引用的项目不授权纠正。

只有普通单词 content、缺少数字索引、索引指向文字／音频／视频、超出原请求范围，均不构成图片纠正许可；明确的 HTTP 400／422 拒绝直接失败。提取只读取真正的错误字段，不使用回显请求、提示词或 URL 中的索引片段。超时、网络中断、429、5xx、非 JSON、已受理后异步失败或带任何生成回执时，仍不能据此重新创建任务；受理不明仅在后台核实。入库也不保证素材获准使用，最终仍以平台审核为准。首次拒绝的实际计费规则尚未真实验证，本服务不据此承诺该 HTTP 请求绝对不产生任何平台费用。

• 保留原 URL 的查询参数、签名、转义和顺序，不截断或重新排序；重复素材仍保留为独立输入，提示词保持原文。
• 链接需允许 ModelFlare 从公网直接读取，且有效期覆盖排队、平台拉取和审核。需要我方 Cookie、专用请求头或局域网访问的地址不适用。
• URL 模式不进行我方自动缩图、格式转换或时长预检。素材超出平台限制、链接失效或平台读取失败时，后台保留平台返回的错误；不会自动切回下载中转。第二次创建仅限上述明确的指定图片纠正。
• 准备回执绑定原 Key、网关、本次任务提交 ID、素材位置和原 URL 摘要。同任务恢复复用原准备结果；不同任务不会仅凭同一 URL 复用旧资产，避免地址内容更新后仍使用旧素材。回执缓存不保存原 URL、签名参数或密钥，任务参数仍保留原输入用于幂等与恢复。

包含任意 multipart 二进制文件的任务继续兼容原有整单素材库路径：文件先进入我方临时上传目录，再校验和上传，可能进行图片等比缩放。已开始的旧素材库任务沿用原组、原 ID 和原期限，不在升级中改为直传。因此“参考文件不经过我方服务器”的保证只适用于 URL 输入。生成后的成片继续按原规则下载到我方服务器，保留与清理规则不受本次输入路径调整影响。

{
  "provider": "modelflare",
  "model": "seedance-2.5",
  "mode": "omni_reference",
  "prompt": "保留参考场景的构图，使用参考运动和音频氛围，镜头平稳推进",
  "duration": 4,
  "resolution": "1080p",
  "ratio": "9:16",
  "images": [{"url": "https://media.example.com/scene.png"}],
  "videos": [{"url": "https://media.example.com/motion.mp4"}],
  "audios": [{"url": "https://media.example.com/mood.mp3"}]
}

提示词中的文字、空白、换行和 @图片1 等标记按原文保留；本渠道不会把这些标记改写为其他平台的引用结构，不自动润色或追加比例前缀。素材仍按请求顺序与类型绑定，重复输入不会被静默删除。

需要入库的参考素材进入原账号和原网关下的资产库；本服务在核验资产 ID、资产组和类型后，仅使用审核状态为 Active 的素材替换对应引用。Processing 继续有限等待，失败或未确认状态明确报错，不绕过审核。真人验证流程未接入，不能通过本 API 完成或绕过平台要求的真人认证。无法满足验证要求的素材请更换。

素材接口限频与审核等待

素材组创建、素材入库和审核查询共用服务端节流。相同 API Key 的不同账号记录、不同进程及官方网关别名共用 Key 限制；同网关还有总请求间隔和在途限制。分组使用密钥摘要，节流表不保存明文密钥。下列默认值是本服务的保守设置，不代表平台公布的配额：

HTTP 429 按 HTTP 状态识别，即使响应是 HTML 或空正文也不会误报为 JSON 解析失败。有有效 Retry-After 时至少等到指定时间；没有时按 30、60、120、240、300 秒退避。有效 Retry-After 超过本地退避上限时不会被缩短；超过本任务总期限则当前任务明确失败且不提交视频。无法表示的超长 Retry-After 会保守阻断该 Key 的后续素材操作，需管理员核实，不会修改账号启停状态或扣减额度。

参考输入支持 30 张图片、10 段视频和 10 段音频合计 50 份。指定图片纠正只为被选择的图片准备素材，multipart／旧任务继续处理其原有素材集合。入库流程使用任务独立组或兼容原组：逐份调用创建接口，收到 ID 后立即保存并继续后续素材，创建与平台异步审核交错推进。创建接口仍是一份一请求；同 Key 的实际请求间隔和在途限制继续生效，审核未完成不会阻塞后面的素材入库。

审核优先使用 ListAssets 按任务素材组分页查询，默认每页 10 条，50 份一轮约需 5 页。分页结果只更新本任务已持久化的精确 ID，并核对类型和归属；返回顺序不会改变输入顺序，重复引用也不会被删除。缺项、重复页或不完整结果不视为成功，必要时按原 ID 单项核查。已通过素材在日常推进中不再因 5 分钟缓存期限反复从头重查；视频生成前集中完成最终核验，全部 Active 后才跨提交边界。

每份素材的回执、状态、下一次动作、分页位置与错误保存在原 task/attempt 的持久元数据中。进程重启只恢复原任务、原 Key、原网关和原 ID。旧任务已有的素材组和回执可以迁移到同一准备计划，不会为了改成独立组重新上传；已经失败的任务不会被本版自动复活。

同 Key 的准备队列按先后顺序发放名额，默认同时推进 2 个任务。等待本地准备名额不启动 15 分钟素材准备期限，但仍受任务创建起算的排队期限约束。取得准备名额后，期限持久保存，重启或重复消息不延长；已有旧版期限也保持原值。默认不再根据陈旧的单素材 Processing 缓存直接判定 180 秒超时，平台明确 Failed 会立即阻止生成，其余准备始终受整项任务硬期限限制。

到期准备任务按秒唤醒；在途请求提前释放许可后，等待任务通过短间隔数据库复查及时继续，65 秒只作为失联请求的安全租约。HTTP 429 的实际冷却不因此缩短。等待会释放 Worker 执行线程，账号和全局生成名额仍按既有规则预留。

后台分别显示等待准备名额、素材请求名额、上游限频和审核等待，并展示已入库、已通过、处理中、失败和待入库的数量。错误详情保留失败素材的原始位置、类型及脱敏错误。准备计划和素材标识不进入公开任务 DTO；总期限耗尽时，内部明确该阶段尚未提交视频生成。

上述延期仅覆盖需要入库的素材操作。正常任务只调用一次视频创建；仅在已持久确认的首次指定图片前置拒绝之后，允许一次更正后的第二次调用。每次调用前均保存自己的序号与提交边界；连接中断、结果不明或已受理时不自动重放。成片保存、24 小时保留及现有清理逻辑保持原规则。本版复用已有节流表和 task/attempt JSON 元数据，不清空原记录，也不新增数据库表。

提交、查询与成片链接

视频创建接口每次默认等待 120 秒，首次 URL 直传和指定图片入库后的更正提交分别使用独立的 120 秒预算。可通过服务端环境变量 MODELFLARE_VIDEO_SUBMIT_TIMEOUT_MS 设置 30000～600000 毫秒的整数；未配置或无效时使用 120000 毫秒。该配置只作用于 ModelFlare 的 POST /v1/videos，不改变素材创建的 60 秒、任务／素材查询的 30 秒，也不修改其他平台。素材审核仍受独立准备期限管理。

ModelFlare 未终结任务对业务调用方统一返回 status: "processing"、stage: "processing"、wait_reason: null，不附 error、error_code 或 reason_code。指定图片入库、更正提交、生成和成片保存均属于原任务处理过程，正常查询不返回重试或待核实错误码。终态仍按原规则返回 succeeded／failed 及对应结果或安全错误。

管理员后台保留真实内部状态、首次拒绝、所选图片、审核进度和“更正提交 1/1”记录。首次或第二次视频创建超时且没有上游任务 ID 时，内部仍保留受理待核实和占用，业务投影的“进行中”不表示已经确认上游生成；此类任务需要管理员核实，不会触发新的生成请求。上游明确要求图片入库才允许一次更正；入库审核失败／期限耗尽时直接失败，第二次明确拒绝后也直接失败，不发第三次。

将任一示例保存为 UTF-8 JSON 文件，POOL_BASE_URL 使用你的号池服务地址，POOL_API_KEY 为本服务调用密钥：

curl "$POOL_BASE_URL/v1/videos/generations/async" \
  -H "Authorization: Bearer $POOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: modelflare-example-001" \
  --data-binary @request.json

curl "$POOL_BASE_URL/v1/videos/generations/async/TASK_ID" \
  -H "Authorization: Bearer $POOL_API_KEY"

后台保留原上游任务 ID 并据此查询；不会凭另一任务的链接替换原结果。上游完成后，先进入本服务器保存阶段，下载并校验 MP4 成功后才对外返回 succeeded 和 data[0].url。

结果使用现有中性签名路径 /v1/video-results/{task_id}/{signature}.mp4，支持 GET、HEAD 和 Range；链接中不包含平台名或 API Key。视频沿用现有服务器保留期限、定时清理和磁盘保护规则。服务器保存失败时，不把上游成功改成重新生成；后续恢复仅围绕原任务和原视频进行。