从业务选择接口：视频生成、图片生成和视频生成后的超分使用异步任务；OpenAI 兼容图片接口是单独的同步接口。不要混用两种响应结构。

接入流程

1. 在控制台创建对应业务的 API Key，保存在自己的服务端。
2. 选择开放的线路：请求体传 provider_route，或者使用带线路前缀的专属地址。
3. 创建任务，保存 request_id 和每个 tasks[].id。
4. 使用同类业务的查询接口轮询；status=succeeded 后读取 content 中的成品地址。

鉴权与 Key

视频与图片 Key 分开鉴权与额度管理，但账号积分共用。创建时请保存完整 Key；支持再次查看的 Key 可在控制台查看，旧 Key 可能无法恢复。不要把 Key 放入浏览器前端、公开仓库、日志或截图。X-Api-Key 是兼容认证方式，推荐统一使用 Bearer。

余额与 Key 管理边界

API Key 额度和账号余额可在网页控制台查看。GET /api/me、GET /api/developer/keys、GET /api/image-developer/keys 都是登录会话接口，不是仅凭 API Key 即可调用的余额 API。

普通 Key 的额度上限 0 表示无额外 Key 上限，不是账号积分为零；同步图片接口默认可能要求有限额度 Key。

通用请求约定

Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: your-business-order-001

• Base URL 为实际部署域名。以下 cURL 使用 https://canseedream.com 作为示例，网页会替换为当前域名。
• 示例 Key、任务 ID 和 example.com 素材地址都是占位符，必须替换后再调用。
• 推荐每个业务订单固定一个 Idempotency-Key，避免超时后重复创建。协议线路必须提供幂等值，推荐使用该请求头；其他接口的具体规则见 幂等与错误。
• 多份生成会返回多个 tasks[]，需要逐个查询，不要只处理顶层 id。
• 新文档只整理已实现能力，不增加接口，也不要求老用户迁移。

专属路径可以替代 provider_route

两种方式使用同一套创建、查询和计费逻辑。对于固定线路的客户端，推荐专属路径，改地址即可切换。

只替换 Base URL 的客户端，也可以把 Base URL 设为 https://你的域名/gpt_image_2_s，其余 /api/v3/images/generations/tasks 路径不变。

参数与地址两种写法

通用地址：

POST /api/v3/images/generations/tasks

{
  "provider_route": "gpt_image_2_s",
  "prompt": "一只橘猫坐在窗边，柔和自然光",
  "resolution": "1K",
  "aspect_ratio": "1:1",
  "n": 1
}

专属地址：

POST /gpt_image_2_s/api/v3/images/generations/tasks

{
  "prompt": "一只橘猫坐在窗边，柔和自然光",
  "resolution": "1K",
  "aspect_ratio": "1:1",
  "n": 1
}

不要将文档中出现的任意名字都当成有效路径。图片前缀只有已经实现的公开别名；以 图片生成 中的映射表为准。

协议线路与旧线路保持一致

已发布的协议视频线路也使用通用 /api/v3/contents/generations/tasks，或 /{线路ID}/api/v3/contents/generations/tasks，不需要独立的 /api/provider-router 请求格式。

推荐：专属地址 /{线路ID}/api/v3/contents/generations/tasks，请求体只传生成参数。通用地址可将公开线路 ID 写入 provider_route；也兼容显式 provider_route: "provider_router" 搭配 provider_line: "线路ID"，不能只传 provider_line。具体线路必须已经发布并开放。

当前开放线路与价格

GET /health

线路未出现在当前能力响应时，不要假定可调用。价格由服务器配置，调用方传入价格不能改变扣分。网页下方的线路目录仅在打开页面或点击“重新读取”时获取一次，不持续轮询。

尚未读取当前配置。

仅展示健康接口已经公开的字段；未声明的能力以实际接口校验为准。不会持续请求或执行生成。

视频生成使用视频 Key 和视频任务接口。文生视频、参考生视频共用一个接口，根据是否传参考素材区分。

