KovAPIKovAPI
grok-imagine-image

Grok Imagine Image · API

POST https://kovapi.com/v1/images/generations

Grok Imagine Image(标准档)生图接口,xAI 的生图模型,出图快。异步任务:提交后立刻返回任务号(HTTP 202),再查询结果或等 Webhook 推送。只有 1K 和 2K 两档;按张计费,失败不收费。改图时每张参考图另收 $0.001。

在 Playground 试用 →

快速开始

三步跑通:提交任务 → 查询结果 → 拿到图片链接。把 YOUR_API_KEY 换成你的 Key,下面的命令可以直接运行。

第 1 步 · 提交任务(立刻返回任务号,HTTP 202)

curl
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image", "prompt": "清晨雪林里的一只红狐狸,写实摄影风格", "size": "16:9", "resolution": "2K"}'

返回(HTTP 202)

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "grok-imagine-image"
}

第 2 步 · 每 2–3 秒查询一次,直到 status 变成 succeeded 或 failed

curl
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

成功时的返回

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "grok-imagine-image",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "grok-imagine-image"}
}

第 3 步 · data[0].url 就是图片链接(PNG),保留 7 天;需要长期使用,请下载到你自己的存储。

完整示例(Python:提交 → 等待 → 保存到本地)

Python
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 提交任务
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "grok-imagine-image",
    "prompt": "清晨雪林里的一只红狐狸,写实摄影风格",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 每 3 秒查询一次,直到结束
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 下载图片
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("grok-imagine-image.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

认证

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在控制台创建 API Key 后即可调用。

请求参数

POST /v1/images/generations 的请求体(JSON):

参数类型必填说明
modelstring是模型 id:grok-imagine-image。
promptstring是画面描述。图生图时写清楚要怎么改。
sizestring否比例,例如 16:9(推荐),也可以写像素尺寸,例如 1536x1024。不传时出 1:1 方图。
resolutionstring否档位:1K(默认)、2K。没有 4K。
image / imagesstring / array否参考图,传了就是图生图:image 传一张,images 传多张(最多 8 张)。可以是公网图片链接、data: URI 或 base64。
ninteger否张数。建议不传:要多张图请同时提交多个任务。传了 n 时按 n 张预扣,按实际交付的张数结算。
callback_urlstring否任务结束时把结果推送到这个地址,见下文的 Webhook。

其他 OpenAI 参数(如 quality、background、output_format、response_format)不影响价格,也不保证生效;成片一律是 PNG,通过 url 返回。

价格

按张计费,价格只看档位,跟比例、文生图还是图生图无关。提交时按档位预扣,任务失败全额退回。1 积分 = $0.005。

档位积分 / 张美元 / 张
1K1$0.005
2K1$0.005

比例、分辨率与输出尺寸

size 写比例,resolution 写档位。1K 交付的图片严格按下表的尺寸;2K 交付上游原图,每种比例的尺寸固定,见下表。改图不按下表:交付跟随第一张参考图比例的原图。

比例1K2K
1:11024x10242048x2048
3:4768x10241776x2368
2:3683x10241664x2496
9:16576x10241584x2816
4:31024x7682368x1776
3:21024x6832496x1664
16:91024x5762816x1584
  • 2K:交付上游原图,不裁切、不缩放。表中 7 种比例都能直接出图,另外 21:9 出 3136x1344;其他比例上游会按最接近的比例出图,和请求不一致时本次失败、不计费。1K:模型按最接近的横版、竖版或方形构图出图,网关再居中裁切、缩放到表中的尺寸。
  • size 也可以写像素尺寸(如 2048x1152):1K 按所写的尺寸交付;2K 只用它来判断比例,交付的是上表对应比例的原图尺寸。档位按 resolution 定;没写 resolution 时看长边:不超过 1536 为 1K,1537 到 2048 为 2K。
  • 这个模型只有 1K 和 2K:要 4K(resolution: "4K",或 size 的长边超过 2048)会直接返回 400 unsupported_resolution,不扣费。要 2K 请写 resolution: "2K"。

图生图与参考图

  • 传 image(一张)或 images(多张,最多 8 张,多出的不用)就是图生图,在提示词里写清楚要怎么改。也可以调用 POST /v1/images/edits,参数相同。
  • 两个接口都只收 JSON 请求体,不支持 multipart 上传文件,所以 OpenAI SDK 的 images.edit() 不能直接用,请按下面的示例传链接或 base64。
  • 每张参考图可以是公网图片链接(http / https)、data: URI 或纯 base64,单张不超过 16MB,JPEG、PNG、WebP 等常见格式都可以。
  • 链接要能直接下载到图片本身,不能是网页、需要登录或有防盗链的地址。读不到的参考图会在提交时直接返回 400,写明是哪一张、什么原因,不建任务、不扣费。
  • 改图时出图比例跟随第一张参考图(传多张时以第一张为准),size 只用来选档位、改不了比例。交付的是上游原图,不裁切、不缩放,照常计费,实际像素尺寸写在返回的 data[].size 里。要别的比例,请先把第一张参考图裁成那个比例。
  • 参考图由我们代为托管,保留 7 天。

两张参考图的图生图

curl
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image", "prompt": "保留画面里的人物,把背景换成夜晚的海边,加上暖色的灯串", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

任务状态与返回字段

GET /v1/images/jobs/{id} 返回的状态如下,每个字段的说明见 异步任务。建议每 2–3 秒查一次,或者用 Webhook。

状态含义
queued排队中。返回里带 queue_position(前面还有几个任务)和 eta_seconds(预计等待秒数)。
processing生成中。
succeeded已完成。结果在 data[0].url,计费明细在 usage。
failed失败。原因在 error,预扣的积分已全额退回。

同一个账号最多 50 个任务同时生成,更多的任务按提交顺序排队;排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天,图片链接保留 7 天。

出图时间

从提交到拿到结果,通常 5–20 秒;2K 和图生图稍慢一些。

近 7 天真实调用:中位 7 秒,90% 在 10 秒 内完成。

错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx,不建任务、不扣费;提交成功后的失败写在查询结果里,预扣的积分全额退回。全部错误码见 错误码。

提交时返回的错误

HTTPcode原因怎么办
400missing_prompt/v1/images/generations 没有 prompt。补上 prompt。
400invalid_request参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。按 message 修改后重新提交。
400unsupported_resolution这个模型不提供所选的分辨率档位(例如 Grok 生图没有 4K)。换一个档位;各模型支持的档位见它的文档。
400model_not_found型号写错、没有传 model,或这个型号不能用在这个接口上(例如拿对话模型调生图接口)。以 GET /v1/models 或 API 手册 里的模型 id 为准。
401invalid_api_keyKey 不存在、已删除或已停用,或者账号已停用。到控制台「API Keys」页面检查这把 Key。
402insufficient_quota余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。如果是并发突发,稍等几秒重试;否则充值。
429rate_limit_exceeded超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。等几秒再试,或在控制台调高这把 Key 的上限。
503model_maintenance型号维护中,暂停接单,期间不会改由其他模型作答。维护结束后重试,进度见 服务状态。
503service_unavailable我们这边临时出错,例如保存参考素材失败;/v1/responses 暂时无法处理时也返回 503,并带 Retry-After。稍后重试。

任务失败(status 为 failed)

code什么时候出现怎么办
moderation_blocked图片:模型方的安全审核拒绝了提示词或参考图(也可能是 content_policy_violation)。改写提示词或更换参考图;原样重交通常还会被拒。
upstream_error其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。通常重新提交就能成功。

用 Webhook 代替轮询

提交时加上 callback_url,任务一结束(成功或失败),网关就把和查询接口完全一样的结果推送到这个地址,带签名,失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image", "prompt": "清晨雪林里的一只红狐狸,写实摄影风格", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'