*更新日期: 2026-08-29*

# 生图

**POST** `/v1/images/generations`

默认同步接口：网关会等到生成完成或超时（最多 **5 分钟**）。超时 `504` + `gateway_timeout`，不扣费。图生图也可走兼容路径 `POST /v1/images/edits`（见下方）。

同步成功/失败都会写入平台任务记录，**门户与管理端任务列表可见**（`img_…`）。同步成功响应体仍是 OpenAI 风格的 `{ created, data, usage }`，**不含**对外 `id`。

传 `async: true` 时，接口立即返回**对外 task id**（HTTP 200），用 `GET /v1/tasks/{id}` 轮询完成结果；不传或传 `false` 时走同步路径，直接返回最终图片。`GET /v1/images/{id}` 是同一查询的别名。

## 请求

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id（`GET /v1/models?capability=image`） |
| `prompt` | string | 是 | 文本提示 |
| `n` | int ≥ 1 | 否 | 请求张数；**计费按实际返回张数**；部分模型仅支持 1 |
| `size` | string | 否 | 像素如 `1024x1024`，或档位如 `2K`（Seedream）；以该模型实际支持为准 |
| `aspect_ratio` | string | 否 | 如 `16:9` / `1:1`；Gemini / 部分模型优先用；也可用 `aspectRatio` |
| `quality` | string | 否 | 如 `low` / `high` / `hd`；GPT-Image 等模型生效 |
| `background` | `auto` \| `opaque` \| `transparent` | 否 | GPT-Image 背景透明度 |
| `moderation` | `auto` \| `low` | 否 | GPT-Image 内容审核强度 |
| `output_format` | `png` \| `jpeg` | 否 | Seedream 输出编码 |
| `watermark` | boolean | 否 | Seedream「AI 生成」水印 |
| `optimize_prompt_options` | object | 否 | Seedream 提示词优化，`{ "mode": "standard" \| "fast" }` |
| `sequential_image_generation` | `auto` \| `disabled` | 否 | Seedream 组图 |
| `sequential_image_generation_options` | object | 否 | `{ "max_images": number }`，组图上限 |
| `async` | boolean | 否 | `true` 时立即返回 task id，走轮询；缺省或 `false` 走同步 |
| `response_format` | `url` \| `b64_json` | 否 | 默认 `url`。也可用 `responseFormat` |
| `image` / `images` | string \| file \| string[] | 否 | 图生图参考。输入形态与别名见下方 |

> **一套契约，多厂商差异由平台处理**
>
> 对外始终是 OpenAI 风格的 `/v1/images/generations`。不同模型族（Seedream、GPT-Image、Gemini / Banana、Grok 等）的差异由平台统一处理；客户端只需按本文档字段调用，不要照搬各模型自有文档。未声明支持的字段会被忽略或拒绝。

### 常见模型族参数习惯

| 系列 | `size` 习惯 | 参考图 |
|------|-------------|--------|
| Seedream | `2K` / `2048x2048` 等档位或像素 | `image` / `images` |
| ChatGPT / GPT-Image / DALL·E | `1024x1024`、`1536x1024`、`auto` | `image`（部分模型支持多图） |
| Gemini / Imagen / Banana | 可用 `aspect_ratio`，或用像素 `size` 推导比例 | `image` / `images` |
| Grok 生图 | 随模型而定；常见像素尺寸 | 视该模型是否支持 |

换模型时只改 `model`（及该模型文档/列表里给出的可选参数），路径与鉴权不变。