创建视频任务

curl 'https://canseedream.com/tc_pool/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk_live_YOUR_VIDEO_KEY' \
  -H 'Idempotency-Key: video-order-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "一只橘猫在草地上奔跑，电影感，自然光",
    "duration": 10,
    "aspect_ratio": "16:9",
    "number_of_runs": 1
  }'

通过通用地址提交同一任务时，改为 /api/v3/contents/generations/tasks，并增加 "provider_route": "tc_pool"。

视频参数

带图片、音频或视频参考

{
  "prompt": "参考第一张图片的角色外观，跟随音频节奏运动",
  "duration": 10,
  "aspect_ratio": "16:9",
  "image_urls": ["https://example.com/character.png"],
  "audio_urls": ["https://example.com/music.mp3"],
  "video_urls": []
}

如果要明确素材类型和顺序，可改用 references；同一素材不要又放入 URL 数组又放入 references。

{
  "prompt": "参考素材中的角色，保持动作自然",
  "duration": 10,
  "references": [
    {"assetType": "image", "url": "https://example.com/character.png"},
    {"assetType": "video", "url": "https://example.com/motion.mp4", "durationSeconds": 3}
  ]
}

不是每条线路都支持纯文本或所有参考类型。素材各自的数量、总数量、音频/视频累计时长分别校验，以线路能力为准，不套用统一上限。

保存创建响应

成功创建通常返回 HTTP 200。以下仅展示需要保存的关键字段：

{
  "id": "cstask_VIDEO_ID",
  "request_id": "csreq_REQUEST_ID",
  "provider_route": "tc_pool",
  "status": "queued",
  "tasks": [
    {"id": "cstask_VIDEO_ID", "status": "queued", "progress": 0, "content": null, "error": null}
  ],
  "idempotent": false
}

查询视频并获取成品

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

也可以用创建时的专属前缀查询。status=succeeded 后检查 content 非空，再取 content.video_url，备用地址为 content.backup_video_url。失败看 error.code、error.message。完整状态及下载说明见 查询与结果。

使用图片 Key。文生图与参考生图自动识别，不需要调用方手动选择两个接口。无参考图就是文生图，有参考图就是参考生图。

图片线路目录

原有线路和新增线路并行，不自动相互替换。下表是接口映射，不代表所有线路当前都已启用。

新增四条线路的 _s 后缀是公开路由的一部分，不能省略。它们与原有同名模型的参数和价格不完全相同。

尚未读取当前配置。

这里读取当前服务端价格，不套用固定积分或旧模型质量价格。

创建图片任务

curl 'https://canseedream.com/gpt_image_2_s/api/v3/images/generations/tasks' \
  -H 'Authorization: Bearer sk_img_YOUR_IMAGE_KEY' \
  -H 'Idempotency-Key: image-order-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "一只橘猫坐在窗边，柔和自然光，精细毛发",
    "resolution": "1K",
    "aspect_ratio": "1:1",
    "n": 1
  }'

通用方式：POST /api/v3/images/generations/tasks，请求体增加 "provider_route": "gpt_image_2_s"。切换其他新增模型只需修改上述线路前缀或 provider_route。

新增四模型的参数

新增四模型按分辨率档位计价，不按 quality 或透明背景计价。不提供 quality、background、mask、web_search、自定义 output_format 能力；不要将旧模型的这些字段复制过来。

GPT Image 2.5 新线路最多 16 张参考图，其余三个新增模型最多 14 张。每份生成按当前目标模型的分辨率价格计算；准确价格从 defaults.image.providers[].resolutions[].points 读取，不在 SDK 内写死。

参考生图

在同一请求中增加参考图即可：

{
  "prompt": "保留参考图中角色的外观，改成明亮的室内场景",
  "resolution": "2K",
  "aspect_ratio": "16:9",
  "images": ["https://example.com/reference.png"],
  "n": 1
}

