Get3W 工作原理

Get3W 是一层架在众多上游模型供应商之前的统一 API。你带上模型 slug 调用同一个接口；Get3W 会挑选供应商、执行任务、保存产物，并返回 URL。

Your app → Get3W API → task queue → worker → model provider → object storage → outputs

模型 Slug

每个模型都用一个三段式 slug 来定位：

{provider_id}/{model_id}/{run_type}

例如 google/nano-banana-pro/text-to-image。slug 同时也是提交路径：

POST /v1/google/nano-banana-pro/text-to-image

完整的供应商和运行类型列表见什么是模型。

运行类型

run_type 这一段声明了你要运行的任务种类：

分类	运行类型
图像	text-to-image、image-to-image、text-to-panorama、image-to-panorama
视频	text-to-video、first-to-video、first-last-to-video、reference-to-video、video-to-video、digital-human
音频	text-to-speech、text-to-music、speech-to-text
3D	text-to-3d、image-to-3d
Chat	chat（兼容 OpenAI，详见下文）

通道

很多模型支持在请求体中传入 channel 来选择服务档位。通用取值是 economy、stable 和 official；部分模型系列使用自己的取值，例如 turbo、balanced、quality、standard、pro、fast 或 human。

通道会影响价格、队列路由以及哪些上游供应商可用。不传时，Get3W 会自动填入该模型的默认值。

请求流程

1. 提交

POST /v1/{provider_id}/{model_id}/{run_type}

可选查询参数：

参数	作用
sync	等待任务完成，并在同一次响应中返回完整结果
webhook	回调地址，任务完成后用于接收结果
prefix	输出文件的自定义存储前缀，例如 myfolder1/myfolder2

在任何任务入队之前，API 服务端会：

1. 校验 Authorization: Bearer API Key
2. 校验供应商并解析出实际生效的通道
3. 用内容黑名单筛查提示词（命中则返回 403）
4. 为请求计价并校验余额（不足则返回 402）

2. 入队与执行

通过校验的任务会被推入 Celery 队列（30 分钟过期），并立即返回给你：

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "created",
  "estimated_duration": 52
}

estimated_duration 单位为秒，来自该模型该通道近期完成任务的耗时中位数。

随后工作节点取走任务，调用上游供应商，下载结果，写入对象存储，并从你的余额中结算费用。

3. 获取结果

轮询这个请求，直到它进入终态：

GET /v1/requests/{request_id}

任务仍在执行时，响应是 {"id": ..., "status": "processing"}，并带上 Retry-After: 3 响应头。进入终态后，你会拿到完整结果：

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "completed",
  "code": 0,
  "outputs": ["https://storage.example.com/output.png"],
  "timings": {
    "queue_wait": 427,
    "celery_init": 2054,
    "api_call": 23068,
    "save": 1902,
    "run_overhead": 679,
    "total": 28131
  },
  "error": null,
  "created_at": "2026-03-28T07:50:42"
}

所有耗时单位均为毫秒。api_call 是在上游供应商处消耗的时间；save 是持久化输出所花的时间。

任务状态

状态	含义
created	已受理并入队
processing	工作节点正在执行任务
completed	已完成；outputs 中是结果 URL
failed	以错误结束；查看 code 和 error

completed 和 failed 是终态 —— 看到它们就停止轮询。code 的取值含义见错误码。

供应商路由与可靠性

同一个模型 slug 可以由多个上游平台承载。Get3W 不会固定绑死某一个，而是自动在它们之间做故障切换：

• 配置好的顺序 —— 每个模型和通道都有一份由 Get3W 维护的、有先后次序的可用平台列表。
• 多轮重试 —— 某次尝试失败后会顺着这个顺序落到下一个平台。整份列表最多重试 2 轮，轮次之间有退避等待，起始为 10 秒。
• 用户侧错误快速失败 —— 由你的输入导致的失败，例如内容审核不通过或参数非法，会立即中止，而不会换到其他平台重试。重试这类错误只会浪费时间，结果不会改变。

每个平台的成功率和延迟会被持续记录，并影响 Get3W 对列表的排序，但排序来自配置，而不是每次请求实时重算。

由于重试发生在单个任务内部，你的请求 ID 始终保持不变。只有当所有可用平台都尝试过，或者失败本身不可重试时，你才会看到 failed。

地理路由

Get3W 运行着两个集群，分别位于广州和硅谷。任务会被投递到离该模型主要上游平台最近的集群，因此部署在中国的供应商跑在 CN 工作节点上，海外供应商跑在 US 工作节点上。当 CN 工作节点上的任务需要访问海外供应商时，这次调用会转交给 US 集群，而不是直接跨境。

这个过程对你完全透明 —— 两种情况下 API 域名和请求格式都完全一致。

调用模式

模式	用法	指南
Sync	提交时加上 ?sync=true	API 入门
Async	提交后轮询 /v1/requests	异步模式
Webhook	提交时加上 ?webhook=<your-url>	Webhook 模式

如果你的接口没有返回 2xx，Webhook 推送会按指数退避最多重试 3 次。结果同时也可以通过轮询获取，所以漏掉一次 Webhook 绝不等于丢失结果。

Chat 模型

Chat 模型不走提交接口，而是使用兼容 OpenAI 的接口：

POST /v1/chat/completions

把任意 OpenAI 客户端指向 https://api.get3w.com/v1，填入你的 Get3W API Key，并在 model 字段传入 chat 模型的 slug。Chat 请求是同步的，并支持流式输出。

内容生命周期

1. Created —— 请求已校验、已计价、已入队
2. Processing —— 工作节点向上游供应商执行任务
3. Completed —— 输出写入对象存储并以 URL 形式暴露
4. Expiring —— 输出文件保留当月和上一个自然月；任务记录保留 7 天
5. Deleted —— 过期的文件和记录由清理任务移除

由于保留期按整个自然月计算，文件的实际存活时长取决于它在月内的创建时间 —— 请把上一个月的月初边界当作截止点，而不是某个固定天数。

需要长期保留的内容请及时下载。如果你在 API Key 上配置了自己的云存储，输出会写入你的存储，保留策略由你自己掌控。

余额与账户等级

随时查询余额和等级：

GET /v1/balance

{
  "balance": 42.5,
  "currency": "USD",
  "account_level": "Silver"
}

等级依据累计充值金额确定，且永不下降。详见什么是账户等级。

下一步

• 什么是模型
• 什么是任务
• API 入门