API 接入文档

1. 接入前准备

1）登录站点，在控制台「API 密钥」页创建一把密钥。密钥形如 sk-live-...，明文只在创建时显示一次，请立即保存到安全位置；平台只保存其哈希，丢失后只能删除重建。

2）OpenAI 协议的 Base URL 为 https://cresily.cn/v1； Anthropic SDK 的 Base URL 使用 https://cresily.cn，由 SDK 自动追加 /v1/messages。

3）每次请求携带鉴权头，二选一：

Authorization: Bearer sk-live-xxxxxxxx
# 或
x-api-key: sk-live-xxxxxxxx

POST 请求还需 Content-Type: application/json; charset=utf-8。密钥是账号级凭证：不要写进前端页面、公开仓库或日志；泄露后请到控制台立即删除。

Agent 工具接入

先从 /v1/models?kind=chat 选择模型。Agent 执行工具需要所选模型的 chat_limits.supportsTools 为 true，输入与输出预算也应按该模型配置。DSH 请添加「自定义模型 API」，选择对应协议，模型输入类型先选「文本」。

控制台「API 密钥 → 接入配置」可选择并复制 OpenAI 兼容、Codex、Anthropic SDK 或 Continue 配置。配置仅包含密钥占位符；完整密钥需使用创建时保存的值。

Codex 的配置示例：将模型 ID 替换为目录中的值，并在运行环境中设置 PLATFORM_API_KEY 为平台密钥。

model = "目录中的模型ID"
model_provider = "platform"
web_search = "disabled"

[model_providers.platform]
name = "平台 API"
base_url = "https://cresily.cn/v1"
env_key = "PLATFORM_API_KEY"
wire_api = "responses"
supports_websockets = false
requires_openai_auth = false

[model_providers.platform.capabilities]
remote_compaction = "unsupported"

Responses 接口为 POST /v1/responses：支持 instructions、完整 input 历史、函数工具、命名空间、additional_tools 与自定义文本工具。流式返回 response.created、文本与工具参数分片，以及 response.completed；达到输出上限返回 response.incomplete，失败返回 response.failed。

Messages 接口为 POST /v1/messages：支持 system、文本内容块、tool_use、tool_result、max_tokens 与 HTTP SSE。接受 x-api-key、anthropic-version；错误使用 Messages 格式返回。两种接口均使用平台模型 ID 和平台密钥。

2. 端点总览

所有端点支持跨域调用（OPTIONS 返回 204），以 API Key 鉴权、不依赖 Cookie。 模型可用范围、参数取值、是否支持某个可选字段，全部以 /v1/models?expand=parameters 下发的参数说明为准。

请求体只接受 JSON，大小上限：对话 ≤ 8 MiB，图片 / 视频 ≤ 2MB，音频 ≤ 1MB，超出返回 413 request_too_large； 不接受文件上传与 base64 图片（参考素材请先放到公网 HTTPS 地址再传 URL）。

3. 模型与参数

调用任何接口前，先用模型列表确认可用的模型与它支持的参数。列表只包含 平台已开放的模型（未开放的不会出现），并且已经按 Key 的模型白名单过滤：Key 限定了模型时，列表里只会有这些模型， 调用白名单之外的模型返回 403 model_not_allowed。

3.1 模型列表

列表响应形如 { "object": "list", "schema_version": "...", "data": [ ... ] }； 详情响应就是单个模型对象。未开放或不存在 → 404 model_not_found。

3.2 模型对象字段

3.3 用展示名称调用

name 与 id 都可以写进请求体的 model，平台会解析到同一个模型 （大小写不敏感；前后空格会被忽略）。如果两个模型的展示名称相同，请求会返回 400 invalid_parameter 并提示改用 id——不会替调用方猜用哪个模型。

3.4 参数说明（parameters）

每个参数是一个描述符对象，用 type 区分类型，并按类型附带约束：

媒体槽位（slot）取值：reference_image、first_frame、last_frame、reference_video、reference_audio； 它是「这张素材用在哪个位置」，请求字段仍以 5.2–5.4 的字段名为准。

4. 生成类接口的异步任务协议

图片、视频、音频三个生成端点使用同一套协议：创建成功返回 HTTP 202 与一个任务对象， 响应头 Location 指向任务查询地址；客户端按 status 轮询， 终态后从 output.urls[].url 下载结果。

POST /v1/images/generations
→ HTTP/1.1 202 Accepted
   Location: /v1/tasks/task_xxxxxxxx
   X-Request-Id: req_xxxxxxxx