```bash
curl https://tokenmei.com/v1/images/generations \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "一只橙猫走在雨夜霓虹街头",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

```javascript
const image = await client.images.generate({
  model: "YOUR_IMAGE_MODEL",
  prompt: "一只橙猫走在雨夜霓虹街头",
  n: 1,
  size: "1024x1024",
  response_format: "url",
});
console.log(image.data[0].url);
console.log(image.usage);
```

```python
image = client.images.generate(
    model="YOUR_IMAGE_MODEL",
    prompt="一只橙猫走在雨夜霓虹街头",
    n=1,
    size="1024x1024",
    response_format="url",
)
print(image.data[0].url)
print(image.usage)
```

```go
image, _ := client.Images.Generate(context.TODO(), openai.ImageGenerateParams{
	Model:          "YOUR_IMAGE_MODEL",
	Prompt:         "一只橙猫走在雨夜霓虹街头",
	N:              openai.Int(1),
	Size:           openai.ImageGenerateParamsSize1024x1024,
	ResponseFormat: openai.ImageGenerateParamsResponseFormatURL,
})
fmt.Println(image.Data[0].URL)
fmt.Println(image.Usage)
```

```php
$image = $client->images()->create([
    "model" => "YOUR_IMAGE_MODEL",
    "prompt" => "一只橙猫走在雨夜霓虹街头",
    "n" => 1,
    "size" => "1024x1024",
    "response_format" => "url",
]);
echo $image->data[0]->url, PHP_EOL;
print_r($image->usage);
```

```java
ImagesResponse image = client.images().generate(
    ImageGenerateParams.builder()
        .model("YOUR_IMAGE_MODEL")
        .prompt("一只橙猫走在雨夜霓虹街头")
        .n(1L)
        .size(ImageGenerateParams.Size._1024X1024)
        .responseFormat(ImageGenerateParams.ResponseFormat.URL)
        .build()
);
System.out.println(image.data().get(0).url());
System.out.println(image.usage());
```

```csharp
var image = client.GetImageClient("YOUR_IMAGE_MODEL").GenerateImage(
    "一只橙猫走在雨夜霓虹街头",
    new ImageGenerationOptions { Size = GeneratedImageSize.W1024xH1024 }
);
Console.WriteLine(image.Value.ImageUri);
```

### 参考图输入形态

`image` / `images` 及下方别名，在 `generations` 与 `edits` 上支持三种入参（多值时取**第一张**）。文件与 base64 会先转存为平台公网 URL，再交给模型服务。

| 形态 | 怎么传 | 说明 |
|------|--------|------|
| **公网 URL** | JSON 字符串，如 `"https://cdn.example.com/ref.png"` | `http://` / `https://` 可直接用；该地址需可公网访问 |
| **Base64** | `data:image/png;base64,...`，或足够长且可识别为图片的裸 base64 | 网关解码后转存；不要传本机文件路径冒充字符串 |
| **文件流** | `multipart/form-data` 字段（如 `-F image=@ref.png`） | 与 OpenAI `images.edit` 常见写法一致；单文件上限约 10MB |

**不支持**客户端本机路径（如 `/Users/.../a.png`、`./ref.png`、`C:\...`）。服务端不会读你的磁盘；请改成上传文件、公网 URL 或 base64。

字段名别名（写全，含 camelCase / snake_case）：`image`、`image_url`、`imageUrl`、`images`、`image_urls`、`imageUrls`、`input_image`、`inputImage`、`input_reference`、`inputReference`、`reference_image`、`referenceImage`、`reference_images`、`referenceImages`、`first_frame`、`firstFrame`、`first_frame_image`、`firstFrameImage`、`init_image`、`initImage`、`file`。`response_format` 也可用 `responseFormat`。

公网 URL 示例：

```json
{
  "model": "YOUR_IMAGE_MODEL",
  "prompt": "改成水墨风",
  "image": "https://cdn.example.com/ref.png"
}
```

Base64（data URL）示例：

```json
{
  "model": "YOUR_IMAGE_MODEL",
  "prompt": "改成水墨风",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
```

Multipart 文件示例（`generations` 与 `edits` 均可）：

```bash
curl $BASE/v1/images/generations \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -F model=YOUR_IMAGE_MODEL \
  -F prompt="改成水墨风" \
  -F image=@ref.png \
  -F response_format=url
```

