Grok Image 文生图 | 青云TOP API 文档

使用 grok-imagine-image-2.0 提交文字提示词，生成图片并获得临时 URL 或 Base64 结果。

功能与支持模型

本页适合从文字创建全新图片，推荐模型为 grok-imagine-image-2.0。示例一次生成 1 张；需要同一提示词生成多张时，可将 n 改为 2–10。该调用不接收参考图片，不提供编辑或遮罩操作。

第一步：设置鉴权

使用请求头 Authorization: Bearer YOUR_API_KEY。把 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的空格。

第二步：调用模型

发送 POST https://top.qingyuntop.ai/v1/images/generations，使用 Content-Type: application/json。请求为同步方式，保持连接直到响应返回。

请求参数

字段与类型	填写规则、默认值与限制
`model`；string / null	JSON 顶层；必填，显式填写 grok-imagine-image-2.0；不依赖默认型号，不传 null。
`prompt`；string	JSON 顶层；必填非空字符串，无推荐默认值；描述主体、场景、风格、构图与文字要求。
`n`；integer / null	JSON 顶层；可选，不传 null；生成图片数量。一次多张时处理完整 data 数组，以实际返回数量为准。默认 1。范围 1–10。
`response_format`；string / null	JSON 顶层；可选，不传 null；允许 url 或 b64_json。url 返回临时图片链接；b64_json 返回不带 data URI 前缀的 Base64。它不指定图片文件编码。默认 url。

不要附加 size、quality 或参考图字段；具体边界见参数与调用限制。

示例一：返回图片 URL

cURL 示例使用 Bash，需 cURL 7.76+ 与 jq；Python 需安装 requests；Node.js 需 20+，保存为 .mjs 运行。600 秒是客户端等待设置，不是生成耗时承诺。每次调用会覆盖 request.json 或 response.json，请按业务需要另存。

以下三种语言发送相同请求，并将生成响应保存为 response.json。HTTP 错误会终止示例；收到 JSON 后还需确认 data 非空且包含图片链接。

set -euo pipefail
cat > request.json <<'JSON'
{
  "model": "grok-imagine-image-2.0",
  "prompt": "一只橘猫坐在窗边的木桌上，窗外是雨后的花园，自然柔光，写实摄影，画面干净。",
  "n": 1,
  "response_format": "url"
}
JSON
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json --output response.json
jq -e 'if .error then error(.error | tostring) else
  (.data | type == "array" and length > 0) and
  all(.data[]; .url | type == "string" and length > 0) end' response.json

示例二：返回 Base64

当应用希望直接取得图片内容时，将 response_format 设为 b64_json。此示例会再次调用模型；仅选择适合你的返回方式运行即可。

set -euo pipefail
cat > request.json <<'JSON'
{
  "model": "grok-imagine-image-2.0",
  "prompt": "一只橘猫坐在窗边的木桌上，窗外是雨后的花园，自然柔光，写实摄影，画面干净。",
  "n": 1,
  "response_format": "b64_json"
}
JSON
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json --output response.json
jq -e 'if .error then error(.error | tostring) else
  (.data | type == "array" and length > 0) and
  all(.data[]; .b64_json | type == "string" and length > 0) end' response.json

响应与图片保存

成功结果位于 data[]：URL 模式读取 url，Base64 模式读取 b64_json。不要依赖固定存在的 created、revised_prompt 或任务 ID。HTTP 200 本身不足以证明得到了图片，还需检查数组及每个元素。

上面的代码保存的是响应 JSON；继续执行返回结果与图片保存的示例，才会得到图片文件。该步骤不再次调用生成接口。

常见错误与参考

401/403 先检查本站 API Key 和模型权限；参数错误先恢复本页四字段请求；返回为空或连接超时不要立即循环重试，详见常见错误。厂商参考：图片生成指南。