Grok 图像格式（Image）

官方文档

xAI Image Generation · xAI Image Generation 能力说明

📝 简介

Grok 图片生成接口与 OpenAI 风格 REST API 兼容，通过 POST /v1/images/generations 根据文本提示生成图片。经 agtcloud 网关转发时，请使用 https://api-cs-al.naci-tech.com 作为 base URL，并携带您的 API Key。

模型	描述
grok-imagine-image-pro	进阶图片模型，适合高质量、精细场景
grok-imagine-image	通用图片生成模型

💡 请求示例

创建图片 ✅

# 基础图片生成（返回 URL）
curl https://api-cs-al.naci-tech.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-imagine-image-pro",
    "prompt": "A cat in a tree",
    "n": 1,
    "response_format": "url"
  }'

# 生成多张图片
curl https://api-cs-al.naci-tech.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "A cat in a tree",
    "n": 2,
    "response_format": "url"
  }'

# 使用 base64 返回格式
curl https://api-cs-al.naci-tech.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-imagine-image-pro",
    "prompt": "A cat in a tree",
    "response_format": "b64_json"
  }'

# 指定宽高比（可选）
curl https://api-cs-al.naci-tech.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "Mountain landscape at sunrise",
    "aspect_ratio": "16:9"
  }'

# 指定分辨率（可选：1k / 2k）
curl https://api-cs-al.naci-tech.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "Mountain landscape at sunrise",
    "resolution": "2k"
  }'

响应示例（response_format 为 url）：

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}

响应示例（response_format 为 b64_json）：

{
  "created": 1589478378,
  "data": [
    {
      "b64_json": "..."
    }
  ]
}

Python 调用示例（OpenAI 风格 REST）：

"""
Grok 图片生成 API 调用示例（OpenAI 风格 REST）
- 接口：POST /v1/images/generations
"""

import requests

API_BASE = "https://api-cs-al.naci-tech.com"
API_KEY = ""

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def generate_image(
    prompt: str,
    n: int = 1,
    response_format: str = "url",
):
    """
    使用 Grok 图片模型按 OpenAI 风格生成图片。
    """
    body = {
        "prompt": prompt,
        "model": "grok-imagine-image-pro",  # 可选：grok-imagine-image-pro, grok-imagine-image
        "response_format": response_format,
        "n": n,
    }

    resp = requests.post(
        f"{API_BASE}/v1/images/generations",
        headers=HEADERS,
        json=body,
        timeout=30,
    )
    if not resp.ok:
        try:
            err = resp.json()
        except Exception:
            err = resp.text
        print(f"[{resp.status_code}] {err}")
        resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    # 示例：生成 2 张图片 URL
    res = generate_image(
        prompt="A cat in a tree",
        n=2,
        response_format="url",  # 如需 base64，可改为 "b64_json"
    )
    print("Response:", res)

📮 请求

端点

端点：创建图片

POST /v1/images/generations

根据文本提示创建图片。与 xAI Image Generation 兼容，经 agtcloud 网关时 Base URL 为 https://api-cs-al.naci-tech.com。

鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

Authorization: Bearer $API_KEY

其中 $API_KEY 是您在 agtcloud 的 API 密钥。

请求体参数

参数：创建图片

prompt

• 类型：字符串
• 必需：是
• 说明：期望生成图片的文本描述。

model

• 类型：字符串
• 必需：是
• 说明：用于图像生成的模型。
• grok-imagine-image-pro：进阶图片模型
• grok-imagine-image：通用图片模型

n

• 类型：整数
• 必需：否
• 默认值：1
• 说明：要生成的图片数量。必须在 1～10 之间。

response_format

• 类型：字符串
• 必需：否
• 默认值：url
• 说明：返回生成图片的格式。
• url：返回临时图片 URL（建议尽快下载或处理）
• b64_json：返回 base64 编码的图片数据

aspect_ratio

• 类型：字符串
• 必需：否
• 说明：生成图片的宽高比。不传时由模型自动选择。可选值示例：

宽高比	适用场景
1:1	社交媒体、缩略图
16:9 / 9:16	宽屏、竖屏、故事图
4:3 / 3:4	演示、人像
3:2 / 2:3	摄影
2:1 / 1:2	横幅、页头
19.5:9 / 9:19.5	常见手机屏
20:9 / 9:20	超宽屏
auto	由模型根据 prompt 自动选择

resolution

• 类型：字符串
• 必需：否
• 说明：生成图片的输出分辨率。当前支持：

分辨率	说明
1k	1k 分辨率
2k	2k 分辨率

参考：xAI Image Generation - Resolution

user

• 类型：字符串
• 必需：否
• 说明：代表最终用户的唯一标识符，便于监控与风控。

📥 响应

成功响应

created

• 类型：整数
• 说明：响应创建的时间戳。

data

• 类型：数组
• 说明：生成的图片对象列表。

图片对象

url

• 类型：字符串
• 说明：当 response_format 为 url 时，为生成图片的临时 URL。请尽快下载或使用，链接有时效。

b64_json

• 类型：字符串
• 说明：当 response_format 为 b64_json 时，为生成图片的 base64 编码数据。

🌟 说明与限制

• 单次请求最多生成图片数：10 张。
• URL 有效期：返回的 URL 为临时链接，请及时下载或处理。
• 内容审核：生成图片受内容政策约束，可能因违规被过滤。
• 输出格式：图片通常为 JPG 格式。

更多能力说明（如图片编辑、风格迁移等）可参考 xAI Image Generation。