平台使用指南

主题

Seedance 视频接入指南 ​

适用于 0.2.18.1 起的 Seedance 独立视频分组。视频采用异步任务：创建返回任务编号，后台继续生成并结算，客户端查询结果后下载。

先确认分组和型号

使用绑定「Seedance 视频」分组的本站 API Key。可用型号以该 Key 的模型列表、分组白名单和管理员配置为准。不要把本站 Key 发给上游供应商；视频分组不能调用文本聊天或图片生成。

1. 准备地址与密钥 ​

本站 API 地址为 https://api.likeai520.cc。BASE_URL 不包含 /v1 或 /api/v3。

bash
export BASE_URL='https://api.likeai520.cc'
# 安全输入本站密钥，不写入脚本或版本库。
read -r -s API_KEY
export API_KEY
curl --fail-with-body --silent --show-error \
  "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"

从 data[].id 选择模型。下文以 doubao-seedance-2.0-mini、4 秒、720p、16:9 为例，须先确认这些参数已开放。模型列表不能保证上游实时有容量或所有参数组合都能生成。

2. 创建任务 ​

创建时会冻结余额和 API Key 可用额度。不要给创建请求添加自动重试；网络超时不代表上游没有收到任务。

bash
curl --fail-with-body --silent --show-error --max-time 120 \
  "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0-mini",
    "prompt": "夕阳下的海边咖啡馆，一只橘猫趴在窗边，镜头缓慢推进，暖色电影质感，无文字。",
    "duration": 4,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false,
    "seed": 0
  }'

响应结构示例（编号和时间为示意）：

json
{
  "id": "video_EXAMPLE",
  "model": "doubao-seedance-2.0-mini",
  "status": "queued",
  "created_at": 1792490000,
  "settlement": "held"
}

保存完整响应和 id。HTTP 200 不表示视频已完成。若错误响应包含 task_id，也要保存，先查询原任务或请管理员核对，不要重新提交。

3. 查询状态 ​

bash
export TASK_ID='替换为创建响应中的id'
curl --fail-with-body --silent --show-error --max-time 30 \
  "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

建议每 5–10 秒查询一次。查询超时、429 或临时 5xx 时稍后查询原任务，不重新创建。

  • queued：排队或等待提交状态核实。
  • in_progress：正在生成。
  • completed：生成成功，可以下载。
  • failed / cancelled：失败或已确认取消，停止轮询并核对结算状态。
  • submission_status: "unknown"：提交结果不明确，需管理员核对上游；不是可以安全重试的信号。

成功响应示例：

json
{
  "id": "video_EXAMPLE",
  "model": "doubao-seedance-2.0-mini",
  "status": "completed",
  "created_at": 1792490000,
  "settlement": "settled",
  "usage": {"completion_tokens": 87299},
  "video_url": "/v1/videos/video_EXAMPLE/content"
}

usage、duration 仅在已记录对应上游数据时返回。缺失不等于 0，也不代表免费。视频已完成但缺少计费用量时，可能仍待核对。关闭客户端不取消任务；后台持续查询、结算，重启后继续处理已知的未完成任务。

4. 下载成片 ​

创建、查询、下载必须使用同一个本站 API Key；同一用户的另一个 Key 也不能读取任务。

bash
curl --fail --silent --show-error --max-time 600 \
  "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.mp4

video_url 是受保护的本站相对路径，需拼接本站地址并携带本站 Key。推荐使用固定下载接口。不要把 Key 放进 URL，或向外部媒体域名发送本站或上游 Key。外部签名媒体地址如由管理员另行提供，需保留完整签名参数、使用无鉴权请求并及时保存。

5. Ark 格式兼容入口 ​

Ark 客户端的 Base URL 可设为 https://api.likeai520.cc/api/v3，只使用创建及单任务查询能力；不是所有 Ark SDK 功能都已开放。

bash
curl --fail-with-body --silent --show-error --max-time 120 \
  "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0-mini",
    "content": [{"type": "text", "text": "晨雾中的山谷，镜头平稳掠过树林，柔和自然光。"}],
    "duration": 4,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

# 将 TASK_ID 更新为这次创建响应中的 id
curl --fail-with-body --silent --show-error \
  "$BASE_URL/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Ark 状态为 queued、running、succeeded、failed 或 cancelled；成功媒体在 content.video_url，用量仍在顶层 usage.completion_tokens。V1 的运行和成功状态分别为 in_progress、completed。

两种入口共用持久化任务和本地 video_ 编号，可用同一 Key 交叉查询；不要把本地编号直接交给上游。不要同时调用两个创建入口生成同一条视频。

6. 参数与参考素材 ​

能力按「上游类型 + 型号」配置；同系列在不同供应商处可能支持不同分辨率和参考方式。某档官方价格存在，不代表本站或该上游已开放该能力。

  • model：公开名称，由本站映射到上游实际型号。
  • prompt / content：二选一。有素材时，把文本和素材统一放入 content，不同时传 prompt。
  • duration：显式填写已支持的整数秒数。seconds 是整数别名，不能同时传两项，不接受字符串秒数。
  • resolution / ratio：显式填写型号已开放的值，例如 720p / 16:9。
  • generate_audio：JSON 布尔值，false 有效；型号需支持音轨参数。
  • seed：整数，0 有效；允许 -1 或 0–2147483647，且型号需开启 seed 能力。
  • camera_fixed、watermark：仅在管理员开启对应能力后使用。

首帧示例（先开启型号的首帧能力，替换型号和素材 URL）：

