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

# 视觉与图像生成

> 使用 gpt-5.4 理解图片，或使用 grok-imagine-image 根据提示词生成图片。

Moxus AI 支持图像理解、图像生成和图像编辑。不同模型的输入格式、尺寸、数量和返回格式可能不同；本页示例分别使用 `gpt-5.4` 进行图像理解，以及 `grok-imagine-image` 进行图像生成。

<Columns cols={2}>
  <Card title="图像理解" icon="scan-eye" href="#image-understanding">
    发送公网图片 URL，或读取本地图片并以 Base64 方式传入。
  </Card>

  <Card title="图像生成" icon="wand-sparkles" href="#image-generation">
    根据文本提示词生成图片，并将返回的 Base64 内容保存为本地文件。
  </Card>

  <Card title="图像编辑" icon="image-plus" href="#image-editing">
    基于已有图片进行编辑，具体能力取决于所选模型。
  </Card>

  <Card title="提示词建议" icon="text-cursor-input" href="#prompting-tips">
    用主体、风格、构图和约束描述你需要的图片。
  </Card>
</Columns>

<Tip>
  如果你还在调试提示词，可以先到网页端“对话”选择图像生成模型直接生成图片。确认模型和提示词效果后，再使用本页的 API 示例接入外部程序。
</Tip>

<span id="image-understanding" />

## 图像理解

图像理解使用 OpenAI 兼容的 `chat/completions` 接口。图片可以传公网 URL，也可以把本地图片转为 Base64 后通过 `data:` URI 传入。示例模型为 `gpt-5.4`。

### 使用本地图片

本地图片会由代码读取并自动转换为 Base64，再随请求发送。Python 示例中的 `IMAGE_PATH = "photo.jpg"` 表示图片与 Python 文件放在同一项目文件夹，且文件名必须与实际图片完全一致，包括扩展名和大小写；图片在其他位置时，改为完整本地路径。Node.js 示例使用 `const IMAGE_PATH = "photo.png"`，将图片与 `.mjs` 文件放在同一项目文件夹后，从该文件夹终端运行代码。若文件名或格式不同，修改 `IMAGE_PATH` 与 `IMAGE_MIME_TYPE`。

<Info>
  Python 和 Node.js 示例的依赖安装、运行方式及环境问题，参阅 [常见问题](/zh/overview/faq)。
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  # 此示例使用公网可访问的图片 URL；如果是本地图片，请看 Python 或 Node.js 示例。
  curl https://moxus.cloud/v1/chat/completions \
    -H "Authorization: Bearer 你的密钥" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.4",
      "messages": [
        {
          "role": "user",
          "content": [
            {"type": "text", "text": "请描述这张图片，并列出其中的关键信息。"},
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/photo.jpg"
              }
            }
          ]
        }
      ]
    }'
  ```

  ```python Python theme={null}
  # base64 是 Python 标准库，用来把本地图片转成可放入 JSON 的文本。
  import base64
  import httpx
  from openai import OpenAI

  # 只需替换这两项：你的 API 密钥，以及本地图片的文件名或完整路径。
  API_KEY = "你的密钥"
  IMAGE_PATH = "photo.jpg"
  # JPEG 使用 image/jpeg；如果 IMAGE_PATH 指向 PNG，请改为 image/png。
  IMAGE_MIME_TYPE = "image/jpeg"

  client = OpenAI(
      api_key=API_KEY,
      base_url="https://moxus.cloud/v1",
      # 直接连接 Moxus AI，不读取系统或终端代理环境变量。
      http_client=httpx.Client(trust_env=False, timeout=60.0),
  )

  # 读取本地图片文件，并编码成 Base64 字符串。
  # "rb" 中 r 表示读取，b 表示二进制模式；图片必须以二进制模式读取。
  with open(IMAGE_PATH, "rb") as image_file:
      image_base64 = base64.b64encode(image_file.read()).decode("utf-8")

  response = client.chat.completions.create(
      model="gpt-5.4",
      messages=[
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "请描述这张图片，并列出其中的关键信息。"},
                  {
                      "type": "image_url",
                      "image_url": {
                          # 前缀告诉模型后面是该格式图片的 Base64 内容。
                          "url": f"data:{IMAGE_MIME_TYPE};base64,{image_base64}",
                      },
                  },
              ],
          }
      ],
  )

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

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  // readFileSync 是 Node.js 标准库方法，用来读取本地图片文件。
  import { readFileSync } from "node:fs";

  // 将 photo.png 放在 .mjs 文件同一项目文件夹；文件名或格式不同时同步修改下面两项。
  const API_KEY = "你的密钥";
  const IMAGE_PATH = "photo.png";
  const IMAGE_MIME_TYPE = "image/png";

  const client = new OpenAI({
    apiKey: API_KEY,
    baseURL: "https://moxus.cloud/v1",
  });

  // 把本地图片转成 Base64 字符串，方便放入 JSON 请求体。
  const imageBase64 = readFileSync(IMAGE_PATH).toString("base64");

  const response = await client.chat.completions.create({
    model: "gpt-5.4",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "请描述这张图片，并列出其中的关键信息。" },
          {
            type: "image_url",
            image_url: {
              // 前缀表示后面是该格式图片的 Base64 内容。
              url: `data:${IMAGE_MIME_TYPE};base64,${imageBase64}`,
            },
          },
        ],
      },
    ],
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