SDK 若不允许额外字段，用 HTTP 调同一路径，或改用下方的 edits。

**POST** `/v1/images/edits`

OpenAI 兼容图编辑入口。与 `images/generations` + `image` **同一下游链路**；差别是 **`image` 必填**。接受 JSON 或 `multipart/form-data`（官方 SDK `images.edit` 常见写法）。输入形态同上表（URL / base64 / 文件流）。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id（平台必填；OpenAI 官方有时可省略） |
| `prompt` | string | 是 | 编辑说明 |
| `image` | string \| file | 是 | 源图；形态与别名见「参考图输入形态」 |
| `mask` | string \| file | 否 | 兼容 OpenAI；同样支持 URL / base64 / 文件；**可传但不参与生成** |
| `n` | int ≥ 1 | 否 | 同 generations |
| `size` | string | 否 | 同 generations |
| `response_format` | `url` \| `b64_json` | 否 | 同 generations；也可用 `responseFormat` |
| `async` | boolean | 否 | 同 generations |

```bash
curl $BASE/v1/images/edits \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -F model=YOUR_IMAGE_MODEL \
  -F prompt="改成水墨风" \
  -F image=@ref.png
```

响应形状与 `POST /v1/images/generations` 相同。

## 响应

```json
{
  "created": 1710000000,
  "data": [
    { "url": "https://cdn.example.com/a/xxx.png", "revised_prompt": null }
  ],
  "usage": {
    "images_generated": 1,
    "cost": { "amount": "0.2200", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `created` | int | Unix 秒 |
| `data` | array | 每项一张图；计费按 `data.length`，不按请求里的 `n` |
| `data[].url` | string | `response_format=url` 时为平台转存后的稳定地址，不是临时链接 |
| `data[].b64_json` | string | `response_format=b64_json` 时直接给 base64，可跳过转存 |
| `data[].revised_prompt` | null | 固定为 `null` |
| `usage.images_generated` | int | 实际张数 |
| `usage.cost` | object | 可选，同对话的对外售价 |

`b64_json` 单项形如：

```json
{ "b64_json": "...", "revised_prompt": null }
```

> **计费张数**
>
> 按 `data.length` 扣，不按请求里的 `n`。若一张都没返回，按 1 张计价前会先当失败（`upstream_error`）。失败整单不扣。

## 任务轮询（`async: true`）

`async: true` 时，`POST /v1/images/generations` 立即返回 task：

```json
{
  "id": "img_a1b2c3d4e5f6",
  "object": "image",
  "model": "YOUR_IMAGE_MODEL",
  "status": "queued",
  "progress": 0,
  "created_at": 1710000000,
  "completed_at": null,
  "error": null
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 前缀 `img_`，用于轮询 |
| `object` | string | 固定 `image` |
| `model` | string | 对外模型 id |
| `status` | string | `queued` / `in_progress` / `completed` / `failed` |
| `progress` | int | 0–100 |
| `created_at` | int | Unix 秒 |
| `completed_at` | int \| null | 未完成时为 `null` |
| `error` | string \| null | 成功为 `null`，失败为说明字符串 |
| `data` | array | 仅 `completed` 时出现，形状与同步生图一致 |

用这个 `id` 轮询（推荐统一路径）：

**GET** `/v1/tasks/{id}`

`GET /v1/images/{id}` 返回同一份 JSON。

| 状态 | 说明 |
|------|------|
| `queued` / `in_progress` | 还没完成，不返回 `data` |
| `completed` | 成功后返回 `data:[{ "url": "...", "revised_prompt": null }, …]`（可多张） |
| `failed` | 失败原因在 `error` |

同步完成的任务若你知道 `img_…` public id（例如从门户任务列表复制），也可用 `GET /v1/tasks/{id}` / `GET /v1/images/{id}` 查询；`data` 含全部转存后的图片。异步 worker 路径当前仍按单结果 URL 落一张。完整约定见[任务查询](/docs/tasks)。