参考 URL 必须可从服务器访问，不能依赖浏览器 Cookie、登录态或局域网地址。新增四模型使用 HTTPS URL，不要将原线路的 Base64、视频、音频或遮罩参数直接复制过来。

创建响应与查询图片

创建响应包含 id、request_id、provider_route、tasks[]、idempotent。一份图片对应一个任务 ID；多份请求逐个处理 tasks[].id。

curl 'https://canseedream.com/gpt_image_2_s/api/v3/images/generations/tasks/cstask_IMAGE_ID' \
  -H 'Authorization: Bearer sk_img_YOUR_IMAGE_KEY'

通用查询地址：GET /api/v3/images/generations/tasks/{task_id}。成功状态为 succeeded，图片地址是 content.image_url，备用地址是 content.backup_image_url。

原有模型与同步图片接口

Weavy GPT Image 2 不支持透明背景，background 仅支持 opaque（可省略）；其 quality 仅支持 auto（自动，默认）与 low（普通）；Weavy GPT Image 2.5 仅支持 low（普通，默认）与 medium（正常）。中文为显示名称，API 请传标准英文值。其他上游线路以各自能力为准。

原有模型保留自身的 size、quality、background、variant 等能力，不能推断所有模型都支持这些字段。原有 Nano 模型使用自身的分辨率与比例配置。当前开放能力及价格见线路目录。

OpenAI 兼容 POST /v1/images/generations、POST /v1/images/edits 是单独的同步接口，成功返回 data[]，不返回上述异步任务结构；新增四个 _s 模型使用异步任务接口。详细区别见 兼容接口。

先区分两种能力

创建生成后超分任务

支持并开放后处理的线路，可在原视频请求中附加：

curl 'https://canseedream.com/tc_pool/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk_live_YOUR_VIDEO_KEY' \
  -H 'Idempotency-Key: video-enhance-order-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "一只橘猫在草地上奔跑，电影感",
    "duration": 10,
    "aspect_ratio": "16:9",
    "enhance": true,
    "enhance_settings": {
      "target_resolution": "1080p",
      "target_fps": 30
    }
  }'

超分与帧率参数

source 分辨率配数值帧率表示只补帧。不能同时将分辨率和帧率都设为 source；也不能降分辨率，或只请求不变的分辨率且不补帧。具体允许组合以服务器校验为准。

查询超分结果与扣分

生成后超分没有单独的 API 任务 ID，继续查询原视频任务：

GET /api/v3/contents/generations/tasks/{task_id}

最终成功地址仍在 content.video_url 中。生成基础积分与超分积分由服务器分别管理；超分失败时保留原始生成视频，释放超分部分，基础生成的结果与计费不被超分失败改写。

接口的 usage.points 是基础与超分额度的合计描述，细项为 usage.base_points、usage.enhancement_points；不要将响应中的额度字段当成独立支付流水。

独立超分的网页会话流程

以下是已有网页使用的接口，不是对第三方开放的 API Key 流程。会话凭证不能替换成视频 Key；不要为了接入而导出用户会话。

1. 登录后上传一个 MP4 文件，获取响应中的 asset.pendingKey。上传正文为文件二进制，非 multipart。
2. 创建时传入该 pendingKey 和真实源视频的宽、高、时长。幂等键放在请求体，服务端会读取实际文件重新校验。
3. 用响应中 tasks[].id 的数字 ID 查询，网页响应使用内部大写状态，不是 v3 状态结构。
4. 成功后下载；删除接口不等于取消正在进行的任务。

POST /api/enhance/assets/upload-raw?filename=source.mp4
X-Session-Token: <SESSION_TOKEN>
Content-Type: video/mp4
Content-Length: <文件字节数>

<MP4 文件二进制>

POST /api/enhance/generate
X-Session-Token: <SESSION_TOKEN>
Content-Type: application/json

{
  "idempotency_key": "enhance-order-001",
  "references": [{"assetType": "video", "pendingKey": "UPLOAD_PENDING_KEY"}],
  "enhance_settings": {
    "source_width": 1280,
    "source_height": 720,
    "duration_seconds": 10,
    "target_resolution": "1080p",
    "target_fps": 30
  }
}

