Flux 绘画（OpenAI 兼容） - 数字先锋API文档

# Flux 绘画 API 文档（OpenAI 兼容）

> 接口协议：OpenAI Chat Completions 兼容
> 统一路径：`/v1/chat/completions`

体验中心（自动翻译 + 图像生成）：https://try.cxsee.com/image/flux/

## 1. 概述

Flux 是 Black Forest Labs 开发的开源图像生成模型，采用 Diffusion Transformer 架构。
本平台以 **OpenAI Chat Completions** 形式提供 Flux 能力，便于快速接入。

- 支持模型：如 `flux-dev`（以控制台实际上线模型为准）
- 返回形式：图片 URL 嵌入在 `choices[0].message.content`（Markdown 格式）
- 语言建议：Flux 对中文提示词理解相对弱，建议先翻译为英文再生成

---

## 2. 接口信息

### URL
`POST /v1/chat/completions`
完整地址：`https://api.cxsee.com/v1/chat/completions`

### Headers
- `Authorization: Bearer YOUR_API_KEY`
- `Content-Type: application/json`

---

## 3. 请求参数（常用）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 模型名，如 `flux-dev` |
| `messages` | array | 是 | 对话消息，图像提示词放在 user content |
| `stream` | boolean | 否 | 是否流式返回，默认 `false` |

`messages` 示例：
```json
[
  {"role":"user","content":"A cute orange cat, soft lighting, high detail"}
]
```

---

## 4. 标准调用示例（cURL）

```bash
curl -s https://api.cxsee.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"flux-dev",
    "stream": false,
    "messages":[
      {"role":"user","content":"Draw a cat, cinematic light, ultra detailed"}
    ]
  }'
```

---

## 5. 成功返回示例

```json
{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1772749181,
  "model": "flux-dev",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Draw a cat  ![image1](https://s3.ffire.cc/cdn/20260306/wu5w4Yb7WcwmJWN3ofFnaH) [下载1](https://s3.ffire.cc/cdn/20260306/wu5w4Yb7WcwmJWN3ofFnaH)"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 2
  }
}
```

---

## 6. 图片 URL 提取规则

图片地址位于：`choices[0].message.content`，通常为 Markdown：

- `![image1](图片URL)`
- `[下载1](图片URL)`

可用正则提取：
```regex
\((https?://[^)]+)\)
```

> 建议：提取后对 URL 去重，取第一个或全部下载链接。

---

## 7. 错误返回示例

```json
{
  "error": {
    "message": "错误说明（含 request id）",
    "type": "new_api_error",
    "param": "",
    "code": "do_request_failed"
  }
}
```

常见错误场景：
- API Key 无效或过期
- 上游模型请求失败
- 请求参数格式错误（如缺少 `model` / `messages`）

---

## 8. 最佳实践

1. **中文先翻译英文**：显著提升出图稳定性与可控性。
2. **提示词结构化**：主体 + 风格 + 光线 + 镜头 + 细节。
3. **关闭流式优先**：图像任务建议 `stream=false`，便于一次性提取 URL。
4. **结果落盘**：拿到链接后立即下载保存，避免临时链接过期。
5. **失败重试**：5xx 或上游错误可指数退避重试 1~2 次。

---

图像生成效果
![](https://img.cxhao.com/images/5/2026/02/iq15oKI8M7mSQZFZUv7iYmSi5KuM7D.png)

上一篇：千问（Qwen）图像编辑下一篇：X.AI 绘画（OpenAI 兼容）