> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 视觉与图像生成

> Moxus AI支持三类图像相关能力（取决于所选模型）：

Moxus AI支持三类图像相关能力（取决于所选模型）：

1. 视觉理解（图像转文本）：对输入图像进行理解与分析。
2. 图像生成（文本转图像）：根据文本描述生成图像。
3. 图像编辑（图像转图像）：基于已有图像进行修改。

## 视觉理解

使用支持视觉的对话模型（如 `gpt-4o`、`claude-3-5-sonnet`、`gemini-2.5-pro`），在 `messages` 中同时传入文本与图像。

### 方式 A：传递图像 URL

```json theme={null}
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "这张图片里有什么？请详细描述。"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ]
}
```

### 方式 B：传递 Base64 编码图像

若图像为本地文件，先转为 Base64，再使用 `data:` URI 传入：

```json theme={null}
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}
```

### Python 示例（本地图像转 Base64）

```python theme={null}
import base64
from openai import OpenAI

client = OpenAI(api_key="sk-你的密钥", base_url="https://moxus.ai/v1")

with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{b64}"},
                },
            ],
        }
    ],
)
print(resp.choices[0].message.content)
```

### 视觉理解的典型应用

* 图像内容描述、物体识别。
* 截图问答（如报错信息分析）。
* 表格或文档图片信息提取（OCR 与理解）。
* 图表解读。

## 图像生成

使用图像生成模型（如 `gpt-image-1`、`dall-e-3` 等，以模型广场为准）调用 `/v1/images/generations`。

### 请求

```json theme={null}
{
  "model": "gpt-image-1",
  "prompt": "一只戴着宇航员头盔的柴犬，漂浮在星空中，卡通风格",
  "n": 1,
  "size": "1024x1024"
}
```

| 参数                | 说明                                       |
| ----------------- | ---------------------------------------- |
| `model`           | 图像生成模型名称                                 |
| `prompt`          | 图像的文本描述（越具体越佳）                           |
| `n`               | 生成图像数量（部分模型仅支持 1）                        |
| `size`            | 尺寸，如 `1024x1024`、`1792x1024`、`1024x1792` |
| `response_format` | `url`（返回链接）或 `b64_json`（返回 Base64）       |

### cURL 示例

```bash theme={null}
curl https://moxus.ai/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "一只戴着宇航员头盔的柴犬，漂浮在星空中，卡通风格",
    "n": 1,
    "size": "1024x1024"
  }'
```

### 响应

```json theme={null}
{
  "created": 1710000000,
  "data": [
    {
      "url": "https://.../generated-image.png"
    }
  ]
}
```

若指定 `"response_format": "b64_json"`，则返回：

```json theme={null}
{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg..."
    }
  ]
}
```

### Python 示例（生成并保存图像）

```python theme={null}
import base64
from openai import OpenAI

client = OpenAI(api_key="sk-你的密钥", base_url="https://moxus.ai/v1")

resp = client.images.generate(
    model="gpt-image-1",
    prompt="一只戴着宇航员头盔的柴犬，漂浮在星空中，卡通风格",
    n=1,
    size="1024x1024",
    response_format="b64_json",
)

img_b64 = resp.data[0].b64_json
with open("output.png", "wb") as f:
    f.write(base64.b64decode(img_b64))
print("图片已保存为 output.png")
```

### 编写有效的 Prompt

* 具体描述主体、风格、构图、光线、色调及背景。
* 明确指定风格（如卡通、写实摄影、水彩画、像素风）。
* 如有不希望出现的内容，可明确说明。

## 图像编辑

使用 `/v1/images/edits` 基于已有图像进行修改（如替换背景、局部重绘）。此类接口通常需上传原图（及可选的蒙版 mask），一般使用 `multipart/form-data` 表单方式：

```bash theme={null}
curl https://moxus.ai/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -F model="gpt-image-1" \
  -F image="@original.png" \
  -F prompt="把背景换成海边日落"
```

具体支持的编辑能力与所需参数取决于所选模型。

## 计费说明

* 视觉理解：图像会被换算为一定数量的输入 Token 参与计费，图像越大或越清晰，Token 越多。
* 图像生成与编辑：通常按次固定计费（每张图像固定价格），也可能按尺寸不同而不同。

具体价格参见 [模型与定价](/zh/overview/models-and-pricing)。

## 注意事项

* 确认模型能力。仅支持相应能力的模型可使用对应功能，请先在模型广场核对。
* 图像大小。过大的图像会消耗更多 Token（视觉理解）或被拒绝，必要时应先压缩。
* URL 可访问性。使用图像 URL 时，须确保该 URL 公网可访问。

## 后续步骤

* 向量嵌入：参阅 [向量嵌入与重排序](/zh/guide/embeddings-and-rerank)。