json
{
  "model": "YOUR_ENABLED_MODEL",
  "content": [
    {"type": "text", "text": "保持主体外观，让镜头缓慢向前推进。"},
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://your-media.example/first-frame.png"}}
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

角色为 first_frame、last_frame、reference_image、reference_video、reference_audio；类型为 image_url、video_url、audio_url，URL 放在同名对象的 url 字段。尾帧必须配首帧；首尾帧不能与普通参考混用；音频参考须搭配视觉素材。数量与组合还须满足型号限制。

素材必须是上游可读取的 HTTPS 文件地址，并保持有效直到任务完成。磁盘路径、blob:、网盘分享页不能直接使用；本版没有素材上传或素材库接口。

编辑需显式开启 edit，使用一个视频参考、omni_reference_task_type: "edit"、duration: -1 和 ratio: "adaptive"；按秒计费的编辑暂不支持。延长需显式开启 extend 并满足型号校验。不要照搬第三方自动时长、默认参数或最大素材数量。

本版不开放任务列表、取消/删除、回调、草稿、任意工具调用。删除记录不等于取消上游生成或退款。

7. Python：恢复查询并下载 ​

示例只查询已有任务，不创建付费任务。安装 requests，设置 BASE_URL、API_KEY、TASK_ID。退出后可以使用相同编号继续查询。

python
import os
import time
from pathlib import Path
from urllib.parse import quote
import requests

base = os.environ["BASE_URL"].rstrip("/")
task_id = os.environ["TASK_ID"]
headers = {"Authorization": "Bearer " + os.environ["API_KEY"]}
task_url = base + "/v1/videos/" + quote(task_id, safe="")
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    try:
        response = requests.get(task_url, headers=headers, timeout=30,
                                allow_redirects=False)
    except (requests.Timeout, requests.ConnectionError):
        time.sleep(10)
        continue
    if response.status_code == 429 or response.status_code >= 500:
        time.sleep(10)
        continue
    if response.status_code != 200:
        raise RuntimeError(f"查询失败 HTTP {response.status_code}，保留原任务编号")
    task = response.json()
    if task.get("submission_status") == "unknown":
        raise RuntimeError("提交结果待核对，请联系管理员，不要重复创建")
    status = task.get("status")
    if status == "completed":
        print("用量：", task.get("usage", "上游未提供"))
        print("结算状态：", task.get("settlement"))
        partial = Path("result.mp4.part")
        # 固定使用本站下载路径，禁止携带密钥跟随重定向。
        with requests.get(task_url + "/content", headers=headers, stream=True,
                          timeout=(15, 120), allow_redirects=False) as media:
            if media.status_code != 200:
                raise RuntimeError(f"下载失败 HTTP {media.status_code}，稍后重试下载")
            with partial.open("wb") as output:
                for chunk in media.iter_content(1024 * 1024):
                    output.write(chunk)
        partial.replace("result.mp4")
        print("已保存 result.mp4")
        break
    if status in {"failed", "cancelled"}:
        raise RuntimeError(f"任务 {task_id} 已结束：{status}，请核对结算状态")
    if status not in {"queued", "in_progress"}:
        raise RuntimeError(f"未知状态 {status!r}，保留响应并联系管理员")
    time.sleep(5)
else:
    raise TimeoutError("查询窗口结束，稍后查询原任务；不要重新创建")

8. 费用与使用记录 ​

收费方式由提交时的型号配置决定：按次、按实际秒数、每百万实际视频 Token。usage 是用量，不是账单；有 Token 字段不代表一定按 Token 收费。费用在「使用记录」查看，视频显示为「异步」；管理员可查看冻结、最终费用和异常结算。

Token 费用 = 实际 completion_tokens ÷ 1,000,000 × 提交时单价。例如单价 23、实际用量 87,299，最终费用为 2.007877 个账本额度。预冻结 23 时释放差额 20.992123，不是再扣一次 2.007877。这不是所有型号的统一价格。

本站当前使用站长指定的 1 个美元标识账本额度 = 1 元人民币报价 政策，不是市场汇率；其他部署须由管理员明确配置。内置官方价格为 2026-10-20 快照，渠道或专用型号价格可覆盖，已提交任务使用当时的价格快照。

  • held：已冻结，等待结果和用量。
  • settled：已结算，重复查询不重复计费。
  • released：明确失败或人工核实后释放冻结。
  • needs_review：用量缺失等异常，等待核对，不补零。
  • pending_debit：费用超出冻结额且余额或 Key 额度不足。补充额度后请管理员处理；可查询下载，暂不能创建新视频。

9. 排错与后台配置 ​

401 / 403：检查本站密钥、启用状态、分组及权限。402：检查余额、Key 额度、冻结预算和待补扣任务。404：确认本地编号及创建时的同一 Key。429：并发或限流，查询稍后重试，不自动重试创建。

400 或模型未配置：检查 JSON 类型、参数组合和定价。管理员按以下顺序检查：

  1. 账号管理：Seedance 平台、上游类型、Key、地址、模型映射。测试连接只验证模型目录，不生成视频。
  2. 分组管理：账号绑定、启用、用户权限和模型白名单。白名单控制权限，不配置售价。
  3. 渠道管理的 Seedance 视频配置：型号、协议、能力、价格档位与冻结规则。优先级为专用型号配置（含显式禁用）→ 可支持的渠道价格 → 已启用的官方默认价。
  4. 使用记录：任务和结算状态，异常核对。改价不改变旧任务快照。

新部署须先配置账本换算规则才能启用官方默认价。价格或冻结规则不完整时禁止创建。独立分组只支持余额计费，不支持订阅扣费。

本站接口范围

本文按本站实现编写，可用型号和能力以本站分组、白名单及配置为准。未列出的查询别名、上传接口和参数组合不属于本文支持范围。旧 OpenAI / 组合分组 Seedance 保持原行为，不自动迁移到独立平台。

面向平台用户的接入与使用说明。

Copyright © 2026