CanSeeDream Developer API

快速说明

所有生成接口都会先创建任务，任务进入队列后通过查询接口获取进度和结果。

异步任务

1. 创建 SK在视频或图片页面创建对应类型的 API Key，并放到服务端环境变量中。

2. 提交任务携带 Bearer SK 调用创建接口，返回 cstask_xxx 任务 ID。

3. 查询结果轮询任务查询接口，状态为 succeeded 后读取结果 URL。

鉴权与 SK

请只在服务端保存 SK，不要放入浏览器、小程序前端或公开仓库。

Bearer Token

视频 SK
sk_live_ 开头，只能调用视频生成接口。

图片 SK
sk_img_ 开头，只能调用图片生成接口。

请求头

Authorization: Bearer sk_live_xxx
Authorization: Bearer sk_img_xxx

两类 SK 权限隔离；用户账户积分统一扣减，但每个 SK 可以设置独立积分上限，避免某个 SK 消耗超过预算。

视频生成 API

提交内容与网页视频生成页保持一致。线路、素材限制和消耗积分以服务器开放配置为准。

sk_live_

POSThttps://canseedream.com/api/v3/contents/generations/tasks

curl 示例

curl -X POST 'https://canseedream.com/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-request-001' \
  -d '{
    "model": "seedance-2.0-reference",
    "provider_route": "tc_pool",
    "prompt": "生成一段 10 秒视频。使用 @Image1 作为主体参考，电影感，动作连贯，画面清晰。",
    "image_urls": ["https://example.com/reference.png"],
    "audio_urls": [
      { "url": "https://example.com/reference.mp3", "durationSeconds": 8 }
    ],
    "video_urls": [
      { "url": "https://example.com/reference.mp4", "durationSeconds": 6 }
    ],
    "aspect_ratio": "9:16",
    "generate_audio": true,
    "number_of_runs": 1
  }'

当前开放线路

默认线路 tc_pool
图片最多 9 张，音频最多 3 个，视频最多 3 个，素材累计最多 10 个；音频累计 15 秒，视频累计 15 秒。

qyfast线路 qyfast
仅支持图片参考；默认图片最多 4 张，不支持音频/视频参考；时长由服务器配置为 5/10/15 秒。

图片生成 API

不传参考图时为文生图；传入参考图时自动走图生图。参考图顺序对应提示词中的 @Image1、@Image2。

sk_img_

POSThttps://canseedream.com/api/v3/images/generations/tasks

文生图示例

curl -X POST 'https://canseedream.com/api/v3/images/generations/tasks' \
  -H 'Authorization: Bearer sk_img_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-request-001' \
  -d '{
    "model": "GPT Image 2",
    "prompt": "生成一张橘猫道长，国风电影感，高清细节",
    "size": "1024x1024",
    "quality": "auto",
    "background": "opaque",
    "n": 1
  }'

图生图示例

{
  "prompt": "参考 @Image1 保持主体身份，将服装改为 @Image2 的紫色道袍风格，电影感柔光。",
  "images": [
    "https://example.com/person.png",
    "https://example.com/cloth.png"
  ],
  "size": "1024x1024",
  "quality": "auto",
  "background": "opaque",
  "n": 1
}

直接传 data URL

{
  "prompt": "把画布中的人物改成水彩插画风格。",
  "images": [
    { "data_url": "data:image/png;base64,iVBORw0KGgo..." }
  ],
  "size": "1024x1024",
  "quality": "auto",
  "n": 1
}

查询任务

建议每 3-5 秒查询一次任务状态；查询接口不会重复扣积分。

GET

视频任务

GEThttps://canseedream.com/api/v3/contents/generations/tasks/cstask_xxx

curl 'https://canseedream.com/api/v3/contents/generations/tasks/cstask_xxx' \
  -H 'Authorization: Bearer sk_live_xxx'

图片任务

GEThttps://canseedream.com/api/v3/images/generations/tasks/cstask_xxx

curl 'https://canseedream.com/api/v3/images/generations/tasks/cstask_xxx' \
  -H 'Authorization: Bearer sk_img_xxx'

状态	含义
`queued`	任务已进入队列，等待资源。
`running`	任务正在生成或上传结果。
`succeeded`	任务成功，读取 `content.video_url` 或 `content.image_url`。
`failed`	任务失败，查看 `error.code` 和 `error.message`。

参数限制

以下为默认限制，实际开放线路以服务器配置为准。

Limits

模块	限制
视频尺寸/时长	清晰度和时长按线路配置；默认线路传参时长固定为 `auto`，qyfast 线路由服务器配置为 5/10/15 秒。
视频参考素材	默认线路：图片 9 张、音频 3 个、视频 3 个、累计素材 10 个；qyfast 默认仅支持图片参考。
音频/视频时长	音频累计不超过 15 秒，视频累计不超过 15 秒，两者独立计算；视频参考需要提供 `durationSeconds`。
图片参考图	最多 16 张；没有参考图为文生图，有参考图为图生图。
图片质量	只开放 `auto` 和 `medium`。页面展示为“正常”和“优秀”。
图片尺寸	`auto`、`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`2048x1152`、`3840x2160`、`2160x3840`。

积分与幂等

网页生成和 API 生成使用同一套任务队列与积分冻结逻辑，避免并发绕过余额。

Points

提交任务时会先冻结预计积分；任务成功后扣除冻结积分，可返还失败会释放冻结积分。

内容安全、肖像、版权等内容类失败按产品规则正常扣除积分。

每个 SK 可以设置独立积分上限；不填或填 0 表示不额外限制，提交时始终检查账户剩余积分。

建议每次提交传入 Idempotency-Key。相同 key 会返回已有任务，避免客户端重试造成重复提交。

错误处理

接口错误格式尽量保持稳定，业务侧建议按 error.code 分支处理。

Error

错误码	建议处理
`NoAvailableResource`	当前生成资源不足，可稍后重试或提示用户等待。
`ModerationFailed`	内容未通过安全检查，请调整提示词或参考素材。
`ServiceUnavailable`	上游服务暂时不可用，建议延迟重试。
`TaskFailed`	普通失败，展示友好文案并保留任务 ID 便于排查。
`NotFound`	任务不存在，确认 SK 类型、用户归属和任务 ID 是否一致。