示例宽、高和时长只是示范，必须替换为实际视频元数据。源视频限制从 defaults.enhance 读取。

独立超分网页的保存与清理

独立超分在网页上传已有视频后完成。结果可能存在本地、备份存储和可恢复的结果来源；保留时间与清理规则由服务器配置决定。调用方应及时保存成品，不应把任意一次返回的 URL 当成永久存储。

查询单个任务

也可以沿用创建时的专属线路前缀。专属查询会检查任务所属线路；前缀不匹配或任务不属于当前用户时返回 404。

使用 tasks[].id 或单份请求的顶层 id。request_id 是请求标识，不是任务查询 ID。

外部状态与内部阶段

API 的 status 只有以下四种主要取值：

task_status 是更详细的内部大写阶段，如 UPLOADING、SUBMITTED、RUNNING、COMPLETED、FAILED、CANCELED。不要将这些值当成外部 status；completed 不是成功状态值。progress=0 也不等于未提交或失败。

成功与失败响应

视频成功，关键字段示例：

{
  "id": "cstask_VIDEO_ID",
  "provider_route": "tc_pool",
  "status": "succeeded",
  "task_status": "COMPLETED",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "backup_video_url": null,
    "thumbnail_url": null
  },
  "error": null
}

图片使用 content.image_url、content.backup_image_url，而不是 video_url。即使 status=succeeded，也要检查 content 和 URL 非空；空结果不能当作已交付，也不要自动重新创建任务。

失败时，关键字段示例：

{
  "id": "cstask_TASK_ID",
  "status": "failed",
  "task_status": "FAILED",
  "content": null,
  "error": {
    "code": "TaskFailed",
    "message": "任务失败，请检查素材或稍后重新发起"
  }
}

error.code、error.message 是任务结果错误。创建或查询请求本身的 HTTP 错误见 幂等与错误。

下载与保存

从 content.video_url 或 content.image_url 下载；主地址暂时失败且存在备用地址时，再尝试备用地址。

curl -L 'https://example.com/result.mp4' -o result.mp4

不要向成品存储域名转发 API Key。本站视频/图片 Key 只放在本站 API 请求头中。不存在通用的 /{task_id}/content 开发者下载接口；不要混用其他渠道文档中的路径。

任务列表与轮询建议

GET /api/v3/contents/generations/tasks?limit=20
GET /api/v3/images/generations/tasks?limit=20

返回 object: "list"、data[]、has_more；limit 最大 100。列表返回当前用户的最近任务，也可以使用专属线路前缀筛选。此接口没有游标分页，不要只因 has_more=true 就反复请求同一页。

推荐 15 至 30 秒查询一次本站任务；查询只是读取本站状态，不保证每次都会主动请求上游。网络错误或 429 应延后重试。成功/失败后停止，避免无效请求。无需回调地址也可完成完整流程。

素材 URL

推荐公开 HTTPS 地址：服务器能直接访问，无登录或 Cookie 依赖，不指向局域网、回环地址或私有网络。签名链接必须在素材准备期间保持有效，不能只保证浏览器此刻可打开。

本地上传并不等于公开 URL。如果集成方持有本地文件，先使用自己的存储或素材服务取得适合目标线路的 URL。网页上传接口依赖登录会话，不应假设可直接使用 API Key 调用。

新增四个 _s 图片模型只需参考图 URL，不要求再上传到模型供应方。历史线路的内联图片或素材上传方式见旧文档，不推断所有线路支持 Base64。

素材顺序与数量

• 选择一种素材写法，避免在 images、image_urls、references 中重复传同一素材。
• 提示词里引用素材时，顺序必须与提交数组一致。
• 视频线路可能分别限制图片数、音频数、视频数、总素材数、各类累计时长。
• 图片线路按目标模型的参考图上限校验；多份生成不会自动扩大参考图上限。
• 仅在目标线路支持时使用音频、视频参考、首尾帧或遮罩。

