X.AI 绘画（OpenAI 兼容） - 数字先锋API文档

# xAI 绘图模型（OpenAI 兼容）API 文档

> 适用于在 `OpenAI SDK / OpenAI 协议` 下调用 xAI 图像生成能力。
> 当前通过 `chat/completions` 接口返回图片链接。

---

## 1. 接口地址

### Base URL
```text
https://api.cxsee.com
```

### Endpoint
```text
POST /v1/chat/completions
```

---

## 2. 认证方式

在请求头中传入 API Key：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

---

## 3. 支持模型

- `grok-4.1-image`（别名）
- 实际响应中可能显示为：`grok-4-1-image`

---

## 4. 请求参数（核心）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称，如 `grok-4.1-image` |
| messages | array | 是 | OpenAI 标准对话消息 |
| stream | boolean | 否 | 是否流式返回，默认 `false` |

`messages` 示例：
```json
[
  {
    "role": "user",
    "content": "画一只小猫"
  }
]
```

---

## 5. 请求示例（cURL）

```bash
curl -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.1-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "画一只小猫"
      }
    ]
  }'
```

---

## 6. 成功响应示例

```json
{
  "id": "ba9be7e4-8612-4dc5-9dc6-c7ff66d0d843",
  "object": "chat.completion",
  "created": 1774065473,
  "model": "grok-4-1-image",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "![image](https://proxy.deepwl.net/file_download/xxx)\n\n![image](https://proxy.deepwl.net/file_download/yyy)\n\nI generated images with the prompt: 'cat'",
        "reasoning_content": "生成进度信息..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 224,
    "total_tokens": 231
  }
}
```

---

## 7. 图片结果解析说明

返回图片通常在：

- `choices[0].message.content`

内容为 Markdown 图片链接，例如：

```markdown
![image](https://proxy.deepwl.net/file_download/xxx)
```

你可以：
1. 正则提取 `(...)` 中 URL；
2. 直接在前端渲染 Markdown；
3. 将 URL 下载并转存到自有对象存储（建议生产环境这样做）。

---

## 8. 错误响应示例

```json
{
  "error": {
    "message": "剩余积分不足",
    "type": "bad_response_status_code",
    "code": "bad_response_status_code"
  }
}
```

常见错误原因：
- API Key 无效或缺失
- 账户余额/积分不足
- 模型无权限或不可用
- 请求频率超限

---

## 9. OpenAI SDK 调用示例（Python）

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cxsee.com/v1"
)

resp = client.chat.completions.create(
    model="grok-4.1-image",
    stream=False,
    messages=[
        {"role": "user", "content": "画一只小猫，卡通风格，白色背景"}
    ]
)

print(resp.choices[0].message.content)
```

---

## 10. 使用建议

- 提示词尽量具体：主体 + 风格 + 构图 + 光照 + 比例
- 返回的是图片 URL，注意链接有效期与防盗链策略
- 若用于生产，建议将图片抓取后存储到自有 CDN
- 控制请求频率，避免触发限流

---

上一篇：Flux 绘画（OpenAI 兼容）下一篇：X.AI 对话（OpenAI 兼容）