私有协议兼容层（旧系统迁移）

为旧系统客户端保留的 /server/* 端点，字段与错误文案逐字兼容；新接入请使用标准协议。

调用

POST/server/api/call

字段	类型		说明
apiKey	string	必填	旧系统 API Key（ak- 开头）。
model	string	必填	模型编码（与旧系统一致）。
clientRequestId	string	可选	幂等键；相同键在 24 小时内返回首次结果。
content / messages / prompt …	any	可选	其余字段按模型类型透传上游。
stream	boolean	可选	standard_v1 档案下为真实 SSE；legacy_v1 缓冲返回。

视频模型bash

curl https://www.link42.ai/server/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "ak-…",
    "model": "seedance-2.0",
    "clientRequestId": "9d7258b0da1c42dfad49d18bfd5e4adb",
    "content": [{"type": "text", "text": "海边日出，缓慢推镜"}],
    "duration": 5, "resolution": "720p", "ratio": "16:9", "generate_audio": true, "watermark": false
  }'

响应json

{"id": "cgt-2026…"}

错误按旧系统文案返回，例如 {"code":-1,"message":"user remainingAmount is not enough"}。

查询结果

POST/server/api/getResult

字段	类型		说明
id	string	可选	任务 ID（与 clientRequestId 二选一）。
clientRequestId	string	可选	提交时的幂等键。

响应（追加计费字段）json

{
  "id": "cgt-2026…", "model": "seedance-2.0", "status": "succeeded",
  "content": {"video_url": "https://…/video.mp4"},
  "usage": {"completion_tokens": 246840, "total_tokens": 246840},
  "provider_task_id": "cgt-2026…",
  "client_request_id": "9d7258b0da1c42dfad49d18bfd5e4adb",
  "billing_time": 1765683800,
  "billing_status": "succeeded",
  "actual_cost": 1.819440,
  "currency_or_credit_type": "USD"
}

查询余额

POST/server/user/getAmountByApiKey

响应json

{"code": 0, "data": {"username": "…", "totalAmount": "120.00", "walletAmount": "87.42", "useAmount": "32.58"}}

该端点有独立限流。

素材接口

POST/server/asset/create

旧系统的五个素材端点原样保留。请求体里的 apiKey 用于鉴权并在转发前删除，其余字段透传到当前用户在上游素材库的分组；上游返回体逐字回传，不做包装。

端点	请求体	成功返回
POST /server/asset/list	{apiKey, Filter{Statuses, Name}, PageNumber, PageSize, SortBy, SortOrder}	上游分页结果原样返回；上游不可用时返回 {"code":0,"message":"success"}
POST /server/asset/create	{apiKey, Name, URL, AssetType}	上游返回体原样返回，含 Result.Id
POST /server/asset/get	{apiKey, Id}	上游返回体原样返回，含 Result.Id 与 Result.Status
POST /server/asset/update	{apiKey, Id, Name}	上游返回体原样返回
POST /server/asset/delete	{apiKey, Id}	上游返回体原样返回

创建素材bash

curl https://www.link42.ai/server/asset/create \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "ak-…",
    "Name": "opening-shot",
    "URL": "https://example.com/clip.mp4",
    "AssetType": "Video"
  }'

失败响应json

{"code": -1, "message": "add asset error"}

错误一律以 HTTP 200 返回 {"code": -1, "message": "…"}，文案逐字兼容旧系统：apiKey is null、apiKey not exist、apiKey disabled、add asset error、get asset error、update asset error、delete asset error、call api error。
apiKey 从请求体读取；请求体里没有时也接受 Authorization: Bearer 或 x-api-key 头。
list 只返回当前用户自己的素材分组。get / update / delete 只接受属于当前用户的素材 Id，跨用户访问返回对应的 … error 文案。create 未传 Name 时自动生成 asset-{yyyyMMddHHmmss}-{8 位随机}，AssetType 支持 Video / Audio / Image，缺省时按 URL 扩展名推断。

getResult 的档案差异

同一个 getResult 请求在两种兼容档案下的响应形状不同。迁移过来的 ak- 密钥是 legacy_v1，新建的 sk- 密钥是 standard_v1。

场景	legacy_v1	standard_v1
任务仍在进行（含本地排队）	空响应体	{"id": "…", "status": "queued"}
任务不存在或不属于该密钥	空响应体	{"code": -1, "message": "task not found"}
actual_cost 类型	JSON 数字，例如 1.819440	JSON 字符串，例如 "1.819440"
clientRequestId 重放（视频任务）	{"id": "…"}，无论任务处于什么状态	{"id": "…"}，无论任务处于什么状态
stream=true 的文本调用	整段 SSE 缓冲成一个响应体	逐帧转发的真实 SSE

本地排队状态 local_queued 从不出现在私有协议里：旧客户端从未见过这个值，所以 standard_v1 报告为 queued，legacy_v1 报告为空体。
id 与 clientRequestId 同时为空时返回 {"code": -1, "message": "id and clientRequestId can not be null at the same time"}。
并发或排队受限时，私有协议把 too_many_running_tasks 映射成旧文案 get lock failed。

各模型的请求形状

/server/api/call 一个端点承载五种请求体形状，网关按 model 决定转发到哪个上游形态。apiKey 与 clientRequestId 在转发前一律删除，其余字段原样透传，只有 model 会被改写成上游模型名。

请求形状	适用模型	请求体	返回
content[] 视频任务	10 个 Seedance 模型	content[]（text / image_url / video_url / audio_url）；2.x 另有 resolution、duration、ratio、generate_audio、watermark	只返回 {"id": "cgt-…"}，结果要用 /server/api/getResult 取
prompt 图片	4 个 Seedream 模型	prompt、size、response_format、sequential_image_generation、watermark；5.0 Pro 另有 image[]	同步返回 {model, created, data[], usage}
messages[] 对话	Seed 2.0 pro / lite / mini、Seed 2.1 turbo、DeepSeek V4 Pro / Flash（-260425）、GLM-5.2（-260617）	OpenAI chat 形状的 messages[]	同步返回 OpenAI chat.completion 形状，带 choices[]
input[] Responses	Seed-1.6、DeepSeek-3.2	input[]；DeepSeek-3.2 可带 tools	同步返回 Responses 形状，object 为 response，带 output[]
contents[] Gemini	Gemini3-pro	contents[]、generationConfig、safetySettings	同步返回 Gemini 形状，带 candidates[] 与 usageMetadata
prompt 单轮	阿里云百炼的 glm-5.2 等已配置单轮模型；不要把国内火山 DeepSeek-V4-Pro / Flash 当作此类接口	只有一个顶层 prompt 字符串	同步返回 {content, model, usage} 顶层形状，没有 choices

同名不同后缀的模型不是同一个：deepseek-v4-pro / deepseek-v4-flash 当前绑定国内火山方舟（其中 Pro 暂未开通），带 -260425 后缀的历史行走 BytePlus；glm-5.2 与 glm-5-2-260617 也分别属于不同上游。迁移时按实时目录里的模型 ID 逐字照抄，不要按名字猜。
每个模型的差异字段、计费口径与限制见对应协议页的「按模型对照」表。

私有协议兼容层（旧系统迁移）

为旧系统客户端保留的 /server/* 端点，字段与错误文案逐字兼容；新接入请使用标准协议。

调用

POST/server/api/call

字段	类型		说明
apiKey	string	必填	旧系统 API Key（ak- 开头）。
model	string	必填	模型编码（与旧系统一致）。
clientRequestId	string	可选	幂等键；相同键在 24 小时内返回首次结果。
content / messages / prompt …	any	可选	其余字段按模型类型透传上游。
stream	boolean	可选	standard_v1 档案下为真实 SSE；legacy_v1 缓冲返回。

视频模型bash

curl https://www.link42.ai/server/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "ak-…",
    "model": "seedance-2.0",
    "clientRequestId": "9d7258b0da1c42dfad49d18bfd5e4adb",
    "content": [{"type": "text", "text": "海边日出，缓慢推镜"}],
    "duration": 5, "resolution": "720p", "ratio": "16:9", "generate_audio": true, "watermark": false
  }'

响应json

{"id": "cgt-2026…"}

错误按旧系统文案返回，例如 {"code":-1,"message":"user remainingAmount is not enough"}。

查询结果

POST/server/api/getResult

字段	类型		说明
id	string	可选	任务 ID（与 clientRequestId 二选一）。
clientRequestId	string	可选	提交时的幂等键。

响应（追加计费字段）json

{
  "id": "cgt-2026…", "model": "seedance-2.0", "status": "succeeded",
  "content": {"video_url": "https://…/video.mp4"},
  "usage": {"completion_tokens": 246840, "total_tokens": 246840},
  "provider_task_id": "cgt-2026…",
  "client_request_id": "9d7258b0da1c42dfad49d18bfd5e4adb",
  "billing_time": 1765683800,
  "billing_status": "succeeded",
  "actual_cost": 1.819440,
  "currency_or_credit_type": "USD"
}

查询余额

POST/server/user/getAmountByApiKey

响应json

{"code": 0, "data": {"username": "…", "totalAmount": "120.00", "walletAmount": "87.42", "useAmount": "32.58"}}

该端点有独立限流。

素材接口

POST/server/asset/create

端点	请求体	成功返回
POST /server/asset/list	{apiKey, Filter{Statuses, Name}, PageNumber, PageSize, SortBy, SortOrder}	上游分页结果原样返回；上游不可用时返回 {"code":0,"message":"success"}
POST /server/asset/create	{apiKey, Name, URL, AssetType}	上游返回体原样返回，含 Result.Id
POST /server/asset/get	{apiKey, Id}	上游返回体原样返回，含 Result.Id 与 Result.Status
POST /server/asset/update	{apiKey, Id, Name}	上游返回体原样返回
POST /server/asset/delete	{apiKey, Id}	上游返回体原样返回

创建素材bash

curl https://www.link42.ai/server/asset/create \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "ak-…",
    "Name": "opening-shot",
    "URL": "https://example.com/clip.mp4",
    "AssetType": "Video"
  }'

失败响应json

{"code": -1, "message": "add asset error"}

错误一律以 HTTP 200 返回 {"code": -1, "message": "…"}，文案逐字兼容旧系统：apiKey is null、apiKey not exist、apiKey disabled、add asset error、get asset error、update asset error、delete asset error、call api error。
apiKey 从请求体读取；请求体里没有时也接受 Authorization: Bearer 或 x-api-key 头。
list 只返回当前用户自己的素材分组。get / update / delete 只接受属于当前用户的素材 Id，跨用户访问返回对应的 … error 文案。create 未传 Name 时自动生成 asset-{yyyyMMddHHmmss}-{8 位随机}，AssetType 支持 Video / Audio / Image，缺省时按 URL 扩展名推断。

getResult 的档案差异

同一个 getResult 请求在两种兼容档案下的响应形状不同。迁移过来的 ak- 密钥是 legacy_v1，新建的 sk- 密钥是 standard_v1。

场景	legacy_v1	standard_v1
任务仍在进行（含本地排队）	空响应体	{"id": "…", "status": "queued"}
任务不存在或不属于该密钥	空响应体	{"code": -1, "message": "task not found"}
actual_cost 类型	JSON 数字，例如 1.819440	JSON 字符串，例如 "1.819440"
clientRequestId 重放（视频任务）	{"id": "…"}，无论任务处于什么状态	{"id": "…"}，无论任务处于什么状态
stream=true 的文本调用	整段 SSE 缓冲成一个响应体	逐帧转发的真实 SSE

本地排队状态 local_queued 从不出现在私有协议里：旧客户端从未见过这个值，所以 standard_v1 报告为 queued，legacy_v1 报告为空体。
id 与 clientRequestId 同时为空时返回 {"code": -1, "message": "id and clientRequestId can not be null at the same time"}。
并发或排队受限时，私有协议把 too_many_running_tasks 映射成旧文案 get lock failed。

各模型的请求形状

请求形状	适用模型	请求体	返回
content[] 视频任务	10 个 Seedance 模型	content[]（text / image_url / video_url / audio_url）；2.x 另有 resolution、duration、ratio、generate_audio、watermark	只返回 {"id": "cgt-…"}，结果要用 /server/api/getResult 取
prompt 图片	4 个 Seedream 模型	prompt、size、response_format、sequential_image_generation、watermark；5.0 Pro 另有 image[]	同步返回 {model, created, data[], usage}
messages[] 对话	Seed 2.0 pro / lite / mini、Seed 2.1 turbo、DeepSeek V4 Pro / Flash（-260425）、GLM-5.2（-260617）	OpenAI chat 形状的 messages[]	同步返回 OpenAI chat.completion 形状，带 choices[]
input[] Responses	Seed-1.6、DeepSeek-3.2	input[]；DeepSeek-3.2 可带 tools	同步返回 Responses 形状，object 为 response，带 output[]
contents[] Gemini	Gemini3-pro	contents[]、generationConfig、safetySettings	同步返回 Gemini 形状，带 candidates[] 与 usageMetadata
prompt 单轮	阿里云百炼的 glm-5.2 等已配置单轮模型；不要把国内火山 DeepSeek-V4-Pro / Flash 当作此类接口	只有一个顶层 prompt 字符串	同步返回 {content, model, usage} 顶层形状，没有 choices

同名不同后缀的模型不是同一个：deepseek-v4-pro / deepseek-v4-flash 当前绑定国内火山方舟（其中 Pro 暂未开通），带 -260425 后缀的历史行走 BytePlus；glm-5.2 与 glm-5-2-260617 也分别属于不同上游。迁移时按实时目录里的模型 ID 逐字照抄，不要按名字猜。
每个模型的差异字段、计费口径与限制见对应协议页的「按模型对照」表。