API
OpenAPI 规范与 SDK
导入 Postman / Insomnia / Swagger UI,或直接生成带类型的客户端
OpenAPI 规范与 SDK
Trellis 2 对外提供完整的 OpenAPI 3.1 描述文件,覆盖整个 /api/v1 接口面。本栏目的 API 参考 就是由它生成的。
获取规范
curl https://trellis2.app/api/openapi.json -o trellis2-openapi.json该端点公开,无需 API Key,因此可以在 CI 里拉取并比对版本差异:
# 公开契约发生非预期变更时让构建失败
curl -s https://trellis2.app/api/openapi.json > openapi.latest.json
diff -q openapi.pinned.json openapi.latest.json || echo "API contract changed"| 格式 | OpenAPI 3.1(JSON) |
| 认证方式 | http / bearer — 发送 Authorization: Bearer tr_... |
| Server | https://trellis2.app/api/v1 |
| 端点 | POST /3d/generations、GET /tasks/{taskId}、GET /models |
导入 API 客户端
Postman — Import → File(或 Import → Link 直接填上面的 URL)。bearer 认证会作为集合变量导入,设一次全局生效。
Insomnia — Create → Import From → URL,粘贴规范地址。
Swagger UI / Redoc — 直接指向 JSON:
<redoc spec-url="https://trellis2.app/api/openapi.json"></redoc>想直接点着调?API 参考 页面内置了基于同一份规范的 playground,密钥只在浏览器里使用。
生成带类型的客户端
任意 OpenAPI 生成器都可用。规范体量不大,生成的代码是可读的,不会糊成一团。
# TypeScript(基于 fetch)
npx openapi-typescript https://trellis2.app/api/openapi.json \
-o src/types/trellis2.d.ts
# Python
openapi-generator-cli generate \
-i https://trellis2.app/api/openapi.json \
-g python \
-o ./trellis2-client// 配合生成的类型,响应可以端到端推导
import type { paths } from './types/trellis2';
type Task =
paths['/tasks/{taskId}']['get']['responses']['200']['content']['application/json'];契约稳定性
规范就是契约——参考页面里的字段名、文档各处示例里的字段名、以及你实际收到的 JSON 字段名,是有意保持一致的。要改字段,先改规范。
有两件事规范里没有描述,因为它们是行为而非结构: