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

# ChatIMG 图片生成 API

> 用代码批量生成、编辑图片：获取 Token、发起生成、轮询结果、查询计价

<Card title="ChatIMG 开放 API 面板" icon="key" href="https://chatimg.ai/user/api">
  登录后在这里获取 Token、查看积分余额与实时计价：[https://chatimg.ai/user/api](https://chatimg.ai/user/api)
</Card>

## 一、获取 API Token

ChatIMG 与 BibiGPT 共用同一套账号体系，**API Token 也是同一个**——登录 ChatIMG 后访问
[chatimg.ai/user/api](https://chatimg.ai/user/api) 即可获取（若你已在 BibiGPT
用过开放 API，那个 Token 可以直接用）。

所有端点统一用 HTTP header 认证：

```shell theme={null}
curl --header 'Authorization: Bearer <api_token>'
```

<Note>
  API 调用消耗的积分与网页端**共用同一个余额**，不需要单独开通或充值。
  余额可在 [chatimg.ai/user/api](https://chatimg.ai/user/api) 查看，
  充值在 [chatimg.ai/pricing](https://chatimg.ai/pricing)。
</Note>

## 二、调用流程

图片生成是**异步**的：先发起任务，再按源图 URL 轮询结果。

### 1. 发起生成 [`POST /v1/generateImage`](https://docs.bibigpt.co/api-reference/open/generate-or-edit-an-image-with-ai-chatimgai)

```shell theme={null}
curl -X POST https://api.bibigpt.co/api/v1/generateImage \
  -H "Authorization: Bearer $CHATIMG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/photo.jpg",
    "prompt": "ghibli style",
    "model": "nanobanana-2-lite"
  }'
```

| 参数         | 必填 | 说明                                                      |
| ---------- | -- | ------------------------------------------------------- |
| `imageUrl` | 是  | 源图地址，支持 http(s) URL 与 base64（可带或不带 `data:image/...` 前缀） |
| `prompt`   | 否  | 想要的效果描述，默认 `ghibli`                                     |
| `model`    | 否  | 模型标识，默认 `nanobanana-2-lite`，取值见下方计价表                    |

返回中的 `taskId` 用于追踪，`costCredits` 是本次扣除的积分，`balanceRemaining` 是扣费后余额。

<Note>
  生成失败会**自动退回积分**，无需自行对账。
</Note>

### 2. 轮询结果 [`GET /v1/imageStatus`](https://docs.bibigpt.co/api-reference/open/get-the-status-of-an-image-generation-task)

用**同一个 `imageUrl`** 作为键查询，只读且不计费：

```shell theme={null}
curl "https://api.bibigpt.co/api/v1/imageStatus?imageUrl=https://example.com/photo.jpg" \
  -H "Authorization: Bearer $CHATIMG_API_TOKEN"
```

`status` 变为 `completed` 时，`generatedImageUrl` 即为成品图片地址。

不同模型耗时差异较大（轻量模型数秒，GPT Image 2 约 1~~2 分钟），建议\*\*每 3~~5 秒轮询一次\*\*并设置合理超时。

### 3. 查询计价 [`GET /v1/imagePricing`](https://docs.bibigpt.co/api-reference/open/list-available-image-models-and-their-credits-pricing)

无需认证，返回各模型每张图的积分单价与充值包信息，方便脚本里做预算控制：

```shell theme={null}
curl https://api.bibigpt.co/api/v1/imagePricing
```

## 三、模型与计价

每张图消耗的积分（以 `/v1/imagePricing` 实时返回为准）：

| 模型                  | 积分/张 | 模型               | 积分/张 |
| ------------------- | ---- | ---------------- | ---- |
| `z-image-turbo`     | 5    | `nanobanana-2`   | 20   |
| `qwen`              | 8    | `openai`         | 25   |
| `gemini`            | 10   | `flux-2-flex`    | 25   |
| `flux`              | 12   | `grok`           | 30   |
| `nanobanana-2-lite` | 12   | `nanobanana-pro` | 30   |
| `seedream`          | 15   | `gpt-image-2`    | 50   |

## 四、完整示例

发起生成后轮询到结果的最小可用脚本：

```bash theme={null}
TOKEN="$CHATIMG_API_TOKEN"
SRC="https://example.com/photo.jpg"

curl -s -X POST https://api.bibigpt.co/api/v1/generateImage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"imageUrl\":\"$SRC\",\"prompt\":\"ghibli style\",\"model\":\"nanobanana-2-lite\"}"

# 轮询直到 completed
for i in $(seq 1 60); do
  sleep 3
  RESP=$(curl -s "https://api.bibigpt.co/api/v1/imageStatus?imageUrl=$SRC" \
    -H "Authorization: Bearer $TOKEN")
  echo "$RESP" | grep -q '"status":"completed"' && echo "$RESP" && break
done
```

## 常见问题

<AccordionGroup>
  <Accordion title="返回 401 怎么办？">
    Token 缺失或已失效。检查 header 是否为 `Authorization: Bearer <token>`，
    并在 [chatimg.ai/user/api](https://chatimg.ai/user/api) 确认当前 Token；
    若曾点过「重置」，旧 Token 会立即失效，需要更新脚本。
  </Accordion>

  <Accordion title="返回 400 invalid_image_url？">
    `imageUrl` 必须是可公开访问的 http(s) 地址或 base64 数据，
    浏览器本地预览地址（`blob:` 开头）无法被服务端读取。此类请求不会扣除积分。
  </Accordion>

  <Accordion title="积分不足怎么办？">
    在 [chatimg.ai/pricing](https://chatimg.ai/pricing) 充值积分包（永不过期），
    或订阅套餐获得每月额度。也可以改用单价更低的模型（如 `z-image-turbo` 每张 5 积分）。
  </Accordion>

  <Accordion title="轮询一直是 unknown？">
    说明该 `imageUrl` 没有对应的生成记录——通常是查询用的 URL 与发起时传的不完全一致。
    两者必须**逐字符相同**（含 query string）。
  </Accordion>
</AccordionGroup>