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

# 生成图片或视频

> 使用 AI 模型生成图片或视频

```
POST /api/generate/v2
```

提交图片或视频生成请求。生成异步进行 — 使用[状态查询端点](#查询生成状态)轮询完成情况。同一端点同时支持图片模型（GPT Image 2、Nanobanana、Seedream、Midjourney 等）和视频模型（Seedance 2.0、Veo 3.1、Grok Video 等），通过 `modelId` 选择。

## 请求

### 请求头

| Header        | 值                               |
| ------------- | ------------------------------- |
| Authorization | `Bearer meigen_sk_YOUR_API_KEY` |
| Content-Type  | `application/json`              |

### 请求体参数

<ParamField body="prompt" type="string" required>
  要生成的图片的文本描述。
</ParamField>

<ParamField body="modelId" type="string">
  用于生成的模型。不传则使用平台当前默认模型（可能随平台配置变化）。

  **[模型列表](/zh/api-reference/endpoint/models)是模型 ID 的权威来源。** 模型会不断上新与下线，请在运行时动态解析 ID，不要在自己这边硬编码一份模型清单。该端点返回的所有模型都可用于本端点，API Token 调用同样不受限。

  常用取值：图片 `gpt-image-2`、`nanobanana-2`、`midjourney-v8.1`；视频 `seedance-2-0`、`veo-3.1`。

  > `rhart-1.5`（GPT image 1.5）已于 2026-04-22 下线，请改用 `gpt-image-2`。`midjourney-v7` 已于 2026-05-09 由 `midjourney-v8.1` 接替（出于向后兼容仍接受老 ID 调用）。
</ParamField>

<ParamField body="aspectRatio" type="string" default="auto">
  生成媒体的宽高比。

  * 默认 `auto`（推荐）：为你自动挑选合适的比例。
  * 也可显式指定——必须是 [模型列表](/zh/api-reference/endpoint/models) 返回的 `supported_ratios` 之一。常见图片比例：`1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `21:9`, `5:4`, `4:5`。
  * Seedance 2.0 还接受特殊值 `adaptive`，按 `referenceImages` 或 `referenceVideo` 的尺寸自适应。仅在提供其中之一时才使用 `adaptive`；无参考时的行为未定义。
  * **Seedance 2.0 上不传 `aspectRatio`（或传了无法识别的取值）都会解析为 `adaptive`。** 纯文生视频没有可供自适应的参考，因此在不带参考图/参考视频生成时，请务必显式指定比例。

  最终采用的比例会同时在本端点的响应和状态端点的 `aspectRatio` 字段返回。
</ParamField>

<ParamField body="resolution" type="string">
  输出分辨率。可用性取决于模型。不传则使用所选模型的默认分辨率。

  可选值取决于模型：图片模型用 `1K` / `2K` / `3K` / `4K`；视频模型用 `480p` / `720p` / `1080p` / `4k`（视频侧的 k 是小写）。并非每个视频模型都支持全部取值 —— `4k` 仅 Seedance 2.0 的 `pro` 档和 Veo 3.1 支持，Seedance 上的 `1080p` 同样需要 `pro` 档。各模型实际支持的分辨率和默认值详见[模型对比](/zh/features/models)。
</ParamField>

<ParamField body="quality" type="string" default="low">
  仅用于 GPT Image 2.0。可选 `low` / `medium` / `high`。其他模型会忽略该参数。
</ParamField>

<ParamField body="referenceImages" type="string[]">
  参考图数组。每一项必须是可公开访问的 HTTP(S) URL，或形如 `data:image/png;base64,...` 的内联 base64 数据。本地文件路径（如 `C:/Users/...`）与 `file://` URI 会被拒绝，返回 `400` / `invalid_reference_url`。

  最大数量按模型不同——请始终以[模型列表](/zh/api-reference/endpoint/models)返回的 `max_reference_images` 为准。撰写时的实况：

  | 上限 | 模型                                                                                  |
  | -- | ----------------------------------------------------------------------------------- |
  | 10 | Seedream 5.0 Pro                                                                    |
  | 5  | GPT Image 2.0、Nanobanana 2、Nanobanana Pro、Seedream 5.0 Lite、Seedream 4.5            |
  | 3  | Grok Imagine Quality                                                                |
  | 2  | Seedance 2.0、Veo 3.1                                                                |
  | 1  | Midjourney V8.1、Happyhorse 1.1、Agnes Image 2.1 Flash、Agnes Video 2.0、Grok Video 1.5 |
  | 0  | Flux 2 Klein、Z Image Turbo                                                          |
</ParamField>

<ParamField body="niji7Options" type="object">
  Midjourney V8.1 高级参数。对其他模型无效。（字段名沿用历史命名，向后兼容。）

  | 字段      | 类型      | 默认值   | 范围        | 说明                   |
  | ------- | ------- | ----- | --------- | -------------------- |
  | stylize | number  | 100   | 0-1000    |                      |
  | chaos   | number  | 5     | 0-100     |                      |
  | raw     | boolean | false | —         |                      |
  | iw      | number  | 1     | 0-2       |                      |
  | sref    | string  | —     | URL 或文本   |                      |
  | sw      | number  | 100   | 0-1000    |                      |
  | quality | string  | `4`   | `1` 或 `4` | 默认 High（4 倍算力，不额外计费） |
</ParamField>

<ParamField body="referenceType" type="string" default="content">
  仅用于 Midjourney V8.1。参考图片的解读方式。

  * `content` — 用作主题素材参考
  * `style` — 仅提取视觉风格
</ParamField>

<ParamField body="duration" type="number">
  视频时长(秒)。不传则按该模型的默认时长出片。

  | 模型              | 可选值     | 默认 |
  | --------------- | ------- | -- |
  | Seedance 2.0    | 4-15    | 4  |
  | Veo 3.1         | 仅 4、6、8 | 4  |
  | Grok Video 1.5  | 4-15    | 4  |
  | Happyhorse 1.1  | 3-15    | 4  |
  | Agnes Video 2.0 | 仅 5(固定) | 5  |

  **调用视频模型时请始终显式传 `duration`。** 上表"默认"列只是不传该字段时实际出片的时长,计费并不跟着它走:漏传 `duration` 时,费用会回落到该模型的名义单价,而不是按出片时长计算,因而可能明显高于显式写清时长的同一请求。Veo 3.1 的落差最大 —— 漏传时按该模型单次计费的最高价扣,显式传 `duration: 4` 则按 4 秒档计费。

  无论怎么传,实际扣除的积分都会在响应的 `creditsUsed` 中返回,请以该字段为准,不要自行推算。
</ParamField>

<ParamField body="tier" type="string">
  支持多档位模型的画质档位。

  * Seedance 2.0:`mini`(默认)、`fast` 或 `pro`
  * Veo 3.1:`fast`(默认)或 `pro`

  档位越高画质越好,每秒单价也越高。不传则使用该模型自身的默认档 —— 注意 Seedance 2.0 的默认档是最便宜的 `mini`。完整价格矩阵见[模型](/zh/features/models)。
</ParamField>

<ParamField body="referenceVideo" type="string">
  仅用于 Seedance 2.0。用于"视频续写"模式的参考视频 URL。必须是可公开访问的 HTTPS URL（一般来自之前生成结果的 `videoUrl` 字段）。

  传该字段时计费走"有参考视频"档（Mini 480p 7、720p 13；Fast 480p 8、720p 14；Pro 720p 16、1080p 28 积分/秒），并应用最低计费秒数（详见[模型](/zh/features/models)）。
</ParamField>

<ParamField body="referenceVideoDuration" type="number">
  仅用于 Seedance 2.0 + 参考视频续写。参考视频本身的时长（秒），与 `duration` 一起用于确定实际计费秒数（详见[模型](/zh/features/models) 定价表）。**传 `referenceVideo` 时必须同时传该字段**——漏传会按 0 处理，可能导致计费明显低于预期且续写效果异常。
</ParamField>

## 响应

<ResponseField name="success" type="boolean">
  请求是否被接受。
</ResponseField>

<ResponseField name="generationId" type="string">
  生成请求的唯一 ID。用此 ID 轮询状态。
</ResponseField>

<ResponseField name="status" type="string">
  初始状态，始终为 `"processing"`。
</ResponseField>

<ResponseField name="creditsUsed" type="number">
  本次生成扣除的积分数。
</ResponseField>

<ResponseField name="modelId" type="string">
  本次生成使用的模型。
</ResponseField>

<ResponseField name="aspectRatio" type="string">
  本次生成最终采用的宽高比。默认 `auto` 会选择合适的比例，提交时即在此返回 —— 无需等第一次轮询，可用于在界面上按正确比例预留占位。
</ResponseField>

<ResponseField name="credits" type="object">
  扣除后更新的积分余额。

  | 字段        | 类型      | 描述         |
  | --------- | ------- | ---------- |
  | daily     | number  | 剩余每日免费积分   |
  | purchased | number  | 剩余购买积分     |
  | unlimited | boolean | 用户是否拥有无限积分 |
</ResponseField>

```json theme={null}
{
  "success": true,
  "generationId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "creditsUsed": 10,
  "modelId": "gpt-image-2",
  "aspectRatio": "1:1",
  "credits": {
    "daily": 2,
    "purchased": 50,
    "unlimited": false
  }
}
```

## 查询生成状态

```
GET /api/generate/v2/status/:generationId
```

轮询此端点以检查图片是否就绪。

### 响应（处理中）

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "imageUrl": null,
  "imageUrls": null,
  "videoUrl": null,
  "mediaType": "image",
  "error": null,
  "aspectRatio": "16:9"
}
```

### 响应（图片已完成）

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "imageUrl": "https://images.meigen.ai/generations/xxx.png",
  "imageUrls": ["https://images.meigen.ai/generations/xxx.png"],
  "videoUrl": null,
  "mediaType": "image",
  "error": null,
  "aspectRatio": "16:9"
}
```

