One envelope
Endpoint, headers, status machine and error table are shared. What changes between models is the set of fields inside input.
Submit a task, poll for it, download the result. The endpoint and the envelope never change — switching models means changing parameters, not code paths.
The flow is identical whether you generate a still image or a fifteen‑second clip, and regardless of which model you pick.
POST the model id and an input object to /v1/task/submit. The call returns in about a second with a task id while generation continues in the background.
GET /v1/task/{id} with a 2–3 s back‑off until status reaches completed or failed. Or hand us a callback_url and skip the loop entirely.
Read outputs[] for direct URLs — JPEG or PNG for images, MP4 for video. Links need no auth and stay live for 24 hours after completion.
Synchronous endpoints hold a connection open until the model finishes. That works for a quick script and breaks everywhere else. WideRouter’s task API was designed around what production actually needs.
| Dimension | Synchronous call | WideRouter async task |
|---|---|---|
| Deterministic outcome | The request either returns or it doesn’t. A timeout leaves you guessing whether the model ran. | Every task has an execution time limit. It ends completed or failed, never in limbo. |
| Failed or timed out | Billed by the provider whether or not you received the bytes. | Not billed. A failed task, including one that hit the time limit, costs nothing. |
| Input and output | Base64 in the request body and base64 in the response. Your bandwidth on both ends. | URLs both ways. Reference images are fetched server-side; results come back as CDN links valid for 24 hours. |
| Nothing gets lost | If the response is interrupted, the image is gone. | The task finishes and is stored on the server. Read it back any time by task id; repeated reads return identical JSON. |
| Network hiccups | A 12–50 s open connection through proxies, serverless functions or mobile networks. Any drop kills the request. | Submit returns in about 0.9 s. Disconnect afterwards and the task still completes. |
| Throughput | A 4K image is megabytes of base64 per response. Video is not even offered. | Up to 4 outputs per task, 4K images and 15 s 1080p video, all delivered as links. |
| Webhooks | None. You poll or you block. | callback_url: the full task object is POSTed on completion, with automatic retries on 5xx. |
| Image and video | Images only, with per-endpoint quirks. | One request shape for both. |
Synchronous image endpoints (/v1/images/generations, generateContent) stay available for scripts that want bytes back immediately. Video is async only. Async task API
Most gateways make you learn a new endpoint, request body and response shape per provider. WideRouter keeps all three fixed.
Endpoint, headers, status machine and error table are shared. What changes between models is the set of fields inside input.
A 4K still from Nano Banana Pro and a 1080p clip from Grok Imagine come back through the same task object.
Model ids match the provider’s names exactly. No invented aliases, no -preview suffixes to guess at.
Pass callback_url to be notified on completion. Try every model from the docs playground with a real key before writing code.
Two families today. Each card links to a comparison matrix with parameters, resolution tiers and measured latency.
Up to 14 reference images per request, n from 1 to 4, resolution tiers from 512 px to 4K.
gemini-3-pro-image gemini-3.1-flash-image gemini-3.1-flash-lite-image gemini-2.5-flash-image Images at 1k or 2k with up to 3 references. Video from 1 to 15 seconds, 480p to 1080p, with edit and extend modes.
grok-imagine-image-2.0 grok-imagine-image-quality grok-imagine-image grok-imagine-video-1.5 grok-imagine-video A hand-picked catalog of the most used and newest text and multimodal models. Each provider’s native API is passed through transparently, with OpenAI-compatible endpoints as the fallback. Nothing left out.
WideRouter’s list price matches the provider’s published price exactly. Your charge is list price × group multiplier — 0.8 for the Grok‑Official group.
list price × group multiplier = charge Reference images and additional outputs are billed per item. Full tables, including Nano Banana, are in the docs. See pricing in the docs
Export your key, submit, poll. The same two calls work for every model on the platform.
# 1. submit curl https://api.widerouter.com/v1/task/submit \ -H "Authorization: Bearer $WIDEROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.1-flash-image", "input": { "prompt": "a lighthouse at dusk" } }' # 2. poll until status is completed or failed curl https://api.widerouter.com/v1/task/task_koYlX7Gm6lEn5jfPS54TcDZcN7OvZA8M \ -H "Authorization: Bearer $WIDEROUTER_API_KEY"
import os, time, requests BASE = "https://api.widerouter.com" HEADERS = {"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"} # 1. submit task = requests.post(f"{BASE}/v1/task/submit", headers=HEADERS, timeout=30, json={ "model": "gemini-3.1-flash-image", "input": {"prompt": "a lighthouse at dusk"}, }).json() # 2. poll with a 3 s back-off while task["status"] not in ("completed", "failed"): time.sleep(3) task = requests.get(f"{BASE}/v1/task/{task['id']}", headers=HEADERS, timeout=30).json() print(task["outputs"])
Create a key in the console, then follow the five‑minute quickstart.
无论生成一张静态图还是一段十五秒的视频，无论选哪个模型，流程都是同一个。
把模型 ID 和 input 对象 POST 到 /v1/task/submit。约一秒返回任务 ID，生成在后台继续进行。
以 2–3 秒退避 GET /v1/task/{id}，直到 status 变为 completed 或 failed。也可以传 callback_url，完全省掉轮询。
从 outputs[] 读取直链：图片为 JPEG 或 PNG，视频为 MP4。链接无需鉴权，完成后 24 小时内有效。
同步接口要一直挂着连接等模型跑完，写个脚本没问题，放到生产环境处处是坑。WideRouter 的任务 API 围绕生产环境真正需要的东西来设计。
| 维度 | 同步调用 | WideRouter 异步任务 |
|---|---|---|
| 结果确定 | 请求要么回来要么不回来，超时了你不知道模型到底跑没跑。 | 每个任务都有最大执行时限，终态只有 completed 或 failed，不会悬着。 |
| 失败与超时 | 无论你有没有拿到字节，上游都已计费。 | 不计费。 failed 的任务，包括超时的，一分钱不扣。 |
| 输入与输出 | 请求体 base64 进、响应体 base64 出，两头都吃你的带宽。 | 两头都是 URL。 参考图由服务端拉取，结果是 CDN 直链，24 小时有效。 |
| 不丢图 | 响应中断，图就没了。 | 任务在服务端跑完并保存，凭 task id 随时回查，重复读取结果完全一致。 |
| 网络波动 | 12–50 秒的长连接穿过代理、serverless、移动网络，哪一环断了请求就没了。 | 提交约 0.9 秒返回，之后断开连接任务照常完成。 |
| 吞吐 | 一张 4K 图在响应里是几 MB 的 base64，视频根本给不了。 | 一个任务最多 4 个产物，4K 图片和 15 秒 1080p 视频都以链接交付。 |
| 回调 | 没有，只能阻塞等。 | callback_url：完成时把完整任务对象 POST 给你，5xx 自动重试。 |
| 图片与视频 | 只有图片，且各端点各有脾气。 | 图片与视频同一种请求形状。 |
同步图片接口（/v1/images/generations、generateContent）仍然保留，适合要立刻拿到字节的脚本。视频只有异步。 异步任务 API
多数中转平台要求你为每家供应商学一套端点、一套请求体、一套响应结构。WideRouter 把这三样都固定下来。
端点、请求头、状态机和错误表全部共用。模型之间变的只是 input 里那组字段。
Nano Banana Pro 的 4K 静态图和 Grok Imagine 的 1080p 视频，通过同一个任务对象返回。
模型 ID 与供应商官方名称完全一致。不自造别名，也不用猜 -preview 后缀。
传 callback_url 即可在完成时收到通知。写代码前先在文档的 Playground 里用真实 Key 试每一个模型。
目前收录两个系列。每张卡片链接到对照矩阵，包含参数、分辨率档位和实测时延。
每次最多 14 张参考图，n 取 1 到 4，分辨率档位从 512 px 到 4K。
gemini-3-pro-image gemini-3.1-flash-image gemini-3.1-flash-lite-image gemini-2.5-flash-image 图片 1k 或 2k，最多 3 张参考图。视频 1 到 15 秒、480p 到 1080p，支持编辑与续写模式。
grok-imagine-image-2.0 grok-imagine-image-quality grok-imagine-image grok-imagine-video-1.5 grok-imagine-video 人工精选常用与最新的文本、多模态模型。以各厂商原生接口透明转发为主，OpenAI 兼容模式为辅。
WideRouter 的标价与供应商公布价格完全一致。实际扣费 = 标价 × 分组倍率，Grok-Official 分组的倍率为 0.8。
标价 × 分组倍率 = 实际扣费 参考图与额外输出按件计费。完整价目表（含 Nano Banana）见文档。 在文档中查看计价
导出 Key、提交、轮询。平台上每一个模型都是这同样的两次调用。
# 1. submit curl https://api.widerouter.com/v1/task/submit \ -H "Authorization: Bearer $WIDEROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.1-flash-image", "input": { "prompt": "a lighthouse at dusk" } }' # 2. poll until status is completed or failed curl https://api.widerouter.com/v1/task/task_koYlX7Gm6lEn5jfPS54TcDZcN7OvZA8M \ -H "Authorization: Bearer $WIDEROUTER_API_KEY"
import os, time, requests BASE = "https://api.widerouter.com" HEADERS = {"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"} # 1. submit task = requests.post(f"{BASE}/v1/task/submit", headers=HEADERS, timeout=30, json={ "model": "gemini-3.1-flash-image", "input": {"prompt": "a lighthouse at dusk"}, }).json() # 2. poll with a 3 s back-off while task["status"] not in ("completed", "failed"): time.sleep(3) task = requests.get(f"{BASE}/v1/task/{task['id']}", headers=HEADERS, timeout=30).json() print(task["outputs"])