seed、draft 与其他可选能力

种子、草稿、音频和超分不是平台所有模型的通用能力。当前协议视频 API 接受 seed，值必须是安全整数且目标模型支持。draft 目前没有在统一 API 的协议请求适配中转发，不能因为网页支持草稿就认为 API 的 draft 会生效。其他特殊参数按实际接口与线路能力使用，未声明的参数不要盲目追加。

draft 不能被当成自动免费超分或自动两次生成。本站创建、查询和计费以实际线路参数为准；网页展示的模型能力不代表所有接口路径都会接受同样字段。

避免重复创建

每个业务订单固定一个 Idempotency-Key。重试创建时应保持线路、提示词、素材、秒数、清晰度、份数和其他参数不变。

• 同一 Key 的幂等响应可能含 idempotent: true，应继续处理已有任务 ID；该字段不能作为所有接口唯一的重放判据。
• 旧异步接口与协议线路的冲突处理不完全相同，不要依赖“改参数再复用 Key”触发某个统一错误；修改参数应使用新订单、新 Key。
• 创建 HTTP 超时或断网，不代表任务未创建。优先用同一 Key 和原参数重试，或查询已保存的任务 ID。
• 已接收的任务尚未终态时，不要自动换新 Key 重发。
• 最终失败后决定重新生成，是新的业务请求，不是对原任务无条件重试。

协议视频线路必须提供幂等值，可使用 Idempotency-Key 或请求体 idempotency_key，推荐统一放请求头。历史异步线路建议提供但不统一强制；同步图片接口是否强制由服务器配置决定。不带显式 Key 时，不能假定获得完全相同的重试保障。

传统异步接口可能在修改提示词或设置后仍返回原任务，不保证比较完整请求参数；同步图片参数冲突为 409 idempotency_conflict，协议线路指纹冲突当前为 400。不要故意复用 Key 测试是否会创建第二个任务。

积分与份数

创建任务时，服务器按线路、时长/分辨率、份数等实际参数检查额度并进行预占。每份任务分别结算；失败时按现行线路策略消费或释放预占。不要以 HTTP 超时、一次上游查询错误或 progress=0 自行认定最终失败。

usage.points 描述任务额度，不是余额接口，也不是再次扣款指令。价格以服务器当前配置为准；创建后已保存的任务参数与额度不应由 SDK 擅自改写。

HTTP 错误

视频/图片异步接口通常返回类似结构，具体 code 以响应为准：

{
  "error": {
    "code": "BadRequest",
    "message": "请求参数无效，请检查线路和素材"
  }
}

错误字段不保证总有 request_id。调用方应兼容新增字段与不同接口的错误码，不依赖错误信息文本作为唯一判断依据。

异步与同步不要混用

生成和查询使用相同业务 Key。新增四个 _s 模型使用异步接口，不要自行拼接 /{新增模型}/v1/images/generations。

OpenAI 兼容图片调用

curl 'https://canseedream.com/v1/images/generations' \
  -H 'Authorization: Bearer sk_img_YOUR_IMAGE_KEY' \
  -H 'Idempotency-Key: sync-image-order-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "一只橘猫坐在窗边",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

{
  "created": 1791072000,
  "data": [{"url": "https://example.com/result.png"}]
}

以上只展示关键字段。同步响应可通过 X-Task-Id、X-Request-Id 响应头关联任务与请求。该接口是否开放由服务器配置决定，关闭时可能返回 404；默认通常要求有限额度的图片 Key，不适用视频 Key。504 表示同步等待结束，不保证原任务已停止，使用同一 Key 和原参数重试。

原有专属接口与旧版文档