### 响应（视频已完成）

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "imageUrl": null,
  "imageUrls": null,
  "videoUrl": "https://images.meigen.ai/generations/xxx.mp4",
  "mediaType": "video",
  "error": null,
  "aspectRatio": "16:9"
}
```

<Note>
  * **`aspectRatio`** 是该次生成最终采用的比例（如果你传了 `auto`，这里是实际落地的值）。
  * **`mediaType`** 取值 `image` 或 `video`。视频生成时 `imageUrl/imageUrls` 为 `null`，反之亦然。
  * Midjourney V8.1 每次返回 4 张候选图片，`imageUrls` 包含全部候选，`imageUrl` 始终指向第一张。其他图片模型返回单张。
</Note>

### 响应（失败）

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "creditsStatus": "refunded",
  "imageUrl": null,
  "imageUrls": null,
  "videoUrl": null,
  "mediaType": "image",
  "error": "Content policy violation",
  "aspectRatio": "16:9"
}
```

生成失败时，积分会自动退还。可通过 `creditsStatus` 确认退款是否落地：`pending`（已预扣，结果未定）、`confirmed`（已实际扣费）、`refunded`（已退回余额）。

## 示例

### 基本生成

省略 `modelId` 即使用默认模型（`gpt-image-2`）：

```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist logo of a mountain, vector style, blue gradient",
    "aspectRatio": "1:1"
  }'
```