{
  "id": "task_xxxxxxxx",
  "object": "task",
  "kind": "image",
  "model": "your-model-id",
  "status": "queued",
  "created_at": 1761300000,
  "expires_at": 1761386400,
  "usage": { "credits_reserved": 12.5, "credits_charged": null, "settled": false }
}

status 的取值：queued（排队中）、in_progress（生成中）、completed（成功）、failed（失败）、canceled（已取消）。只有后三个是终态，前两个需要继续轮询。

轮询建议：起始间隔 2 秒，逐次退避到 10 秒；响应带 Retry-After（秒）时优先按它等待。 任务记录在完成后 3 天内可查询，expires_at 是查询截止时间（Unix 秒），超时后查询返回 404 task_not_found。

任务对象字段

结果 URL 与下载

成功任务的 output.urls[].url 是平台签名地址，有效期 24 小时；在任务查询期内重新查询 /v1/tasks/{id} 会重新签发。 下载时直接 GET 该地址即可（签名即凭证），不要把签名地址当作长期存储地址。 成品本身只保留 3 天（见下一小节），请及时转存。

产物保留与过期（3 天）

通过 API 生成并交付的成品文件（图片 / 视频 / 音频）只保留 3 天： 任务对象里的 media_expires_at 就是成品保留截止时间（Unix 秒），等于任务完成时刻 + 3 天。 任务查询截止时间 expires_at 与它一致（同为完成时刻 + 3 天）。

说明：以上保留策略只针对通过 API 生成的成品；你在站内（控制台、创作页面等）直接生成的内容 不在此清理范围，按站内既有规则保留。

幂等：Idempotency-Key

生成类接口建议带 Idempotency-Key 请求头（8–200 字符，可用字符A-Z a-z 0-9 . _ : -）。同一把 Key、同一请求体、同一个幂等键重复提交时， 服务端不会新建任务，而是返回首次创建的任务，并带响应头 Idempotency-Replayed: true；同一幂等键配不同请求体则返回 409 idempotency_conflict。

不带该头时每次请求都是新任务（会重复计费）。幂等键建议使用业务订单号等稳定值， 不要每次重试都换一个新值。对话接口不支持幂等重放，请勿对 /v1/chat/completions 依赖该头。

5. 请求字段

所有 POST 请求都必填 model：可以用 /v1/models 返回的 id，也可以直接用列表里的展示名称（name），两者等价。 字段名校验是严格模式：未定义的字段返回 400 unknown_parameter；模型不支持的可选字段返回 400 unsupported_parameter；取值越界或互相冲突返回 400 invalid_parameter。服务端不会静默忽略或自动修正参数。

下文提到的「模型 schema / 参数说明」指 /v1/models?expand=parameters（或单模型详情）返回的 parameters：里面出现了的字段才代表该模型当前支持，取值域也以它为准。

5.1 对话 /v1/chat/completions

兼容 WorkBuddy 消息中的 agent、conversationRequestId、rootRequestId（string），以及 startsNewUserRequest、isMeta、isAdditionalData、isCompactInternal、isSummary、isSubAgent（boolean）。 平台校验类型后移除这些客户端标记，不转发给模型，不计入输入 Token 估算；其他未支持的消息字段仍返回 400。

支持 stop（非空字符串或最多四项的非空字符串数组）、reasoning_effort、verbosity 与 response_format（text / json_object / json_schema）；需所选模型支持，实际转发给模型。 已知可选参数的 null 按未指定处理。兼容 n=1、store=false；metadata、prompt_cache_key、safety_identifier 校验后只作兼容接收，不提供存储、缓存命中或额外风控保证。Responses 的推理摘要与 include 为兼容提示，不保证返回推理摘要或加密内容。

聊天接口还支持 seed（安全整数）、presence_penalty 与 frequency_penalty（-2 到 2），所选模型需支持。兼容接收 logprobs=false、top_logprobs=0、空 logit_bias、service_tier=auto/default 与缓存保留提示；不承诺日志概率、优先调度或缓存保留。历史消息的空 tool_calls、空 refusal/audio 及 annotations 注释会被归一化。

工具调用支持 tools（函数定义）、tool_choice（auto / none / required 或指定函数）与 parallel_tool_calls。 工具调用返回在 tool_calls 中（流式响应位于 delta.tool_calls），正常完成时 finish_reason 为 tool_calls。 调用方执行工具后，以 role: tool 与对应的 tool_call_id 提交结果。所选模型需支持该能力。

