# Seedance 任务接口

<a id="seedance"></a>

<a id="seedance-任务接口"></a>

## 接口说明

使用本站 API Key

使用本站 API Key 调用 Ark 兼容任务接口。Base URL 为 `https://y.junlistudio.com/api/v3`，创建任务使用 `content[]`，成功结果位于 `content.video_url`。模型、时长、比例、分辨率和参考能力以[模型目录](https://y.junlistudio.com/docs.md?page=models#models)为准。

 **Seedance · 创建任务**  `POST /api/v3/contents/generations/tasks`

```bash
curl 'https://y.junlistudio.com/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "seedance-2.5",
  "content": [
    {
      "type": "text",
      "text": "海浪轻轻拍打沙滩，镜头缓慢推进"
    }
  ],
  "duration": 4,
  "ratio": "21:9",
  "resolution": "480p"
}'
```

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 本站公开的视频模型 ID；时长、参考能力与价格以模型目录为准。 |
 `content` | `array` | 是 | 非空数组，最多 32 项。文字使用 {"type":"text","text":"提示词"}；多个文字项按换行合并。 |
 `content[].image_url` | `object` | 否 | type=image\_url，image\_url={"url":"公网 URL 或 Data URI"}。role 为 first\_frame（默认）、last\_frame 或 reference\_image；尾帧须搭配首帧。 |
 `content[].video_url / audio_url` | `object` | 否 | type=video\_url 或 audio\_url，对应字段为 {"url":"…"}。role 分别为 reference\_video / reference\_audio，可省略；支持 HTTP(S) 或对应媒体的 Data URI。 |
 `duration` | `integer` | 否 | 正整数秒，默认 5；必须在模型支持范围内，不支持 -1 自动时长。 |
 `ratio / resolution` | `string` | 否 | 例如 16:9 / 720p；默认比例 16:9，分辨率采用模型默认档位。建议按模型目录显式填写。 |
 `generate_audio` | `boolean` | 否 | 控制生成音轨，仅用于声明支持此能力的模型。 |

普通参考与首尾帧互斥；音频参考按模型要求搭配视觉参考。当前支持上表字段；callback\_url、seed、draft、watermark、return\_last\_frame、tools 等扩展参数会返回 400，不会被静默忽略。

<a id="查询-下载与删除"></a>

### 查询、下载与删除

 **Seedance · 查询与下载**  `GET /api/v3/contents/generations/tasks/{id}`

```bash
# 创建返回 {"id":"任务ID"}；替换 TASK_ID，查询至 succeeded / failed / expired
curl 'https://y.junlistudio.com/api/v3/contents/generations/tasks/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# succeeded 后，复制响应 content.video_url 的完整地址（含 media_token）
curl 'VIDEO_URL' -o video.mp4

# 可选：删除已结束的任务，返回 204
curl -X DELETE 'https://y.junlistudio.com/api/v3/contents/generations/tasks/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

状态为 `queued / running / succeeded / failed / expired`。创建、查询和删除需要本站 API Key，任务按本站用户隔离；同一用户的密钥可查询其任务。视频链接包含临时下载凭证，无需额外密钥，有效期为生成完成后 24 小时。查询已有任务不重复扣费；删除仅支持已结束任务，不退还成功任务费用，且会撤销该任务的 API 查询与下载权限。运行中删除返回 409，暂不支持主动取消。

 **完成响应示例 · 本次扣除 3 积分**  `200 OK`

```json
{
  "id": "TASK_ID",
  "model": "seedance-2.5",
  "status": "succeeded",
  "content": {
    "video_url": "https://y.junlistudio.com/api/v3/contents/generations/tasks/TASK_ID/content?media_token=TEMPORARY_TOKEN"
  },
  "usage": {
    "completion_tokens": 3000,
    "total_tokens": 3000
  },
  "billing": {
    "unit": "credit_equivalent",
    "credits": 3,
    "units_per_credit": 1000,
    "measured_tokens": false
  }
}
```

<a id="在你的-sub2api-中接入本站"></a>

### 在你的 Sub2API 中接入本站

使用支持 Seedance 的 Sub2API v0.2.7 或更新版本，新增  **OpenAI 平台 → API Key 账号** ，勾选  **Seedance (Ark)** 。Base URL 填 `https://y.junlistudio.com/api/v3`，API Key 填本站密钥。配置本站视频模型及模型映射，加入可用分组，并开启分组的“允许图片生成”媒体权限。

 **计费单位：** 本站按模型价格预扣积分，失败退款。为兼容 Sub2API 的 Seedance 结算，成功响应的 `usage.completion_tokens` 按实际扣费积分 × 1000 折算，四舍五入为整数；这是兼容计费单位，并非实际测量的推理 token。`billing.measured_tokens=false` 明确标注来源，重复查询返回相同单位数。

Sub2API 按成功查询的 usage 结算。若希望每个本站积分向下游收取 P 个货币单位，将输出价格设置为  **1000 × P / 百万 token** ，并考虑分组倍率。例：每积分收取 0.01，则设置 10 / 百万 token，3 积分对应 3000 单位，基础费用为 0.03。客户端必须查询到 succeeded，并及时保存视频；不要通过重复创建来重试查询。

同时提供 `/v3`、`/v1` 和无版本前缀的任务路由别名；Sub2API 接口地址使用 `/api/v3` 地址。未提供任务列表、回调或完整 Ark 扩展能力。错误格式为 `{"error":{"code":"…","message":"…"}}`。