Developer Docs / Image Generation

使用 Grok Imagine 创建并保存图片结果

本文档覆盖站内当前图片模型:grok-imagine-image、 grok-imagine-image-2.0、grok-imagine-image-quality。 示例 Base URL 为 https://img.apixgo.com。请在后端调用;具体返回字段以实际响应为准。

Base URL https://img.apixgo.com
模型列表 GET /v1/models
生成图片 POST /v1/images/generations
鉴权 Bearer Token

接口概览

三个 Grok Imagine 图片模型均用于图片生成。公开文档未给出它们在参数、尺寸或输出字段上的逐项差异; 调用前请用 GET /v1/models 确认模型 ID,并以实际响应为准。

若网关按 OpenAI 兼容图片接口映射,可使用 POST /v1/images/generations。 是否返回 b64_json、URL 或其他字段,以网关实际响应为准,本文不臆造未验证字段。

后端调用原则

不要在浏览器端直接调用图片接口。API Key 应只存在于服务端环境变量、密钥管理服务或后端运行时中。

请求流程

  1. 确认模型

    调用 GET /v1/models,确认所选 grok-imagine-image* 可用。

  2. 构造请求

    向 POST /v1/images/generations 提交 JSON(至少包含 model 与 prompt)。

  3. 读取结果

    按实际响应保存图片(常见为 base64 或 URL;以返回为准)。

  4. 转存

    解码或下载后保存到本地、R2、S3 或业务素材库。

认证方式

所有接口使用 Bearer Token。请在用户控制台创建或复制 API Key,并放入请求头。

HTTP Header
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
查询模型
curl -X GET "https://img.apixgo.com/v1/models" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

模型对照表

仅列出当前 Imagine 图片 / 视频模型。未写明的能力差异请以 GET /v1/models 与实际网关返回为准。

模型名 类型 说明 / 适用场景 备注
grok-imagine-image 图片 用途:图片生成。 文档未公开更多差异;以 /v1/models 与网关实际参数为准。
grok-imagine-image-2.0 图片 用途:图片生成。 文档未公开更多差异;以 /v1/models 与网关实际参数为准。
grok-imagine-image-quality 图片 用途:图片生成(名称含 quality)。 质量档位与计费以网关为准。
grok-imagine-video-1.5 视频 当前视频模型;单参考图生视频。 详见 视频生成文档。

文本 / 编程模型不在本表: grok-4.7、grok-4.7-build-fast、grok-build-0.1 请使用对话类 API (如 https://coding.apixgo.com)。

模型说明

请求参数

下表列出 OpenAI 兼容图片生成接口的常见字段。除 model / prompt 外,其余字段是否被 Grok Imagine 接受,请以实际网关错误与响应为准;若返回 400,请去掉未支持字段。

字段 类型 必填 说明
model string 是 使用 grok-imagine-image、 grok-imagine-image-2.0 或 grok-imagine-image-quality。
prompt string 是 图片生成指令。建议写清主体、风格、构图、光线与限制。
n integer 否 生成数量。是否支持以网关为准。
size string 否 尺寸。是否支持及可选值以网关为准。
quality string 否 质量档位。是否支持以网关为准(尤其 …-quality 模型)。
output_format string 否 输出格式(如 png / jpeg / webp)。是否支持以网关为准。

提示词建议

  • 明确主体、场景、用途和画面比例。
  • 写清不要出现的内容,例如水印、额外 logo、变形手指。

生成示例

curl JSON 请求

POST /v1/images/generations
curl -X POST "https://img.apixgo.com/v1/images/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A clean studio product photo of a matte black wireless headphone, soft rim light, white background",
    "n": 1
  }'

Node.js 示例

Backend Example
import fs from 'node:fs/promises';

const BASE_URL = 'https://img.apixgo.com';
const API_KEY = process.env.IMAGE_API_KEY;

const response = await fetch(`${BASE_URL}/v1/images/generations`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'grok-imagine-image-2.0',
    prompt: 'A modern API documentation cover image, precise grid, teal accent, editorial style',
    n: 1,
  }),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(`Image request failed: ${JSON.stringify(result)}`);
}

// 按实际响应取值:部分网关返回 b64_json,部分返回 url
const item = result.data?.[0];
if (item?.b64_json) {
  await fs.writeFile('grok-imagine-output.png', Buffer.from(item.b64_json, 'base64'));
} else if (item?.url) {
  const img = await fetch(item.url);
  await fs.writeFile('grok-imagine-output.png', Buffer.from(await img.arrayBuffer()));
} else {
  throw new Error(`Unrecognized image payload: ${JSON.stringify(result)}`);
}
说明

示例把 model 设为 grok-imagine-image-2.0,可换成 grok-imagine-image 或 grok-imagine-image-quality。 未验证的可选参数请先不加;若 400 再对照错误信息调整。

响应处理

图片接口通常返回数组。请按实际字段保存,不要写死某一种返回形态。

常见取值 response.data[0].b64_json 或 response.data[0].url(以实际为准)
保存方式 服务端解码 base64 或下载 URL,并保存为目标格式文件。
多张图片 若返回多条,遍历 response.data 逐张保存。
前端展示 建议后端先保存为文件 URL,再返回给前端展示。

状态/错误码

状态或错误 含义 建议处理
401 API Key 缺失或错误。 检查 Authorization: Bearer <YOUR_API_KEY>。
403 权限、额度、分组或模型访问限制。 检查账号余额、令牌权限和模型可用性。
400 prompt is required prompt 为空。 提交前校验提示词。
400 invalid model 模型名不可用或未映射。 调用 /v1/models,确认模型名和中转映射。
400(参数相关) 可选字段不被当前模型支持。 去掉 size / quality / output_format 等未验证字段后重试。
429 请求过于频繁或额度不足。 加入重试退避,降低并发,检查额度。
5xx 服务端或上游暂时异常。 保留请求参数和错误响应,稍后重试或提交排查。

常见问题

  • 可以在前端直接调用图片 API 吗?
    不建议。前端代码会暴露 Key,应由后端代调并返回保存后的图片 URL。
  • 三个 Imagine 图片模型有什么区别?
    公开文档尚未给出逐项参数对照。请按业务需要选择模型名,并用实际响应确认输出格式。
  • 为什么示例里没有 size / quality?
    这些字段对 Grok Imagine 是否生效尚未在公开文档中核实。需要时可自行试探;失败则去掉。
  • 视频怎么生成?
    使用 grok-imagine-video-1.5,见 视频生成文档。