模型详情的 chat_limits 提供独立的上下文窗口、最大输入、最大输出、默认输出预算及消息限制。 上下文窗口包含输入与输出预算；输入 Token 为估算，最终以模型实际分词结果为准。工具定义、参数、结果与结构化输出定义均计入输入估算与报价。 未配置字符上限时不额外限制单条消息；请求体仍受 8 MiB 传输保护。

响应为非流式时是标准 chat.completion 对象；流式时是 OpenAI 兼容 SSE 分片。usage 中 prompt_tokens / completion_tokens / total_tokens 对应本次实际用量，终局分片会带上 usage（个别模型不回报用量时会省略该字段，平台不会编造 token 数）。

本期不支持的参数（传入返回 400， 不会被悄悄忽略）：多结果 n>1、旧式 functions、function_call、logprobs=true、top_logprobs>0、非空 logit_bias、优先服务级别、store=true、modalities、audio、prediction。

5.2 图片 /v1/images/generations

5.3 视频 /v1/videos/generations

n（生成条数）本期不开放：每次请求生成 1 条视频，传入 n 返回 400。

视频模式与媒体字段的互斥关系

参考媒体只接受公网 HTTPS 地址；内网地址、http://、data: 本地路径一律 400 invalid_media。参考视频/音频的时长由服务端自行探测（用于计费与时长预算）， 探测失败同样返回 invalid_media。

5.4 音频 /v1/audio/generations

音频接口只认 input 作为文本字段；prompt、text、format、n、stream 等其它写法返回 400。voice / response_format / speed / duration 都是「模型声明才可用」的可选字段。

5.5 特殊模型：先读 schema，再决定传什么

端点和协议对所有模型一致，但可传字段不保证一致。同一个请求体在 A 模型能跑通、在 B 模型返回 400，是最常见的失败原因。 判断依据只有一处：/v1/models/{id}?expand=parameters 里该模型的parameters。下面四类差异最需要提前处理：

6. 响应头与错误码

响应头

错误对象

所有失败响应都是同一形态的 JSON（message 为稳定英文，可直接展示）：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_media",
    "message": "image_urls[1] is not a public HTTPS URL.",
    "param": "image_urls[1]",
    "request_id": "req_xxxxxxxx",
    "retryable": false
  }
}

错误码

7. 任务取消语义

调用 POST /v1/tasks/{id}/cancel 取消任务。是否全额退积分取决于任务是否已经开始执行：

取消成功后返回任务对象；取消成功不等于一定全额退款，请以响应里的 status 与 usage 为准（settled: true 时 credits_charged 为最终扣费）。

8. 日额度与用量查询

每把 Key 可在控制台设置每日积分上限（单位：积分；0 = 不限额，默认不限额）。上限按 Asia/Shanghai 自然日累计当天已冻结的积分； 超过上限的生成请求返回 429 daily_quota_exceeded，冻结的积分会被释放、任务不会开始执行。

口径说明：日用量按「请求创建时冻结的积分」累计，失败/取消退回的积分不会回冲当日累计。 因此该限额偏保守（可能提前拦截，不会漏拦）。

用 GET /v1/me 查询 Key 信息、今日用量与账户余额：

{
  "object": "api_key",
  "id": "key_xxxxxxxx",
  "name": "生产环境",
  "prefix": "sk-live-xxxx",
  "status": "active",
  "created_at": 1792900000,
  "expires_at": null,
  "rpm_limit": 60,
  "daily_credit_limit": 100,
  "model_ids": [],
  "usage": {
    "today": { "date": "2026-10-25", "credits": 3.23, "requests": 5 },
    "balance_credits": 931.5461,
    "currency": "credits"
  }
}

字段说明：daily_credit_limit 为 0 表示不限额；model_ids 为空数组表示可调用全部已开放模型；expires_at 为 null 表示永久有效；金额单位均为积分（最多 4 位小数）， 时间戳为 Unix 秒。balance_credits 在暂时读不到余额时为 null（不要据此认定 Key 失效）。

9. 调用示例

9.1 对话（非流式）

curl -sS -X POST "https://cresily.cn/v1/chat/completions" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      { "role": "system", "content": "你是一个简洁的助手。" },
      { "role": "user", "content": "用一句话介绍你自己。" }
    ],
    "stream": false,
    "max_tokens": 512
  }'

需要流式输出时，把 stream 改为 true 并按 SSE 读取 data: 行，直到收到 data: [DONE]。

9.2 图片生成（创建 + 轮询）

# 1) 创建任务：202 + task。Idempotency-Key 建议用业务订单号，防重试时重复扣费
curl -sS -X POST "https://cresily.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1024-1" \
  -d '{
    "model": "your-model-id",
    "prompt": "海边日落，电影感",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "n": 1
  }'

