CanSeeDream Developer API

快速说明

视频和标准图片接口创建任务后通过查询接口获取结果；图片特供版会保持 HTTP 请求并等待同一套持久化任务完成。

异步 + 同步

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

当前开放线路的兼容 Base URL 由服务端实时返回，页面只显示 /health 的 defaults.videoProviders 中仍开放的线路；通用地址为 /api/v3。

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": "video",
    "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
  }'

当前开放线路

正在读取当前开放线路...

视频超分与补帧

这是视频生成成功后的可选第二阶段，适用于当前开放的所有视频线路。

Optional

当服务端开启 VIDEO_ENHANCE_ENABLED=true 且模式为 user 时，请在提交请求中传入 enhance: true。目标清晰度支持 source、720p、1080p、2k、4k；其中 source 表示保持原清晰度、只做补帧，必须同时传入数字帧率。目标帧率支持 source、24、30、48、60。720p 视频的超分选项从 1080p 开始，但仍可用 source + 数字帧率进行 720p 补帧。独立超分页面和视频生成后的增强使用独立积分配置，具体价格由服务端环境变量决定。

{
  "enhance": true,
  "enhance_settings": {
    "targetResolution": "1080p",
    "targetFps": "source"
  }
}

情形	结果与积分
480p -> 720p	允许增强；增强成功后返回 720p 结果。
720p -> 720p	超分不允许同分辨率；如只需补帧，请使用 `source` + 数字帧率，原始分辨率保持不变。
增强失败	原始生成视频仍返回给用户；基础视频积分保留；增强积分释放，不会因为增强失败额外扣分。
基础视频失败	增强积分释放；基础视频积分继续按所选线路的失败计费规则处理。
服务端 force 模式	所有视频自动进入增强，客户端不能关闭；最终是否扣增强积分仍以增强任务成功为准。

图片生成 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
}

图片特供版（同步）

兼容 OpenAI 图片接口的请求与响应结构，共用现有 GPT Image 2 账号池和用户积分。接口等待生成完成后直接返回图片 URL，无需客户端轮询。

OpenAI Compatible

安全要求
使用设置了有限积分额度的 sk_img_*。额度为 0 的无限密钥不能调用此接口。

幂等与画布兼容
Idempotency-Key 建议携带但默认可选。无法添加自定义请求头的 OpenAI 兼容画布可直接调用；相同请求仍在运行时，服务端会复用原任务，防止超时重试重复扣分。

画布接入配置

接口格式：OpenAI 兼容
Base URL：https://canseedream.com
API Key：sk_img_xxx
Model ID：gpt-image-2

同时兼容 gpt-img-2、gpt_image_2 和 GPT Image 2，均使用现有 GPT Image 2 图片账号池。

文生图

POSThttps://canseedream.com/v1/images/generations

curl 示例

curl -X POST 'https://canseedream.com/v1/images/generations' \
  -H 'Authorization: Bearer sk_img_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-sync-001' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "白色背景上的红色马克杯，干净的产品摄影",
    "size": "auto",
    "quality": "auto",
    "response_format": "url",
    "n": 1
  }'

图生图

POSThttps://canseedream.com/v1/images/edits

multipart 示例

curl -X POST 'https://canseedream.com/v1/images/edits' \
  -H 'Authorization: Bearer sk_img_xxx' \
  -H 'Idempotency-Key: image-edit-sync-001' \
  -F 'model=gpt-image-2' \
  -F 'prompt=保留主体，将背景替换为专业摄影棚' \
  -F 'image=@reference-1.png' \
  -F 'image=@reference-2.jpg' \
  -F 'response_format=url'

远程图片 URL（JSON）

curl -X POST 'https://canseedream.com/v1/images/edits' \
  -H 'Authorization: Bearer sk_img_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-edit-url-sync-001' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留 @Image1 的主体，参考 @Image2 的服装风格",
    "image_urls": [
      "https://example.com/reference-1.png",
      "https://example.com/reference-2.jpg"
    ],
    "size": "auto",
    "quality": "auto",
    "response_format": "url",
    "n": 1
  }'

Base64 参考图（JSON）

curl -X POST 'https://canseedream.com/v1/images/edits' \
  -H 'Authorization: Bearer sk_img_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-edit-base64-001' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留主体，将背景替换为专业摄影棚",
    "image_base64": "data:image/png;base64,iVBORw0KGgo...",
    "size": "auto",
    "quality": "auto",
    "response_format": "url"
  }'

多个 Base64 参考图（JSON）