• 原有图片异步专属地址保留：/gptimg-2.5/api/v3/images/generations/tasks、/nano2/api/v3/images/generations/tasks、/nano2pro/api/v3/images/generations/tasks。
• 原有 GPT Image 2.5 同步地址保留：/gptimg-2.5/v1/images/generations、/gptimg-2.5/v1/images/edits。
• 图片编辑的 multipart、URL、内联素材，以及历史模型的高级参数，参见 旧版文档 或 旧版 Markdown。
• 原有地址不会因为文档改版被删除或重定向到新的请求格式。
• 本页的新旧入口只切换文档，不切换用户账号、默认线路或 API 版本。

进入文本Key / 模型售价 / 消费账单 →

账号与积分

复用本站账号，使用专用 sk_txt_ Key；视频、图片Key不通用。文本专用积分优先，不足自动补通用积分，无须用户划转。Key额度是消费上限，不是独立充值余额。100积分=1元保持不变。

模型与协议

GET /text/v1/models
POST /text/v1/responses
POST /text/v1/messages
POST /text/v1/chat/completions

先查看当前公开模型目录。以下 YOUR_PUBLIC_MODEL_ID 与Key为占位符，必须替换；模型各自支持的协议、能力和售价不同。不要传媒体的 model: "video" 或 provider_route。

Responses / Codex

curl 'https://canseedream.com/text/v1/responses' \
  -H 'Authorization: Bearer sk_txt_YOUR_TEXT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_PUBLIC_MODEL_ID","input":"请简洁解释什么是HTTP。","max_output_tokens":256,"stream":true}'

Codex自定义供应商Base URL为本站 /text/v1，wire_api使用 responses。工具由客户端执行，网关不运行用户代码。

Messages / Claude Code

curl 'https://canseedream.com/text/v1/messages' \
  -H 'x-api-key: sk_txt_YOUR_TEXT_KEY' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_PUBLIC_MODEL_ID","max_tokens":256,"messages":[{"role":"user","content":"请简洁解释什么是HTTP。"}],"stream":true}'

Claude Code Base URL为本站 /text，使用后台公开模型ID与文本Key。辅助 messages/count_tokens、responses/compact 原生转发是否可用需要实际验证上游。

费用与异常

按请求时价格快照和完整可信usage分别计算普通输入、缓存读写、5分钟/1小时缓存写入及输出。缓存和推理token不重复收费。不保存提示词、回答或流式片段。

先保守预算预占，最后释放多余预占。冻结金额不是最终费用；按总费用向上舍入到0.000001积分，不设置一积分最低收费。含图片/加密压缩上下文的输入预算采用配置的模型输入能力上限，可能明显大于实际费用。

客户端断线后有限收尾收集终态用量，不自动重发生成。缺少完整可信用量时不伪造账单，释放剩余预占并保留异常记录；不能因此认定上游没有收费。终态usage先持久化，再交付终止块；过期恢复独立于媒体worker。

边界与账单

首版只支持无本站服务端会话存储的HTTP JSON/SSE，不支持 store:true、previous_response_id、conversation、后台生成或WebSocket。尚未配置收费的托管搜索、代码执行、图片生成及priority/fast加速等级不开放。原生函数工具、思考和缓存参数保持透传。

前台消费默认汇总，明细游标分页；UTC日统计。不得用媒体的cstask查询格式轮询文本，也不需要人工逐条核对任务。

重试与主动重新生成

相同内容不再自动拦截：未传 Idempotency-Key 时每次提交是新请求，可能独立计费。主动重新生成请使用新键；同一请求网络重试请保持原键、原参数和原文本Key。

同键同参数且缓存可用时重放原JSON/SSE，处理中可接续输出，不再次调用上游或扣费；响应头 X-Request-Id 保持原请求ID，X-Idempotent-Replay: true 标识重放。同键换参数返回 400 TEXT_IDEMPOTENCY_CONFLICT。

响应只在内存短期保留：单条最多4MiB、全局16MiB，完成后最多10分钟，可能因容量或进程重启失效。无法恢复时返回 410 TEXT_RESPONSE_UNAVAILABLE，不会偷偷重发上游。先核对原账单；明确要重新生成时再用新键。