如何提交任务

向任意 Get3W 模型提交一个生成任务。

接口

POST https://api.get3w.com/v1/{provider_id}/{model_id}/{run_type}

路径就是模型 slug。例如 google/nano-banana-pro/text-to-image 对应 /v1/google/nano-banana-pro/text-to-image。

请求头

请求头	是否必填	说明
Authorization	是	Bearer YOUR_API_KEY
Content-Type	是	application/json

查询参数

参数	类型	说明
sync	boolean	等待任务完成并返回完整结果，而不是只返回任务 ID
webhook	string	任务完成后用于 POST 结果的回调地址
prefix	string	输出文件的自定义存储前缀，例如 myfolder1/myfolder2

三个参数都不传就是异步模式：先拿到任务 ID，再轮询获取结果。

请求

cURL

curl -X POST 'https://api.get3w.com/v1/google/nano-banana-pro/text-to-image' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A cat wearing a space suit",
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "output_format": "png",
    "channel": "stable"
  }'

Python

import os
import requests

api_key = os.environ["GET3W_API_KEY"]

response = requests.post(
    "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A cat wearing a space suit",
        "aspect_ratio": "16:9",
        "resolution": "1k",
        "output_format": "png",
        "channel": "stable"
    }
)

task = response.json()
print(f"Task submitted: {task['id']}")

JavaScript

const response = await fetch(
    "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image",
    {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${process.env.GET3W_API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            prompt: "A cat wearing a space suit",
            aspect_ratio: "16:9",
            resolution: "1k",
            output_format: "png",
            channel: "stable"
        })
    }
);

const task = await response.json();
console.log(`Task submitted: ${task.id}`);

请求体

请求体就是模型的输入参数。不同模型接受的参数各不相同 —— 每个模型在 get3w.com/models 上的页面都列出了完整的参数结构。常见的通用参数有：

参数	类型	说明
prompt	string	对输出内容的文字描述
image_url / image_urls	string	图像和视频模型的输入图片
aspect_ratio	string	输出画面比例，例如 16:9
resolution	string	输出分辨率，例如 1k、720p
duration	integer	视频时长（秒）
output_format	string	文件格式，例如 png
seed	integer	用于复现结果的随机种子
channel	string	服务通道，例如 economy、stable、official

响应

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

字段	说明
id	任务 ID，用于轮询结果或匹配收到的 webhook 回调
status	固定为 created
estimated_duration	预计耗时（秒），基于同一模型、同一通道近期的运行情况估算。历史数据不足时为 null

带上 ?sync=true 则会直接返回完整的结果对象 —— 结构参见如何获取结果。同步模式最多等待 10 分钟；如果届时任务尚未完成，响应会返回 status: "processing" 而不是报错，之后由你轮询获取剩余结果。

使用 Webhook

回调地址是查询参数，不是请求体字段：

curl -X POST 'https://api.get3w.com/v1/google/nano-banana-pro/text-to-image?webhook=https://your-server.com/callback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "A cat in space"}'

详见如何使用 Webhook。

错误响应

状态码	说明
400	参数无效，或 slug 中的 provider 无法识别
401	缺少 API Key 或 API Key 无效
402	余额低于任务的预估费用
403	提示词被内容策略拦截，或账户已被封停
404	模型 slug 不存在
500	服务端错误

参数校验、计价和内容审核都在任务入队之前完成，因此这里返回非 200 意味着没有产生任何扣费。

下一步

• 如何获取结果 — 取回生成的输出
• 错误码 — 完整错误参考