OpenImage Open API · v1

把生图和视频接入你的应用。

同样的扣费规则、同样保存到 OSS 的稳定地址 — 现在通过 HTTP 直接调用。创建密钥、给它一个积分上限和过期时间，开箱即用。

Quick Start · 快速开始

登录账号，前往开发者中心创建密钥。
把密钥写到 Authorization: Bearer <your-key> 头中。
调用 POST /openapi/v1/images/generations 生成图片。model 传模型表里的 ID，quality 传该模型支持的档位。
调用 POST /openapi/v1/videos/generations 生成视频，再用 GET /openapi/v1/videos/{taskId} 取结果。
同步模式下，接口会等待生成完成（最多 4 分钟）后返回 OSS 图片地址。

curl -X POST "/openapi/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cat astronaut floating in space, cinematic",
    "model": "jws-nano-banana-2",
    "aspectRatio": "1:1",
    "quality": "2K"
  }'

const res = await fetch("/openapi/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A cat astronaut floating in space",
    model: "jws-nano-banana-2",
    aspectRatio: "1:1",
    quality: "2K"
  })
});
const data = await res.json();
console.log(data.imageUrls);

import requests

resp = requests.post(
    "/openapi/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "prompt": "A cat astronaut floating in space",
        "model": "jws-nano-banana-2",
        "aspectRatio": "1:1",
        "quality": "2K",
    },
)
print(resp.json()["imageUrls"])

Authentication · 鉴权

