API 入门

几分钟就能完成第一次 Get3W API 调用。本文使用 同步模式（Sync mode）：请求会等待任务完成，并在一次请求中直接返回结果。

第一步：获取 API Key

打开 API Keys
填写名称并点击 Generate
复制 Key 并妥善保存

提示

新建的 Key 立即生效。账户的试用额度（约 $0.10）足够跑一次低价的首个任务 —— 之后需要充值，因为每次请求在执行前都会按余额计价。

第二步：生成内容

发送带 ?sync=true 的 POST 请求即可直接拿到结果。下面以 Google 的 Nano Banana Pro 文生图模型为例：

cURLPythonJavaScript

bash

curl -X POST "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image?sync=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A sunset over mountains",
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "output_format": "png",
    "channel": "stable"
  }'

python

import requests

response = requests.post(
    "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image?sync=true",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A sunset over mountains",
        "aspect_ratio": "16:9",
        "resolution": "1k",
        "output_format": "png",
        "channel": "stable"
    }
)

data = response.json()
print(data["status"])    # "completed"
print(data["outputs"])   # ["https://..."]

javascript

const apiKey = "YOUR_API_KEY";

const response = await fetch(
    "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image?sync=true",
    {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${apiKey}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            prompt: "A sunset over mountains",
            aspect_ratio: "16:9",
            resolution: "1k",
            output_format: "png",
            channel: "stable"
        })
    }
);

const data = await response.json();
console.log(data.status);   // "completed"
console.log(data.outputs);  // ["https://..."]

channel 参数用于指定服务通道：

通道	说明
`economy`	性价比高，适合批量任务
`stable`	速度与稳定性兼顾
`official`	直连官方供应商

响应示例：

json

{
  "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"
}

outputs 数组包含生成内容的 URL。需要长期保留的文件请及时下载 —— 详见数据保留政策。

提示

同步模式是最简单的用法：请求会阻塞直到任务完成，无需轮询。对于耗时较长的任务或高吞吐场景，建议使用异步模式或 Webhook 模式。

警告

同步模式最多等待 10 分钟。如果到时任务仍在执行，响应会返回 status: "processing" 而不是报错 —— 请保留 id 并轮询 GET /v1/requests/{id} 获取最终结果。同时要把 HTTP 客户端的超时时间设置得足够长，大多数客户端的默认值远低于此。视频和数字人任务通常会超过 10 分钟，这类任务请使用异步或 Webhook 模式。

调用模式

Get3W 支持三种调用方式：

模式	说明	指南
Sync	等待任务完成并直接返回结果（即本文做法）	加上 `?sync=true` 查询参数
Async	立即返回任务 ID，之后轮询获取结果	异步模式指南
Webhook	立即返回任务 ID，结果推送到你的回调地址	Webhook 模式指南

API 速查

项目	值
Base URL	`https://api.get3w.com/v1`
提交接口	`POST /v1/{provider_id}/{model_id}/{run_type}`
轮询接口	`GET /v1/requests/{request_id}`
鉴权头	`Authorization: Bearer YOUR_API_KEY`
内容类型	`application/json`

任务状态值

状态	说明
`created`	任务已排队
`processing`	任务正在执行
`completed`	任务成功完成
`failed`	任务失败（查看 `error` 字段）

下一步

异步模式 — 提交任务后轮询结果
Webhook 模式 — 通过回调地址接收结果
API 鉴权 — 安全最佳实践

API 入门 ​

第一步：获取 API Key ​

第二步：生成内容 ​

调用模式 ​

API 速查 ​

任务状态值 ​

下一步 ​