# 2) 轮询任务（把 task_xxx 换成上一步返回的 id）
curl -sS "https://cresily.cn/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-live-xxxxxxxx"

# 3) status 为 completed 后，从 output.urls[0].url 直接下载（签名地址 24 小时有效）
#    成品只保留 3 天（media_expires_at），请立即转存；需要取消时：POST /v1/tasks/task_xxxxxxxx/cancel

用同一把 Key、同一请求体、同一 Idempotency-Key 重复执行第 1 步是安全的： 会返回同一个任务并带 Idempotency-Replayed: true，不会重复扣费。

9.3 视频生成（创建 + 轮询）

# 1) 创建任务（文生视频）：202 + task
curl -sS -X POST "https://cresily.cn/v1/videos/generations" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-B-1" \
  -d '{
    "model": "your-model-id",
    "prompt": "海边日落，镜头缓慢推进，电影感",
    "mode": "text_to_video",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

# 2) 轮询任务（轮询节奏与图片一致）
curl -sS "https://cresily.cn/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-live-xxxxxxxx"

# 3) status 为 completed 后，从 output.urls[0].url 下载（签名地址 24 小时有效）
#    成品只保留 3 天，请立即转存

做图生视频时把 mode 换成 first_frame 并传首帧first_frame_url（公网 HTTPS URL）；首尾帧用 first_and_last_frame 再补 last_frame_url。mode 省略时由传入的媒体字段推断。duration、resolution、generate_audio 等均为按模型提供的可选字段， 模型参数说明里没有就表示当前不支持（传入返回 400，不会静默丢弃）。

9.4 音频生成（创建 + 轮询）

# 1) 创建任务：202 + task（文本字段固定是 input）
curl -sS -X POST "https://cresily.cn/v1/audio/generations" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-C-1" \
  -d '{
    "model": "your-model-id",
    "input": "欢迎使用本平台的语音合成接口。",
    "voice": "your-voice-id",
    "response_format": "mp3",
    "speed": 1.0
  }'

# 2) 轮询任务（与图片/视频同一套协议）
curl -sS "https://cresily.cn/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-live-xxxxxxxx"

# 3) completed 后从 output.urls[0].url 下载音频文件

音频接口只认 input 作为文本字段（prompt、text 等写法返回 400）；voice、response_format、speed、duration 都是按模型提供的可选字段，取值以模型参数说明为准。

9.5 特殊模型的写法（MJ 型 / 图片编辑型 / 仅图生视频型）

下面三段是按能力签名给的， 不是按某个具体模型名给的：先看 /v1/models/{id}?expand=parameters里有没有 speed_mode、字段是否标 required、image_urls 的 minItems 是几，再挑对应写法。

# ① MJ 型（schema 里有 speed_mode）：n 只能 1，一次交付 4 张、按 4 张计费
curl -sS -X POST "https://cresily.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-D-1" \
  -d '{
    "model": "your-model-id",
    "prompt": "海边日落，电影感，细节丰富",
    "aspect_ratio": "3:2",
    "negative_prompt": "低清, 变形",
    "speed_mode": "relax"
  }'

# ② 图片编辑型（schema 里 image_urls 的 minItems ≥ 1）：不带参考图直接 400
curl -sS -X POST "https://cresily.cn/v1/images/generations" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "prompt": "把背景换成雪山，人物与服装保持不变",
    "image_urls": ["https://your-cdn.example.com/source.png"],
    "aspect_ratio": "1:1"
  }'

# ③ 仅图生视频型（schema 里 mode 没有 text_to_video）：必须给首帧
curl -sS -X POST "https://cresily.cn/v1/videos/generations" \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "prompt": "镜头缓慢推进，光线渐暗",
    "mode": "first_frame",
    "first_frame_url": "https://your-cdn.example.com/first.png",
    "duration": 5
  }'

三段的轮询与下载完全相同（GET /v1/tasks/{id} → output.urls[].url）。MJ 型要特别注意两点：n 不能大于 1；虽然 n 是 1，返回的是 4 条地址、按 4 张计费—— 客户端按 output.urls.length 展示即可，不要按 n 截断。 另外这类模型没有 resolution 维度，传了会返回 400。

10. 跨分类统一接入（一个客户端接四类模型）

如果你的接入方需要「同一套代码请求本站点不同分类下的不同模型」，请按下面的边界来设计：传输层与任务协议是统一的，请求体不是统一的。 统一的部分可以写成一份公共代码；差异部分只有三处——端点、主输入字段、分类专属字段。

10.1 完全统一、无需分支的部分