### 带参考图片

```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Similar style landscape but with autumn colors",
    "modelId": "seedream-5.0-lite",
    "aspectRatio": "16:9",
    "referenceImages": ["https://example.com/reference.jpg"]
  }'
```

### Midjourney V8.1 风格参考

```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a warrior princess in an enchanted forest",
    "modelId": "midjourney-v8.1",
    "aspectRatio": "3:4",
    "referenceImages": ["https://example.com/style-ref.jpg"],
    "referenceType": "style",
    "niji7Options": {
      "stylize": 300,
      "sw": 500
    }
  }'
```

### Seedance 视频生成（文生视频）

```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A majestic eagle soaring over a misty mountain valley at sunrise, cinematic camera movement",
    "modelId": "seedance-2-0",
    "aspectRatio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'
```

计费：这里没有传 `tier`，因此走 Seedance 的默认 **Mini** 档 —— 720p 单价 16 积分/秒 × 5 秒 = **80 积分**。改传 `"tier": "fast"`（20 积分/秒 → 100 积分）或 `"pro"` 会更贵，详见[模型](/zh/features/models)。

### Seedance 视频续写（参考视频）

```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Continue the scene as the eagle dives toward a river below",
    "modelId": "seedance-2-0",
    "aspectRatio": "adaptive",
    "resolution": "480p",
    "duration": 5,
    "referenceVideo": "https://images.meigen.ai/generations/eagle-clip.mp4",
    "referenceVideoDuration": 3
  }'
```

计费：这里没有传 `tier`，因此走默认 **Mini** 档 —— 480p 带参考视频单价 7 积分/秒，计费秒数 = max(3 + 5, 9) = 9 秒，共 **63 积分**。同样的请求走 `fast` 档则是 8 × 9 = 72 积分。输出视频长度 = `duration` = 5 秒。

### 让系统自动选比例（Auto）

省略 `aspectRatio` 或显式传 `"auto"`，由 MeiGen 自动挑选合适比例：

```bash theme={null}
curl -X POST https://www.meigen.ai/api/generate/v2 \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Blog hero banner image, abstract gradient background with code snippets"
  }'
```

实际采用的比例会通过 `aspectRatio` 字段返回 —— 本次请求的响应和状态端点里都有。