<span id="image-generation" />

## 图像生成

图像生成使用 OpenAI 兼容的 `/v1/images/generations` 接口。本页示例使用 `grok-imagine-image`；不同模型支持的尺寸、数量和返回格式可能不同，接入前请先在模型广场确认模型名称与计费方式。

<CodeGroup>
  ```bash cURL theme={null}
  # prompt 是图片描述；size、n 等参数是否可用取决于所选图像模型。
  curl https://moxus.cloud/v1/images/generations \
    -H "Authorization: Bearer 你的密钥" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "grok-imagine-image",
      "prompt": "一张现代办公桌上的智能台灯产品图，白色背景，柔和棚拍光线",
      "n": 1,
      "size": "1024x1024"
    }'
  ```

  ```python Python theme={null}
  # base64 是 Python 标准库，用来把接口返回的图片 Base64 解码成图片文件。
  import base64
  import httpx
  from openai import OpenAI

  client = OpenAI(
      api_key="你的密钥",
      base_url="https://moxus.cloud/v1",
      # 直接连接 Moxus AI，不读取系统或终端代理环境变量。
      http_client=httpx.Client(trust_env=False, timeout=60.0),
  )

  response = client.images.generate(
      model="grok-imagine-image",
      prompt="一张现代办公桌上的智能台灯产品图，白色背景，柔和棚拍光线",
      n=1,
      size="1024x1024",
      response_format="b64_json",
  )

  # response_format="b64_json" 时，图片内容会在 b64_json 字段里返回。
  image_base64 = response.data[0].b64_json

  # 把 Base64 图片内容写入本地 PNG 文件。
  with open("generated-image.png", "wb") as image_file:
      image_file.write(base64.b64decode(image_base64))

  print("图片已保存为 generated-image.png")
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  // writeFileSync 是 Node.js 标准库方法，用来把图片写到本地文件。
  import { writeFileSync } from "node:fs";

  const client = new OpenAI({
    apiKey: "你的密钥",
    baseURL: "https://moxus.cloud/v1",
  });

  const response = await client.images.generate({
    model: "grok-imagine-image",
    prompt: "一张现代办公桌上的智能台灯产品图，白色背景，柔和棚拍光线",
    n: 1,
    size: "1024x1024",
    response_format: "b64_json",
  });

  // response_format: "b64_json" 时，图片内容会在 b64_json 字段里返回。
  const imageBase64 = response.data[0].b64_json;

  // Buffer.from(..., "base64") 会把 Base64 字符串还原为图片二进制内容。
  writeFileSync("generated-image.png", Buffer.from(imageBase64, "base64"));

  console.log("图片已保存为 generated-image.png");
  ```
</CodeGroup>

<span id="image-editing" />

## 图像编辑

图像编辑用于基于已有图片修改背景、局部内容或整体风格。编辑接口、文件上传方式和可用参数由模型决定；调用前请在模型广场确认所选模型支持图像编辑。

<span id="prompting-tips" />

## 提示词建议

* 描述主体、风格、构图、光线、色调及背景。
* 明确图片用途和限制，例如尺寸比例、需要保留或避免的元素。
* 需要稳定字段时，将图像理解与 [结构化输出](/zh/guide/structured-output) 结合使用。

## 计费说明

* 图像理解：图像会被换算为一定数量的输入 Token 参与计费，图像越大或越清晰，Token 越多。
* 图像生成与编辑：通常按次固定计费，也可能随尺寸或模型而变化。

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

## 注意事项

* 仅使用模型广场标记支持对应能力的模型。
* 过大的图像会消耗更多 Token 或被拒绝，必要时先压缩。
* 使用图片 URL 时，确保该 URL 可被公网访问。

## 后续步骤