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

# Imagine

> 使用 Imagine 完成文生图和图片编辑。

<Warning>
  生成结果**仅保存在当前浏览器本地**，**不会存储在 AIOHub 服务器**。**清空浏览器数据会删除历史图片**，请及时下载需要保留的结果。
</Warning>

[Imagine](https://imagine.aiohub.org/) 是 AIOHub 的浏览器图片工作台，支持 `gpt-image-2` 的文生图和图片编辑。输入提示词或上传参考图即可出图，适合调试提示词和对比生成效果。你也可以在控制台 **令牌管理** 页对支持图片模型的令牌点击 **Imagine**，页面会自动填入该令牌。

<Frame>
  <img src="https://mintcdn.com/qyhfrankgmailcom/4qHxe2G9W8j3rdqH/images/common/clients/imagine/token-management-imagine.png?fit=max&auto=format&n=4qHxe2G9W8j3rdqH&q=85&s=00e8c58a46ad158513f0278b494dd136" alt="AIOHub 令牌管理页面中，单个 images 令牌的操作区显示 Imagine 入口" width="1382" height="418" data-path="images/common/clients/imagine/token-management-imagine.png" />
</Frame>

## 前置条件

* 已 [创建 AIOHub API 令牌](/cn/account/create-token)
* 账号余额为正
* 令牌分组包含 `openai`、`codex` 或 `codex-passthrough`（任一即可调用 `gpt-image-2`）

## 配置方法

| 配置项       | 值                           |
| --------- | --------------------------- |
| API URL   | `https://api.aiohub.org`    |
| API Key   | 你的 `sk-` 令牌                 |
| API 接口    | Images API（`/v1/images`）    |
| Codex CLI | `codex*` 分组开启；`openai` 分组关闭 |
| 模型 ID     | `gpt-image-2`               |
| Timeout   | 360-600 秒                   |

<Note>
  **Codex CLI 开关取决于令牌分组：**

  * 令牌属于 `codex` 或 `codex-passthrough` 分组 → 开启
  * 令牌属于 `openai` 分组 → 关闭

  不确定分组？在控制台 **令牌** 页查看令牌详情。
</Note>

<Frame>
  <img src="https://mintcdn.com/qyhfrankgmailcom/4qHxe2G9W8j3rdqH/images/common/clients/imagine/settings.png?fit=max&auto=format&n=4qHxe2G9W8j3rdqH&q=85&s=404f39417f8394d77b3b79eba20e48ae" alt="Imagine 设置页，API URL 为 https://api.aiohub.org，API 接口为 Images API，模型 ID 为 gpt-image-2" width="902" height="956" data-path="images/common/clients/imagine/settings.png" />
</Frame>

<Steps>
  <Step title="打开 Imagine">
    访问 [https://imagine.aiohub.org/](https://imagine.aiohub.org/)，或从控制台令牌管理页点击 **Imagine** 快捷入口。
  </Step>

  <Step title="填写 API URL 和 API Key">
    点击右上角 **设置**，API URL 填 `https://api.aiohub.org`，API Key 填完整的 `sk-` 令牌值。不要在 URL 后追加请求路径，客户端会自动拼接。
  </Step>

  <Step title="选择 API 接口和模型">
    **API 接口** 选择 **Images API（`/v1/images`）**，**模型 ID** 填 `gpt-image-2`。若模型列表中没有该模型，先在控制台为令牌加入对应分组。
  </Step>

  <Step title="设置 Codex CLI 开关">
    <Tabs>
      <Tab title="codex / codex-passthrough 分组">
        打开 **Codex CLI** 开关。`codex*` 分组通过 Codex 渠道路由请求，需要开启此开关。
      </Tab>

      <Tab title="openai 分组">
        保持 **Codex CLI** 关闭（默认状态）。`openai` 分组走标准 OpenAI Images 路径，无需开启。
      </Tab>
    </Tabs>
  </Step>

  <Step title="生成或编辑图片">
    文生图：输入提示词，选择尺寸、质量和输出格式。图片编辑：上传参考图，描述你希望完成的修改。
  </Step>
</Steps>

## 使用注意

* 设置和历史存储在浏览器本地，共用设备建议使用独立令牌。
* 用量和费用记录在控制台日志，与 SDK 调用一致。
* 图片生成耗时较长，大图或高质量任务建议先将超时调至 360-600 秒。
* 浏览器未显示结果时，先在控制台日志确认请求是否已完成，再重试。

## 常见问题

<AccordionGroup>
  <Accordion title="401 或 403 错误">
    确认令牌有效、已启用，且填写了完整的 `sk-` 值。如果返回 403，检查令牌是否包含 `openai` 或 `codex*` 分组，并确认 **Codex CLI** 开关与令牌分组匹配（`codex*` 分组开启，`openai` 分组关闭）。
  </Accordion>

  <Accordion title="模型不存在">
    用同一令牌请求 `/v1/models`，或查看控制台模型列表，确认当前令牌可见 `gpt-image-2`。
  </Accordion>

  <Accordion title="路径不存在">
    API URL 应填 `https://api.aiohub.org`，不要追加 `/v1/images/generations` 等路径。选择 Images API 后客户端自动拼接。
  </Accordion>

  <Accordion title="生成超时">
    将超时调至 360-600 秒，或降低图片尺寸和质量后重试。
  </Accordion>

  <Accordion title="不确定该开还是关 Codex CLI">
    在控制台查看令牌详情中的分组字段。包含 `codex` 或 `codex-passthrough` → 开启；包含 `openai` → 关闭。若令牌同时包含两类分组，任选一种配置即可。
  </Accordion>
</AccordionGroup>