快速开始

快速开始

API

MCP 服务
API 概览认证可用模型

指南

快速开始任务与轮询错误处理

计费与限制

定价与积分速率限制

集成

OpenAPI 规范与 SDK
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_...
Serverhttps://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 字段名,是有意保持一致的。要改字段,先改规范。

有两件事规范里没有描述,因为它们是行为而非结构:

  • 同步 55 秒上限与 running 降级 —— 见 任务与轮询
  • 60 次/分钟的额度与相关响应头 —— 见 速率限制

速率限制

请求额度、429 响应,以及正确的退避方式

创建 3D 生成任务 POST

下一页

目录

OpenAPI 规范与 SDK
获取规范
导入 API 客户端
生成带类型的客户端
契约稳定性