10.2 必须按分类分支的三处

10.3 推荐写法（按 kind 分支 + 参数说明驱动）

// 1) 拉一次模型清单，按 kind 建索引（缓存即可，字段是只增不删的）
const { data } = await get("/v1/models?expand=parameters");
const model = data.find((m) => m.id === modelId); // model.kind: chat|image|video|audio

// 2) 只按 kind 选端点与主输入字段
const endpoint =
  model.kind === "chat"  ? "/v1/chat/completions"
: model.kind === "image" ? "/v1/images/generations"
: model.kind === "video" ? "/v1/videos/generations"
:                          "/v1/audio/generations";

// 3) 业务参数按 schema 过滤：schema 里没有的字段不要发（发了就是 400）
const body = { model: model.id };
for (const [key, value] of Object.entries(businessParams)) {
  if (key in model.parameters) body[key] = value;
}
if (model.kind === "chat") body.messages = messages; // 主输入字段
else if (model.kind === "audio") body.input = text;
else body.prompt = text;

// 4) 交付：chat 直接拿响应；其余三类统一走「202 → 轮询 → 下载」
const res = await post(endpoint, body);
const task = res.status === 202 ? await pollTask(res.headers.get("Location")) : null;
const urls = task ? task.output.urls.map((u) => u.url) : [res.json.choices[0].message.content];

这样写出来的客户端，切换模型只需要改 modelId 与业务参数； 切换分类只影响「端点 + 主输入字段」两个变量，轮询、下载、取消、错误处理、重试与幂等全部复用。

11. 对接建议与常见问题

这一节集中说明接入时最容易踩的坑。按下面的建议实现，可以避免「请求成功、结果却和预期不符」， 也能让重试、轮询与资金处理更稳。

11.1 用参数说明驱动界面与校验

模型清单（/v1/models?expand=parameters）是唯一权威来源：先按 kind 决定用哪个端点， 再按该模型的 parameters 渲染表单并做前端校验。枚举参数只能从 values 里取值； 数值参数只能取 minimum / maximum 之间的值（有 exclusiveMinimum 时下限是开区间）； 标了 required 的字段必须传。列表里的 capability_version 变化时，刷新本地参数缓存即可。

不要硬编码参数清单：不同模型支持的字段不同，同一模型也可能随平台调整而变化。参数说明里没有出现的字段， 传了会返回 400 unsupported_parameter，不会被悄悄忽略。

11.2 媒体素材：只传公网 HTTPS

参考图、首帧、尾帧、参考视频、参考音频都只接受公网可访问的 HTTPS 地址；不支持文件上传，也不接受 base64 或本站内路径。数量、格式、单文件大小、像素、时长等限制以参数说明为准 （如 minItems / maxItems / formats / maxBytesPerFile / maxDurationSec），不满足返回 400 invalid_media。视频 / 音频参考素材的时长由平台自行探测，不要自行传入时长字段（传了会返回 400）。

11.3 幂等：让重试变成安全操作

生成类请求建议带 Idempotency-Key（8–200 字符，取业务订单号等稳定值）。 超时或失败重试时复用同一个键：同一把 Key、同一请求体、同一个键会返回同一个任务，并带 Idempotency-Replayed: true，不会重复扣费；同一键配不同请求体会返回 409 idempotency_conflict。如果要重新发起一个真正的新任务，换一个新键。 对话接口不支持幂等重放，不要对它做自动重放。

11.4 轮询与失败重试

生成类是异步的：创建得到任务后按 2 秒起步、逐步退避到 10 秒轮询；响应带 Retry-After 时按它等待。到终态（completed / failed / canceled）后停止轮询，不要并发高频刷新（有每分钟请求上限）。

11.5 Key、额度与账户

三种「不能用」要区分对待：Key 的模型白名单不含该模型 → 403 model_not_allowed； 每分钟请求数超限 → 429 rate_limit_exceeded；Key 的每日积分上限用尽 → 429 daily_quota_exceeded（每日上限为 0 表示不限额，可在控制台调整）； 账户可用积分不足 → 402 insufficient_quota（充值后再试）。 Key 信息、今日用量与余额可用 GET /v1/me 查询；控制台的「任务中心」还能查看每笔 API 任务的金额与状态，方便对账。

11.6 成品请及时转存

签名下载地址 24 小时有效，成品本身只保留 3 天（见第 4 节「产物保留与过期」）。 不要把签名地址存进数据库当长期链接：收到 completed 后立即下载并转存到自己的对象存储； 链接过期时可在保留期内重新查询任务换新链接；超过保留期无法补下载。

11.7 常见问题