API 指南

本页汇总所有模型通用的调用须知；各模型的具体调用方式，见下方「各模型指南」。

调用前必读

鉴权与端点

所有模型共用同一个 API Key 与同一个端点，请求头带 Authorization: Bearer sk-xxxxxxxx。

模型列表 `GET /v1/models`

需带 Authorization: Bearer <API Key>；只返回当前账号可见的模型。文本模型会附带实际上下文上限与能力位，客户端应以这里的返回为准。

{
  "object": "list",
  "data": [
    {
      "id": "deepseek-flash",
      "object": "model",
      "created": 0,
      "owned_by": "trellis",
      "max_model_len": 524288,
      "vision": false
    },
    {
      "id": "trellis-qwen-image",
      "object": "model",
      "created": 0,
      "owned_by": "trellis"
    }
  ]
}

max_model_len / vision 仅文本模型返回，且以网关实际值为准；deepseek-v4-flash 为 deepseek-flash 的兼容别名。

懒加载

模型按需加载：首次调用需等待加载（同步接口会变慢、视频会排队）；空闲后资源可能被驱逐，再次调用需重新加载。请为长时间等待做好超时设置。

限流与排队

分两层:平台按 API Key 限流(超过返回 429),以及网关的容量排队(超过返回 503)。后端(模型/网关)不返回 `429`。

排队控制请求头:X-Trellis-Queue-Timeout: <秒>(默认 900;0 = 不等待,队列满立即 503)。当前为 FIFO,X-Trellis-Priority 暂不支持(网关会忽略)。

客户端务必遵守 `Retry-After` 退避,不要紧循环重试;并区分提示“排队中 / 限频”与“服务重启中”。

错误处理

错误响应为 JSON（含 error.message / error.type / error.code；部分接口为 message）。常见状态码:

调用方式

同步：直接 POST 返回结果；各接口建议超时见下表，超时后请勿自动重试。LLM 仅同步（stream: true 为 SSE 流式）。

异步（推荐）：除 LLM 与视频外，所有 POST 均支持——加请求头 X-Trellis-Async: 1 提交，返回 202 {id, poll}，再轮询 GET /v1/jobs/{id}（间隔 3–5s），completed 时取 result （JSON）或 url（产物）。视频为原生异步：POST /v1/videos 返回 {id, status}，状态同样轮询 `GET /v1/jobs/{id}`（/v1/videos/{id} 已移除）。二进制产物（如 TTS 裸 wav）经 /files/gw/<job>.wav 下载。异步不受长连接超时限制。

视频参数：num_frames 须为 4n+1，且决定耗时（帧越多越慢）；fps 决定时长 = num_frames / fps、不影响耗时。用户给"时长 + 帧率"时，按 num_frames = 最近的 4n+1(秒 × fps) 换算并同时传 fps（不传 fps 时默认 16）。

取消任务

异步任务可中途取消：统一 POST /v1/jobs/{id}/cancel（视频与异步同一入口）， 立即返回 canceling；对已结束任务返回其原状态（幂等）。取消为协作式（采样步/block 边界 ≤1 步生效；模型加载中则在加载完成后再生效），并非强杀。

调用方流程：① 用户取消 → 调 cancel；② 继续轮询 GET /v1/jobs/{id} 直到 status = canceled（期间为 canceling，不要提前结束）；③ 收到 canceled 后清理状态、可重新发起。 不要依赖"关闭连接"来取消；取消 / 失败后不再产出产物、不计费。

任务状态统一为 queued / model_loading / in_progress / canceling / completed / failed / canceled（美式拼写 canceling/canceled；无 `phase` 字段，阶段只看 status）； 并新增 progress（0–100，两位小数、单调）、eta_seconds、load_elapsed_seconds 字段，可用于展示进度与预计剩余时间。

同步调用建议超时

若走同步，客户端超时必须大于「懒启动等待 + 推理耗时」；且超时后请勿自动重试——重试会让另一节点再次加载大模型并驱逐其它模型，雪上加霜。

开启 qc:true 时，在原超时基础上再加 ≥300s。

输入限制

超限返回 413 E_PAYLOAD_TOO_LARGE（num_frames 不合规返回 400）：

可选质检 qc

图 / 视频 / TTS 生成接口均支持 qc: true（默认 false）：开启后同步质检，指标随响应（图/TTS）或异步结果（视频）回显， 不额外收费，但耗时更长（图片 ≥25 分钟、TTS ≥5 分钟）。也可用独立接口单独质检：/v1/evaluations/image、 /v1/evaluations/video、/v1/evaluations/audio（按模态计费：图按张、音/视频按秒）。

产物与保留

产物保留 7 天，过期返回 404 E_NOT_FOUND（终态，不要重试；请提示"产物已过期，可重新生成"）。 产物下载 /files/* 由独立常驻服务提供，模型被驱逐/停机后仍可下载。url 出现即表示文件已完整落盘， 请勿自行拼接文件名，只用接口返回的 url。产物 url 自带命名空间 （/files/image|video|audio|music/...、异步二进制 /files/gw/<job>.<ext>），请原样使用，勿再叠加 `image/` 等前缀。

异步任务 status=failed（如 E_RESOURCE_BUSY）时 url 为 null、产物不存在：不要取文件； 如需重试请重新提交新任务（新 id），不要轮询旧任务。404（过期/不存在）不要重试；5xx 可短暂重试。

模型选型（按场景选模型）

各模型指南