curl -X POST 'https://canseedream.com/v1/images/edits' \
  -H 'Authorization: Bearer sk_img_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-edit-multi-base64-001' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留 @Image1 的主体，参考 @Image2 的服装风格",
    "image_base64s": [
      "data:image/png;base64,iVBORw0KGgo...",
      "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    ],
    "size": "auto",
    "quality": "auto",
    "response_format": "url",
    "n": 1
  }'

成功响应

{
  "created": 1784592000,
  "data": [
    { "url": "https://canseedream.com/api/local-results/image/123?token=..." }
  ]
}

图片尺寸
size 省略时默认为 auto，也可以显式传入 auto 或支持的固定尺寸。同步接口默认值可通过 IMAGE_SYNC_DEFAULT_SIZE 独立配置。

返回格式
Base64 仅用于输入参考图；返回仍只支持 response_format=url，不支持 b64_json、流式响应和 mask。返回地址为带签名的结果链接。

结果存储
生成结果保存到本地服务器后即可返回；读取时优先使用本地文件。本地文件已清理且存在 MinIO 备份时，会自动从备份读取。没有备份时，链接有效期不会超过本地文件保留时间。

参考图输入
本地文件使用 multipart 并重复传入 image 字段；远程图片使用 JSON 的 image_urls；单张 Base64 使用 image_base64，多张使用 image_base64s 数组，推荐每项都传携带 MIME 的完整 Data URL。数组顺序对应 @Image1、@Image2，不能把多张图片拼进同一个 Base64 字符串。HTTPS 与 Base64 可混用；混合输入需要严格保持顺序时，将 URL、Data URL 或 b64_json 对象依次放入同一个 images 数组。最多支持 16 张参考图；单图大小、全部 Base64 解码后的合计大小和 JSON 请求体大小分别受服务端配置限制。Base64 会校验实际图片格式并转存为临时文件，不会写入任务 JSON 或数据库。

超时与重试
HTTP 等待超时会返回 504 generation_timeout，后台任务仍会继续。使用完全相同的请求内容重试会继续等待原任务；显式携带 Idempotency-Key 时保护范围更长。

幂等冲突
同一个 Idempotency-Key 不能用于不同的提示词、参数或参考图；内容变化时会返回 409 idempotency_conflict。

查询任务

建议每 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`；西瓜线路固定 720p，`duration` 仅支持 5、10、15 秒，并且只支持图片参考；其他可选时长线路通常支持 4-15 秒。西梅和薯条线路固定 720p，桔子线路默认 720p，苹果线路支持服务器配置的 480p 或 720p。
视频参考素材	默认线路：图片 9 张、音频 3 个、视频 3 个、累计素材 10 个；其他线路以服务器开放配置为准。
桔子提示词	桔子线路默认最多 `5000` 个字符，实际限制以服务器配置为准。
音频/视频时长	音频累计不超过 15 秒，视频累计不超过 15 秒，两者独立计算；视频参考需要提供 `durationSeconds`。
图片参考图	最多 16 张；没有参考图为文生图，有参考图为图生图。
图片特供版	默认单次最多生成 4 张；JSON 请求体最大 2 MiB，完整请求体最大 96 MiB，单张上传文件最大 20 MiB。实际限制以服务端配置为准。
图片质量	只开放 `auto` 和 `medium`。页面展示为“正常”和“优秀”。
图片尺寸	`auto`、`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`2048x1152`、`3840x2160`、`2160x3840`。

积分与幂等

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

Points

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

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

每个 SK 可以设置独立积分上限；不填或填 0 表示不额外限制，提交时始终检查账户剩余积分。图片特供版属于例外：为控制密钥泄露风险，只接受设置了有限积分额度的图片 SK。

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

错误处理

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

Error

错误码	建议处理
`NoAvailableResource`	当前生成资源不足，可稍后重试或提示用户等待。
`ModerationFailed`	内容未通过安全检查，请调整提示词或参考素材。
`ServiceUnavailable`	上游服务暂时不可用，建议延迟重试。
`TaskFailed`	普通失败，展示友好文案并保留任务 ID 便于排查。
`NotFound`	任务不存在，确认 SK 类型、用户归属和任务 ID 是否一致。
`idempotency_conflict`	同一个幂等键对应的请求内容发生变化；请为新请求使用新的 `Idempotency-Key`。
`generation_timeout`	同步等待已超时，任务仍在后台继续；请使用原请求内容和原幂等键重试。
`rate_limit_exceeded`	同步请求并发或频率超过限制，请降低并发并延迟重试。