所有 /openapi/v1/* 接口都需要密钥。支持三种传递方式（按优先级）：

HTTP Header（推荐）：Authorization: Bearer oi-xxxxxxx
专用头：X-API-Key: oi-xxxxxxx
查询参数：?api_key=oi-xxxxxxx（仅供调试，会被日志/CDN 记录，不建议生产使用）

密钥等同于账户的提款凭证，不要提交到公开仓库或前端代码。建议：每个使用场景单独创建密钥，并设置积分上限。

Models & Pricing · 模型与计费

当前生图走贾维斯按次模型，另保留官key gpt-image-2-official。扣费按模型档位计算，参考图和画幅不再加价。任务失败会自动退款。后台关闭的模型不会出现在下表和 List Models 里。

model 传模型 ID，quality 传 1K / 2K / 4K，只接受该模型列出的档位。不传 quality 时按 1K 计费。不传 aspectRatio 时按 16:9。不支持的比例会落到该模型允许的默认比例。

jws-wan-2.7、jws-wan-2.7-pro、jws-qwen-image-3 的尺寸是画幅比例。同步和异步都能用，用 aspectRatio 指定即可。
jws-seedream-5-pro 只接受 1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3。
jws-gpt-image-2.5-flare-adobe、jws-gpt-image-2.5-sunburst-adobe 的尺寸是像素。用 quality + aspectRatio，不要把 16:9 传给 size。
参考图超过该模型上限时，多出的会被丢掉。

模型 ID	名称	档位积分	画幅	参考图上限
nano-banana-2.1	Nano Banana 2.1	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-nano-banana-2	Nano Banana 2	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-nano-banana-pro	Nano Banana Pro	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-grok-imagine-image-2	Grok Imagine Image 2.0	1K / 2K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-seedream-5-flash	Seedream 5.0 Flash	1K / 2K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-seedream-5	Seedream 5.0	1K / 2K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-seedream-5-pro	Seedream 5.0 Pro	1K / 2K	1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3	14
jws-wan-2.7	Wan 2.7 Image	1K / 2K	比例尺寸，可选 1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3	9
jws-wan-2.7-pro	Wan 2.7 Image Pro	1K / 2K / 4K	比例尺寸，可选 1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3	9
jws-qwen-image-3	Qwen Image 3.0	1K / 2K	比例尺寸，可选 1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3	3
jws-midjourney-v8.2	Midjourney v8.2	1K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-gpt-image-2-free	GPT Image 2 Free	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-gpt-image-2-adobe	GPT Image 2 Adobe	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-gpt-image-2.5-flare	GPT Image 2.5 Flare	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-gpt-image-2.5-sunburst	GPT Image 2.5 Sunburst	1K / 2K / 4K	1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9	14
jws-gpt-image-2.5-flare-adobe	GPT Image 2.5 Flare Adobe	1K / 2K / 4K	像素尺寸，可选 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21	14
jws-gpt-image-2.5-sunburst-adobe	GPT Image 2.5 Sunburst Adobe	1K / 2K / 4K	像素尺寸，可选 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21	14

gpt-image-2-official 仍可用 upstreamModel 选择 gpt-image-2（默认）/ gpt-image-2.5-flare / gpt-image-2.5-sunburst。贾维斯模型忽略这个字段，模型 ID 已经对应实际上游。

List Models · 列出模型

GET/openapi/v1/models

返回当前可用的模型清单和单价（以积分计）。无副作用，不扣费，可用于在你的 UI 里做模型下拉/选择列表。

响应字段

字段	类型	说明
success	boolean	请求是否成功。
models	object[]	模型数组，按推荐顺序排列。
models[].id	string	模型 ID，传给生图接口的 `model` 字段。
models[].label	string	面向用户的展示名（含中文标签）。
models[].baseCost	number	该模型最低档积分 / 张。贾维斯模型的 2K / 4K 以模型表为准。参考图与画幅不再额外计费。
models[].default	boolean	是否为默认模型。不传 `model` 时使用清单里的第一项，当前通常是官key。

响应示例

{
  "success": true,
  "models": [
    { "id": "gpt-image-2-official", "label": "GPT Image · 官key", "baseCost": 33, "default": false },
    { "id": "jws-gpt-image-2-free", "label": "GPT Image 2 Free", "baseCost": 8, "default": false },
    { "id": "jws-nano-banana-2", "label": "Nano Banana 2", "baseCost": 36, "default": false }
  ]
}

Account · 查询额度

GET/openapi/v1/account

查询当前密钥的额度使用情况，以及密钥所属账户的整体积分余额。无副作用，不扣费，适合调用前先看看够不够。

响应字段

字段	类型	说明
success	boolean	请求是否成功。
apiKey.prefix	string	密钥可见前缀（如 `oi-aB3kZ9...`），完整密钥永不回显。
apiKey.creditLimit	number / null	密钥配置的积分上限；`null` 表示不设上限（仅受账户余额限制）。
apiKey.creditUsed	number	该密钥累计已消耗积分（含失败已退款的部分会回退）。
apiKey.creditRemaining	number	密钥剩余可用额度 = `creditLimit - creditUsed`，不设上限时不返回此字段。
credit.balance	number	账户总积分余额（含赠送积分）。
credit.giftBalance	number	其中赠送积分余额，消耗时优先扣此项。
credit.totalConsumed	number	账户累计已消耗积分（历史，不含退款回退后的差额）。

响应示例

{
  "success": true,
  "apiKey": {
    "prefix": "oi-aB3kZ9...",
    "creditLimit": 5000,
    "creditUsed": 1280,
    "creditRemaining": 3720
  },
  "credit": {
    "balance": 8420,
    "giftBalance": 230,
    "totalConsumed": 1580
  }
}

Generate Image · 生成图片

POST/openapi/v1/images/generations

提交一次生图请求。默认同步模式会阻塞直到生成完成（含 3 次自动重试），并直接返回保存到 OSS 的稳定图片 URL。如不希望阻塞，可设 async: true 立刻拿到 taskId，再轮询 /images/{taskId}。

接口支持两种 Content-Type：application/json（仅 URL 参考图）与 multipart/form-data（可直接上传本地图片作为参考图）。两种形式的字段名一致，仅本地文件需要走 multipart。

请求字段

字段	类型	说明
prompt必填	string	画面描述（支持中英文），最多 2000 字符。
model选填	string	模型 ID，见模型与计费。不传时使用 List Models 的第一项。要指定贾维斯模型必须显式传 `jws-*` 或 `nano-banana-2.1`。
aspectRatio选填	string	画幅比例。贾维斯常用 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` / `21:9`。不传或传 `auto` 时按 `16:9`。`9:21` 会落到 `9:16`。各模型允许的比例见模型表，超出范围会落到该模型默认比例。
quality选填	string	清晰度档位，`1K` / `2K` / `4K`，大小写均可。只对模型表里列出的档位生效，不传按 `1K` 计费。推荐用 `quality` + `aspectRatio`。
upstreamModel选填	string	仅 `gpt-image-2-official` 生效：`gpt-image-2`（默认）/ `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`。贾维斯模型忽略。
size选填	string	官key可传 27 个固定像素尺寸之一，优先级高于 `quality` + `aspectRatio`。贾维斯模型不要传比例字符串。两款 Adobe 像素模型用 `quality` + `aspectRatio` 即可。
negativePrompt选填	string	反向提示词，最多 500 字符。贾维斯生图不使用该字段。
referenceUrls选填	string[]	参考图 URL，需公开可访问。上限见模型表，多出的会被丢掉。可与 `referenceFiles` 合并。
referenceFiles选填	file[]	仅 multipart。本地参考图文件，重复传字段名 `referenceFiles` 即可上传多张；服务端会上传到 OSS 并自动拼接到 `referenceUrls`。单张 ≤ 20MB，`image/*` 任意类型。参考图不再额外扣费。
async选填	boolean	是否异步：`true` 立即返回任务 ID 不等待，需自行轮询；`false`（默认）阻塞至完成。
waitMs选填	number	同步模式下最大等待毫秒数，默认 180000（3 分钟），最大 360000（6 分钟）。官key 4K 生成耗时较长，建议显式抬到 360000。超时不算失败，可继续轮询拿结果。

请求示例 · multipart 直传本地参考图

curl -X POST "/openapi/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=把这张人像改成赛博朋克风格" \
  -F "model=jws-nano-banana-2" \
  -F "quality=2K" \
  -F "aspectRatio=1:1" \
  -F "referenceFiles=@./portrait.png" \
  -F "referenceFiles=@./style.jpg"

请求示例 · 贾维斯 2K

curl -X POST "/openapi/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic landscape, golden hour, ultra detailed",
    "model": "jws-nano-banana-2",
    "aspectRatio": "16:9",
    "quality": "2K"
  }'

响应字段

同步与异步返回的字段结构一致，区别只是返回时刻 status 是否已经是终态。详细字段说明见 Get Task 章节，常用字段速览：

字段	类型	说明
success	boolean	请求是否被成功受理。注意：`true` 仅代表受理成功，是否生图成功要看 `status`。
taskId	string	本次任务的唯一 ID，可用于轮询和补单。
status	string	`queued`（排队）/ `running`（生成中）/ `succeeded`（成功）/ `failed`（失败）。
imageUrl	string / null	主图 URL（即 `imageUrls[0]`），未完成或失败时为 `null`。
imageUrls	string[]	所有结果图的 OSS 稳定地址。同步成功时至少 1 张。
model	string	实际使用的模型 ID。
size	string / null	按请求档位和画幅记下的像素尺寸。贾维斯成品像素以上游实际输出为准。
prompt / aspectRatio / negativePrompt / referenceUrls	—	原样回显请求参数，方便对账与日志。
progressText	string	面向人的进度文案，如 "正在请求绘图模型" / "第 2 次尝试…"。
errorMessage	string / null	失败原因（如 "请求过于频繁，请稍后再试"），仅 `failed` 时有值。
creditsCharged	number	本次实际扣除的积分。
creditsRefunded	boolean	是否已自动退款。三次重试都失败 → `true`；命中内容安全策略被拒（如涉黄、暴力等）属于有效调用，`false`，不退款。
createdAt / updatedAt	datetime	任务创建时间 / 最近一次状态更新时间（ISO-8601）。

响应示例 · 同步成功

{
  "success": true,
  "taskId": "f8d3e91a06d34c5fb4d2c1e9a7b08c2d",
  "status": "succeeded",
  "model": "jws-nano-banana-2",
  "prompt": "A cat astronaut floating in space, cinematic",
  "aspectRatio": "1:1",
  "imageUrl": "https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png",
  "imageUrls": ["https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png"],
  "creditsCharged": 10,
  "creditsRefunded": false,
  "progressText": "生成完成",
  "createdAt": "2026-05-20T10:23:18.000+08:00",
  "updatedAt": "2026-05-20T10:23:42.000+08:00"
}

响应示例 · 异步受理

{
  "success": true,
  "taskId": "f8d3e91a...",
  "status": "queued",
  "creditsCharged": 10,
  "imageUrls": [],
  "progressText": "已加入生成队列"
}

✓

三次自动重试：上游接口超时、限流或返回空，服务自动重试，全部失败再退款。你不用自己实现重试逻辑。
例外：提示词或参考图被上游内容安全策略拒绝时（涉黄、暴力等），不会重试也不退款，errorMessage 会明确提示「内容违规」。请在客户端做基础的提示词审查。

Get Image Task · 查询图片任务

GET/openapi/v1/images/{taskId}

查询任务状态、进度和最终图片地址。同步模式下返回的 taskId 也可以用来重查、补单。任务在 Redis 保留 14 天，过期返回 404。

路径参数

参数	位置	说明
taskId必填	path	提交生图时返回的任务 ID（32 位 hex）。仅可查看属于当前密钥提交的任务。

请求示例

curl "/openapi/v1/images/f8d3e91a06d34c5fb4d2c1e9a7b08c2d" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应字段

字段	类型	说明
success	boolean	是否成功取到任务（任务不存在 → 404 + `success: false`）。
taskId	string	任务 ID。
status	string	`queued`（排队中）/ `running`（生成中）/ `succeeded`（成功）/ `failed`（失败）。
imageUrl	string	主图 URL（即 `imageUrls[0]`），仅 `succeeded` 时有值；失败或进行中为 `null`。
imageUrls	string[]	所有结果图的 OSS 稳定地址数组。
model	string	本次使用的模型 ID。
size	string / null	请求档位和画幅对应的像素尺寸。贾维斯成品以上游实际输出为准。
prompt	string	提交时的画面描述。
aspectRatio	string	画幅比例。
negativePrompt	string	反向提示词（可空）。
referenceUrls	string[]	参考图 URL 列表。
progressText	string	面向人的进度文案，如 "正在请求绘图模型" / "第 2 次尝试 · 上次未成功，正在重试…"。
errorMessage	string	失败时的错误描述（如限流、上游超时等），其他状态为 `null`。
createdAt	datetime	任务创建时间（ISO-8601）。
updatedAt	datetime	最近一次状态更新时间。
creditsCharged	number	本次扣除的积分。
creditsRefunded	boolean	是否已自动退款（三次重试都失败时为 `true`；命中内容安全策略被拒不退款，`false`）。

响应示例 · 成功

{
  "success": true,
  "taskId": "f8d3e91a06d34c5fb4d2c1e9a7b08c2d",
  "status": "succeeded",
  "model": "jws-nano-banana-2",
  "prompt": "A cat astronaut floating in space",
  "aspectRatio": "1:1",
  "negativePrompt": null,
  "referenceUrls": [],
  "imageUrl": "https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png",
  "imageUrls": [
    "https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png"
  ],
  "progressText": "生成完成",
  "errorMessage": null,
  "createdAt": "2026-05-20T10:23:18.000+08:00",
  "updatedAt": "2026-05-20T10:23:42.000+08:00",
  "creditsCharged": 10,
  "creditsRefunded": false
}

响应示例 · 进行中

{
  "success": true,
  "taskId": "f8d3e91a...",
  "status": "running",
  "progressText": "正在请求绘图模型",
  "imageUrl": null,
  "imageUrls": [],
  "errorMessage": null,
  "creditsCharged": 10,
  "creditsRefunded": false
}

响应示例 · 失败已退款

{
  "success": true,
  "taskId": "f8d3e91a...",
  "status": "failed",
  "progressText": "生成失败",
  "errorMessage": "模型多次未返回图像，请尝试调整提示词",
  "imageUrl": null,
  "imageUrls": [],
  "creditsCharged": 10,
  "creditsRefunded": true
}

异步轮询建议：建议每 5 秒查一次，直到 status 变为 succeeded 或 failed。或者直接用同步模式（async 不传），服务端帮你阻塞至完成，单次请求即可拿到最终结果。

Error Codes · 错误码

所有错误响应的结构一致：HTTP 非 2xx + JSON body 包含 success: false、code（机器可读的错误标识）、message（面向人的错误描述）。部分错误会附加上下文字段（如 required、balance）方便你做提示。

统一错误响应结构

{
  "success": false,
  "code": "insufficient_credits",    // 机器可读的错误码
  "message": "积分不足：当前 5，需要 10",  // 用户友好提示
  "required": 10,                        // 部分错误会附加额外字段
  "balance": 5
}

错误码表

code	HTTP	含义
missing_api_key	401	请求未携带密钥（Authorization / X-API-Key / api_key 全为空）。
invalid_api_key	401	密钥不存在、已删除或已过期。检查是否复制完整。
user_disabled	401	密钥所属用户被管理员禁用。
unauthorized	401	未识别到密钥上下文（一般不会出现，除非鉴权拦截被绕过）。
insufficient_credits	402	账户积分不足。响应附带 `required`（需要积分）和 `balance`（当前余额）。
api_key_limit_exceeded	402	密钥配置的积分上限已用尽。响应附带 `required` / `creditLimit` / `creditUsed`。
invalid_request	400	参数非法（如 `prompt` 为空、上传文件超限）。`message` 中说明原因。
not_found	404	任务不存在或不属于当前密钥。
generation_failed	502	三次重试后仍失败，已自动退款。响应附带 `task` 字段含完整任务详情。
endpoint_removed	410	该接口已下线（如旧的 `/images/upload`），`message` 中给出替代方案。
server_error	500	未分类的服务端错误，详见 `message`。

List Video Models · 列出视频模型

GET/openapi/v1/video-models

返回当前已启用的视频模型。不扣费。关闭的模型不会出现。这个接口和生图的 /models 分开，避免旧客户端把视频模型当成生图模型。

模型 ID	名称	计费	示例积分	分辨率	时长
grok-imagine-video-1	Grok 视频	按秒	129	480p / 720p	6 秒起，可选 6, 8, 10, 15
grok-imagine-video-1.5	Grok 视频 1.5	按秒	770	480p / 720p	6 秒起，可选 4, 6, 8, 10, 12, 15
grok-imagine-video-1.5-fast	Grok 视频 Fast	按次	89	720p	6 秒起，可选 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
seedance-2.0-fast-face	Seedance Fast Face	按秒	391	480p / 720p	6 秒起，可选 4, 5, 6, 8, 10, 12, 15
seedance-2.0-mini-eco	Seedance Mini Eco	按秒	44	720p / 1080p	6 秒起，可选 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
seedance-2.0-mini	Seedance Mini	按秒	192	480p / 720p	6 秒起，可选 4, 5, 6, 8, 10, 12, 15
seedance-2.0-face-builtin	Seedance 2.0 内置过脸	按次	167	720p	6 秒起，可选 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
seedance-2.0-face-native	Seedance 2.0 原生过脸	按次	373	720p	6 秒起，可选 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
seedance-2.0-face-native-sec	Seedance 2.0 原生过脸（按秒）	按秒	183	720p	6 秒起，可选 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
seedance-2.5-eco	Seedance 2.5 Eco	按秒	418	720p / 1080p	6 秒起，可选 4, 6, 8, 10, 12, 15, 20, 30
seedance-2.5-face-builtin	Seedance 2.5 内置过脸	按次	167	720p	6 秒起，可选 4, 6, 8, 10, 12, 15, 20, 30
seedance-2.5-face-native	Seedance 2.5 原生过脸	按次	491	720p	30 秒起，可选 30
seedance-2.5-face-native-sec	Seedance 2.5 原生过脸（按秒）	按秒	1471	720p	30 秒起，可选 30
seedance-2.5-pro-face-native-sec	Seedance 2.5 Pro（按秒）	按秒	353	720p	6 秒起，可选 4, 6, 8, 10, 12, 15, 20, 30
minimax-h3	MiniMax H3	按秒	83	1080p / 2K / 4K	6 秒起，可选 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
wan3.0	Wan 3.0	按秒	189	480p / 720p / 1080p	6 秒起，可选 4, 6, 8, 10, 12, 15, 20, 30

响应里每个模型还包含 aspectRatios、maxInputImages、defaultResolution。按秒计费的模型带 creditsPerSecond，键是分辨率，值是每秒积分。

Generate Video · 生成视频

POST/openapi/v1/videos/generations

提交一次视频生成。接口立即返回 taskId，状态为 queued。服务每 1 分钟向上游同步一次，最长等待 30 小时。完成后 videoUrl 是 OSS 地址。失败自动退款。

支持 application/json 和 multipart/form-data。本地参考图走 multipart 的 referenceFiles。

请求字段

字段	类型	说明
prompt必填	string	画面描述，最多 2000 字符。
model必填	string	视频模型 ID，见 List Video Models。必须传，不会回落到生图默认模型。
resolution选填	string	分辨率，如 `480p` / `720p` / `1080p`。不传用该模型默认值。不在可选列表里时，会落到最接近的一档。
duration选填	number	时长秒数。不传用该模型默认时长。不在可选列表里时，会落到最接近的一档。按秒计费时，扣费 = 每秒积分 × 实际时长。
aspectRatio选填	string	画幅。不传或不支持时用该模型默认画幅。
referenceUrls选填	string[]	参考图 URL，需公开可访问。超过该模型上限的部分会被丢掉。
referenceFiles选填	file[]	仅 multipart。本地参考图，单张不超过 20MB。

请求示例

curl -X POST "/openapi/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "海边日落，镜头缓慢推进",
    "model": "grok-imagine-video-1",
    "resolution": "720p",
    "duration": 6,
    "aspectRatio": "16:9"
  }'

响应示例

{
  "success": true,
  "taskId": "0e86c7a11b1445a388fb9d1343d26138",
  "status": "queued",
  "model": "grok-imagine-video-1",
  "resolution": "720p",
  "duration": 6,
  "videoUrl": null,
  "creditsCharged": 40,
  "progressText": "已加入生成队列"
}

Get Video Task · 查询视频任务

GET/openapi/v1/videos/{taskId}

只能查询当前密钥提交的视频任务。建议每分钟查一次。succeeded 时读取 videoUrl。

curl "/openapi/v1/videos/0e86c7a11b1445a388fb9d1343d26138" \
  -H "Authorization: Bearer YOUR_API_KEY"

字段	类型	说明
status	string	`queued` / `running` / `succeeded` / `failed`。
videoUrl	string / null	成功后的 OSS 视频地址。
resolution / duration / aspectRatio	—	实际采用的规格。
creditsCharged / creditsRefunded	—	扣费与是否已退款。失败后退款，密钥已用额度同步回退。
errorMessage	string / null	失败原因。等待超过 30 小时也会失败并退款。

Playground · 在线调试

填好密钥和提示词，直接在页面里发起一次真实调用 — 同样会扣积分。

Try it now · 发起一次真实请求

密钥仅在浏览器本地存储，不会上传服务器。同步模式最长等 4 分钟。

API Key 来自开发者中心。本浏览器记住，刷新仍可用。

Prompt

Model

Quality

Aspect Ratio

参考图 URL（每行一条，可空）

尚未发起请求

把 生图和视频 接入你的应用。

Quick Start · 快速开始

Authentication · 鉴权

Models & Pricing · 模型与计费

List Models · 列出模型

响应字段

响应示例

Account · 查询额度

响应字段

响应示例

Generate Image · 生成图片

请求字段

请求示例 · multipart 直传本地参考图

请求示例 · 贾维斯 2K

响应字段

响应示例 · 同步成功

响应示例 · 异步受理

Get Image Task · 查询图片任务

路径参数

请求示例

响应字段

响应示例 · 成功

响应示例 · 进行中

响应示例 · 失败已退款

Error Codes · 错误码

统一错误响应结构

错误码表

List Video Models · 列出视频模型

Generate Video · 生成视频

请求字段

请求示例

响应示例

Get Video Task · 查询视频任务

Playground · 在线调试

Try it now · 发起一次真实请求

把生图和视频接入你的应用。