> ## 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.

# 生成图片或视频

> 提交图片或视频任务，设置模型参数、参考素材和幂等重试。

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

提交图片或视频生成请求。生成异步进行 — 使用[状态查询端点](#查询生成状态)轮询完成情况。同一端点同时支持图片模型（GPT Image 2.5、GPT Image 2、Nanobanana、Seedream、Midjourney 等）和视频模型（Seedance 2.5、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>
  GPT Image 2 与 2.5 的长提示词会自动压缩以适配模型限制，请明确写出关键要求和需要保留的内容。

  要生成的图片或视频的文本描述。要引用已创建的角色，在文本中内嵌 `[character:<uuid>]` ——例如 `"[character:550e8400-e29b-41d4-a716-446655440000] standing in a neon-lit alley, cinematic lighting"`。每次生成最多引用 3 个角色。

  支持范围：所有接受参考图的图片模型（Flux 2 Klein 除外）+ 视频侧 **Seedance 2.5 / 2.0**。角色图片与用户上传图片共用内容参考图预算。模型不支持、角色不存在或无权访问、引用数超限均返回 `400`（`characters_not_supported`、`character_not_found`、`too_many_characters`）；部分角色需要更高的 `tier`（`character_tier_required`）。

  **素材标记** —— 在提示词里内嵌 `[image1]`、`[video1]`、`[audio1]`，用来指明某句话针对哪个参考素材：*"沿用 \[image1] 的调色，接续 \[video1] 的运动，并按 \[audio1] 的节奏配乐"*。编号**从 1 开始、按素材类型各自计数**，顺序与本请求体里 `referenceImages` / `referenceVideos` / `referenceAudios` 的数组顺序一致 —— `[video2]` 指 `referenceVideos` 的第二项，而不是全部素材里的第二个。请求抵达模型前，两类标记的处理方式不同：

  * **`[videoN]` / `[audioN]`** 会被改写成厂商自己的写法 —— `Video 1`、`Audio 1`；编号超过本次实际提交条数的标记会被**直接删除**，只传了两条视频却写 `[video3]`，那里什么都不会留下。也可以直接写厂商写法 —— `"Video 1"` —— MCP 和 REST 调用方通常这么写。
  * **`[imageN]` 与 `[character:<uuid>]`** 会被展开成一句描述性短语，点名该标记落到的参考图位次 —— `[image1]` 变成 *"the subject in reference image 1"*，角色标记变成 *"the character in reference image 2"*。参考图在送进模型前可能被合并或重排，因此短语里的位次是模型实际看到的那个，不一定等于 `N`。编号超出你实际提交图片数量的 `[imageN]` **会原样留在提示词里**，不会被删除 —— 所以图片编号不要超过你实际传的张数。

  改写只发生在发给模型的那一份上。落库的提示词保留你写的原始标记，重新打开编辑器仍能看到当初的 mention。
</ParamField>

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

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

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

  Nanobanana 2.1 使用 `modelId: "nanobanana-2.1"`，`resolution: "2K"` 为 5 积分，`"4K"` 为 8 积分。它与 `nanobanana-2` 是独立模型，后者仍可使用，两种分辨率均为 5 积分。

  > `rhart-1.5`（GPT image 1.5）已于 2026-04-22 下线，请改用 `gpt-image-2`。`midjourney-v7` 已于 2026-05-09 由 `midjourney-v8.1` 接替（2026-09-02 原地升级为 V8.2，ID 不变）（出于向后兼容仍接受老 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.5 和 2.0 还接受 `adaptive`，让输出跟随输入素材；首帧/末帧和 `referenceVideos` 请求使用该值。
  * Seedance 2.5 的文生视频或 `referenceMode: content` 请求如需明确画幅，请传受支持的具体比例。
  * **Seedance 2.0 上不传 `aspectRatio`（或传了无法识别的取值）都会解析为 `adaptive`。** 纯文生视频没有可供自适应的参考，因此不带参考图/参考视频时请显式指定比例。

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

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

  可选值取决于模型：图片模型用 `1K` / `2K` / `3K` / `4K`；视频模型用 `480p` / `720p` / `1080p` / `4k`（视频侧的 k 是小写）。Seedance 2.5 支持 480p / 720p / 1080p；Seedance 2.0 的 `pro` 档增加 1080p / 4k，Veo 3.1 也支持 4k。Seedance 2.0 带 `referenceVideos` 时最高 1080p。完整矩阵见[模型对比](/zh/features/models)。
</ParamField>

<ParamField body="quality" type="string">
  质量选项按模型区分。GPT Image 2.5 支持 `low`（Standard）、`medium`（Medium）、`high`（High）、`xhigh`（Extra High）、`max`（Max）。GPT Image 2 仅支持 `low` / `medium` / `high`。GPT Image 模型省略此字段或传 `auto` 时使用模型配置的默认值（当前为 `low`）。

  Grok Imagine Image 2.0 支持 `low`（Standard，默认）/ `medium`。通过[模型列表](/zh/api-reference/endpoint/models)读取 `extra_config.qualities` 与 `extra_config.pricing`。GPT 不支持的质量值返回 `400` / `unsupported_quality`。
</ParamField>

<ParamField body="modelVariant" type="string">
  仅 GPT Image 2.5 支持：`sunburst`（质量优先，配置默认值）或 `flare`（速度优先）。两者都支持图片生成和参考图编辑，同分辨率、同质量下同价。添加参考图不会自动改变此设置。

  与 `modelId: "gpt-image-2.5"` 一起使用。不要把型号选项名称当作独立模型 ID，也不要为 GPT Image 2 或其他模型传此字段。非法组合返回 `400` / `unsupported_model_variant`。
</ParamField>

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

  <Note>
    **Agnes Video 2.5 Flash —— 图生视频会忽略 `aspectRatio`。**（该模型自 2026-09-22 起暂时下线，
    以下规则在其启用时适用。）该模型的输出比例由首帧图本身
    决定。对托管在 `images.meigen.ai` 上的图片（你在 MeiGen 生成或上传过的），我们会先在
    CDN 边缘把首帧裁到你请求的 `aspectRatio`，因此输出与你选的比例一致；对其他来源
    （外部 URL 或 `data:` base64），图片原样透传，**输出比例跟随你的图片，而不是
    `aspectRatio`**。

    如果外部图片也需要精确的输出比例，请在发送前自行裁到该比例，或改传此前生成产物的
    `imageUrl`（本来就在我们 CDN 上）。
  </Note>

  最大数量按模型不同。图片模型和视频首帧/末帧输入请读[模型列表](/zh/api-reference/endpoint/models)返回的 `max_reference_images`；Seedance 的 `content` 模式改读 `extra_config.maxContentReferenceImages`。撰写时的实况：

  | 上限 | 模型 |
  | - | - |
  | 16 | GPT Image 2.5, GPT Image 2.0 |
  | 14 | Nanobanana 2 / 2.1、Nanobanana Pro |
  | 10 | Seedream 5.0 Pro、Seedream 4.5 |
  | 3 | Grok Imagine Image 2.0 |
  | 2 | Seedance 2.5、Seedance 2.0、Veo 3.1 —— 默认 `frame` 模式（首/尾帧），见下方 `referenceMode` |
  | 1 | Midjourney V8.2、Agnes Image 2.5 Flash、Agnes Video 2.5 Flash、Grok Video 1.5(**必传** —— 仅支持图生视频) |
  | 0 | Flux 2 Klein |

  `content` 模式下，Seedance 2.5 最多接受 30 张图片，Seedance 2.0 最多 9 张；使用角色时，角色解析出的图片也计入同一上限。
</ParamField>

<ParamField body="frameReferenceImages" type="string[]">
  可选的 Seedance 结构化首尾帧输入，顺序为首帧、末帧，最多 2 张。需要同时控制首尾帧与内容参考时，可与 `contentReferenceImages` 一起使用。结构化字段优先于旧的 `referenceImages` / `referenceMode` 组合。
</ParamField>

<ParamField body="contentReferenceImages" type="string[]">
  可选的 Seedance 结构化内容参考图：Seedance 2.5 最多 30 张，Seedance 2.0 最多 9 张。可与 `frameReferenceImages`、`referenceVideos`、`referenceAudios` 和角色引用同时使用。图片、视频、音频是三份互不占用的预算；角色图片计入本图片上限。
</ParamField>

<ParamField body="referenceMode" type="string" default="frame">
  仅用于 Seedance 2.5 和 Seedance 2.0，决定其 Provider 如何解读 `referenceImages`。

  * `frame`（默认）—— 首/尾帧参考，最多 2 张
  * `content` —— 内容参考，不绑定具体帧位置。当前 API 上限请读 `extra_config.maxContentReferenceImages`（Seedance 2.5 为 30，Seedance 2.0 为 9）

  Veo、Grok、Agnes 视频模型不要传此字段：它们的 Provider 不实现内容参考模式，仍按各自的常规帧语义处理。超过受支持的上限会返回 `400`——Seedance `frame` 模式为 `frame_reference_limit`，内容参考或其他模型上限为 `too_many_references`。
</ParamField>

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

  | 字段 | 类型 | 默认值 | 范围 | 说明 |
  | - | - | - | - | - |
  | 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 | |
  | profile | string | — | 字母数字档案码 | Midjourney 个性化档案；可与 `sref` 同时使用 |
  | quality | string | `4` | `1` 或 `4` | 默认 High（4 倍算力，不额外计费） |
</ParamField>

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

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

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

  | 模型 | 可选值 | 默认 |
  | - | - | - |
  | Seedance 2.5 | 4-30 | 4 |
  | Seedance 2.0 | 4-15 | 4 |
  | Veo 3.1 | 仅 4、6、8 | 4 |
  | Grok Video 1.5 | 4-15 | 4 |
  | Agnes Video 2.5 Flash（暂时下线） | 仅 5(固定) | 5 |

  实际扣除的积分始终以响应中的 `creditsUsed` 为准,不要自行推算。
</ParamField>

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

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

  Seedance 2.5 没有档位，请省略该字段。更高档位画质更好、价格也更高；不传则使用模型默认档，Seedance 2.0 默认为 `mini`。完整价格矩阵见[模型](/zh/features/models)。
</ParamField>

<ParamField body="referenceVideos" type="string[]">
  Seedance 2.5 或 Seedance 2.0 续写所用的参考视频数组。每一项都必须是 `https://images.meigen.ai/...` 地址 —— 要么来自此前 MeiGen 生成结果的 `videoUrl`，要么是通过[参考素材上传端点](#上传参考视频与音频)上传的文件。**不接受任意公网 URL**：其他域名一律在扣点前返回 `400` / `invalid_reference_video`。同一个 URL 只能出现一次，重复条目会在扣点前返回 `400` / `invalid_input`，不会被探测和计费两次。

  | 模型 | 数量 | 单条时长 | 合计时长 | 单条大小 | 带参考视频单价 |
  | - | - | - | - | - | - |
  | Seedance 2.5 | 最多 10 条 | 2–30 秒 | ≤30 秒 | ≤200MB | 480p 11 / 720p 24 / 1080p 54 积分/秒 |
  | Seedance 2.0 | 最多 3 条 | 2–15 秒 | ≤15 秒 | ≤50MB | Mini 480p 7 / 720p 13、Fast 480p 8 / 720p 14、Pro 720p 16 / 1080p 28 积分/秒(带参考视频时 Pro 仅限 720p / 1080p) |

  服务端会逐条探测参考视频，以探测到的时长为准；你传的时长只作诊断提示。参考视频或参考音频的探测在预算内没完成时，请求**在扣点前**失败，返回 `503` / `reference_probe_timeout` 且 `retryable: true`：用同一个 `idempotencyKey` 原样重试即可。计费按所有参考视频时长的**总和**：

  `计费秒数 = max(参考视频时长总和 + 输出时长, 最低计费秒数)`

  完整费率和示例见[模型](/zh/features/models)。参考视频、参考音频与内容参考图是三份互不占用的预算。

  **旧字段别名。** 单数形式 `referenceVideo`（字符串）仍然受理，等价于只含一项的 `referenceVideos` 数组，并会长期保留。两者同时传时，`referenceVideo` 必须是 `referenceVideos` 的第一项；其他组合返回 `400` / `invalid_input`。
</ParamField>

<ParamField body="referenceAudios" type="string[]">
  Seedance 2.5 或 Seedance 2.0 的参考音频数组。每一项都必须是通过[参考素材上传端点](#上传参考视频与音频)得到的 `https://images.meigen.ai/...` 地址，格式为 **wav** 或 **mp3**，单条不超过 **15MB**。**不接受任意公网 URL**：其他域名一律在扣点前返回 `400` / `invalid_reference_audio`。格式按文件自身字节校验，不看扩展名或 `Content-Type`。

  | 模型 | 数量 | 单条时长 | 合计时长 | 纯音频请求 |
  | - | - | - | - | - |
  | Seedance 2.5 | 最多 10 条 | 2–30 秒 | ≤30 秒 | 允许 |
  | Seedance 2.0 | 最多 3 条 | 2–15 秒 | ≤15 秒 | 不允许 —— 至少还要 1 张参考图或 1 条参考视频 |

  **参考音频免费**：它不计入计费秒数，加音频不会让请求变贵。只带参考音频、不带参考视频的请求按该模型的**直接生成**每秒单价计费，不走带参考视频的折扣价。

  校验失败都是扣费前的 `400`：`reference_audio_not_supported`、`too_many_reference_audios`、`reference_audio_total_seconds_exceeded`、`reference_audio_requires_visual`；音频读不出、不是 wav/mp3、或单条时长越界则是 `invalid_reference_audio`。
</ParamField>

<ParamField body="referenceVideoDuration" type="number">
  已弃用的兼容提示，新集成应省略。若仍传入，必须是有限的非负数，服务端可能用它与探测值做诊断比对，但它不决定计费或裁剪。Seedance 2.5 / 2.0 续写均以服务端探测到的真实时长为准；使用 `referenceVideos` 时，计费用的是每条探测时长之和。音频没有对应字段 —— 音频时长始终由服务端探测，且从不计费。
</ParamField>

<ParamField body="idempotencyKey" type="string">
  可选 UUID。用于防止重复提交——例如弱网超时后的重试。

  对于新的 API Token 请求，此 UUID 标识所属账号的一次逻辑尝试；提交前应保存 ID 和精确输入。沿用原 ID 与相同参数可恢复该尝试；已经建单时返回 `deduped: true`，不再扣费。修改参数返回 `409 idempotency_conflict`，不同账务上下文可能返回 `request_id_collision`，不能自动换 ID 绕过。对象字段顺序不影响比对，其它调用参数值在模型默认值应用前比较。旧任务可能缺少完整输入指纹，不能据此追溯保证所有旧回执。详见[按请求 ID 恢复](/zh/api-reference/endpoint/requests)。MCP 普通生成把此句柄称为 `requestId`。
</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` 会选择合适的比例，提交时即在此返回 —— 无需等第一次轮询，可用于在界面上按正确比例预留占位。

  <Note>
    除一种情况外，此值都与实际产物一致：**Agnes Video 2.5 Flash 的图生视频，且首帧图是
    我们无法预裁的来源**（外部 URL 或 `data:` base64）—— 此时输出比例跟随你的首帧图。
    若该场景下构图很关键，请直接读取返回视频的实际尺寸，不要依赖此字段。
  </Note>
</ResponseField>

<ResponseField name="deduped" type="boolean">
  若本次响应命中了此前请求的同一个 `idempotencyKey`，该字段为 `true`——未再次扣除积分。
</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": 6,
  "modelId": "gpt-image-2.5",
  "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",
  "expectedWaitSeconds": 25,
  "pollHintSeconds": 20
}
```

<Note>
  * **`expectedWaitSeconds`** —— 该模型 + 分辨率的预估总等待秒数（从提交时算起）。
  * **`pollHintSeconds`** —— 建议还需继续轮询的秒数，会逐步归零，归零即可停止轮询。用它来驱动轮询节奏，而不要写死固定超时——参考视频续写、更高档位耗时可能明显长于普通文生视频。
  * 这两个字段只在 `status` 为 `"processing"` 时出现。
</Note>

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

```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.2 每次返回 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`（已退回余额）。

## 上传参考视频与音频

```
POST /api/upload/reference-video
```

`referenceVideos` 与 `referenceAudios` 只接受托管在 `images.meigen.ai` 上的文件。本端点用于为本地文件申请预签名上传 URL，再由你自己 PUT 文件字节。它同时接受 **API Token**（`Bearer meigen_sk_...`）和登录态 session access token —— 只读 Bearer 请求头，不读 cookie。视频和音频共用该端点，用 `kind` 区分。

API Token 调用还要求账户**已购积分余额大于零**。上传本身不扣点，但余额为零时返回 `402` —— 为同一账号充值后重试。session 调用不受此限。

### 请求体参数

<ParamField body="filename" type="string" required>
  原始文件名。服务端只校验它是非空字符串：既不存储也不回显，它不会进入存储对象，也不会出现在响应里。对象的存储扩展名**只**由 `contentType` 推导：`video/mp4` → `mp4`、`video/quicktime` → `mov`、`audio/wav` / `audio/x-wav` / `audio/wave` / `audio/vnd.wave` → `wav`、`audio/mpeg` / `audio/mp3` → `mp3`。文件名叫 `clip.mov`、`contentType` 却传 `video/mp4` 时，仍然按 `.mp4` 落盘。所以请传与文件真实容器一致的 `contentType` —— 厂商是按存储 URL 的后缀判断容器的。
</ParamField>

<ParamField body="contentType" type="string" required>
  文件的 MIME 类型，也是决定存储扩展名的唯一依据。视频接受 `video/mp4` 和 `video/quicktime`；音频接受 `audio/wav`、`audio/x-wav`、`audio/wave`、`audio/vnd.wave`、`audio/mpeg` 和 `audio/mp3`。它必须与 `kind` 一致 —— 音频类型配 `kind: "video"`（或反过来）会返回 `400`。后续 `PUT` 必须使用完全相同的值。
</ParamField>

<ParamField body="size" type="number" required>
  文件的精确字节数。签发 URL 前会按所选模型的上限校验：参考视频在 Seedance 2.5 上 ≤200MB、Seedance 2.0 上 ≤50MB；参考音频两个模型都是 ≤15MB。
</ParamField>

<ParamField body="modelId" type="string">
  你接下来打算用于生成的模型，决定适用哪一档大小上限。不传时音频按 15MB 的历史兜底值处理。
</ParamField>

<ParamField body="kind" type="string" default="video">
  `video` 或 `audio`。为兼容已有集成，默认值是 `video`。
</ParamField>

### 响应

<ResponseField name="presignedUrl" type="string">
  短时效的上传 URL，用 `PUT` 直接写入原始文件字节。请带上你在上一步声明的同一个 `Content-Type`，且不要带 `Authorization` 头。
</ResponseField>

<ResponseField name="publicUrl" type="string">
  上传完成后用于 `referenceVideos` / `referenceAudios` 的 `https://images.meigen.ai/...` 地址。
</ResponseField>

<ResponseField name="key" type="string">
  对象存储 key，形如 `ref-videos/YYYY-MM-DD/{id}.{mp4|mov|wav|mp3}`。音频与视频共用该前缀。
</ResponseField>

```bash theme={null}
# 1. 申请预签名 URL
curl -X POST https://www.meigen.ai/api/upload/reference-video \
  -H "Authorization: Bearer meigen_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "theme.mp3",
    "contentType": "audio/mpeg",
    "size": 1843200,
    "modelId": "seedance-2-5",
    "kind": "audio"
  }'

# 2. 把文件字节 PUT 到返回的 presignedUrl
curl -X PUT "<presignedUrl>" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @theme.mp3

# 3. 把返回的 publicUrl 填进 referenceAudios
```

<Note>
  上传的参考素材会在上传后 **7 天**自动删除。需要重新提交请保留源文件 —— 已经开始的生成不受影响，但过期的 `publicUrl` 会在新请求里校验失败。
</Note>

## 工作流示例

N 个脚本 → 首帧 → 视频、持久化 ID、在途预算预留与有限并发，详见[组合工作流](/zh/mcp/composable-workflows)。HTTP 使用 `idempotencyKey`，MCP 使用 `requestId`。新 ID 表示新尝试，不能用于超时恢复。

## 示例

### 基本生成

省略 `modelId` 时使用当前图片默认模型。请读取[模型列表](/zh/api-reference/endpoint/models)的 `is_default`，默认值可能变化：

```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"
  }'
```

### 显式设置 GPT Image 2.5

当[活跃模型列表](/zh/api-reference/endpoint/models)中返回 `gpt-image-2.5` 时，可使用此示例。

```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 studio product photo of a ceramic coffee mug, soft window light",
    "modelId": "gpt-image-2.5",
    "aspectRatio": "4:5",
    "resolution": "2K",
    "quality": "low",
    "modelVariant": "sunburst"
  }'
```

这次 2K Standard 请求消耗 **6 积分**。若要使用 4K Max 与速度优先，改为 `resolution: "4K"`、`quality: "max"`、`modelVariant: "flare"`（**88 积分**）。添加 `referenceImages` 即可编辑或使用视觉参考，不额外收取参考图积分。实扣以 `creditsUsed` 为准。

只有重试相同请求时才复用同一个 `idempotencyKey`。修改质量或型号选项属于新请求，应使用新的 key。

### 带参考图片

```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-4.5",
    "aspectRatio": "16:9",
    "referenceImages": ["https://example.com/reference.jpg"]
  }'
```

### Midjourney V8.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 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 2.5 视频生成（文生视频）

```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-5",
    "aspectRatio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'
```

计费：Seedance 2.5 没有档位。720p 为 39 积分/秒 × 5 秒 = **195 积分**。

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

```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-5",
    "aspectRatio": "adaptive",
    "resolution": "480p",
    "duration": 5,
    "referenceVideos": ["https://images.meigen.ai/generations/eagle-clip.mp4"]
  }'
```

计费：480p 带参考视频为 11 积分/秒。假设上传视频实际为 2 秒（系统自动识别），计费秒数 = max(2 + 5, 9) = 9 秒，共 **99 积分**。输出长度仍为 `duration` = 5 秒。

### Seedance 2.5 两条参考视频 + 一条参考音频

```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 dive from [video1], then cut to the river camera move of [video2], scored to the rhythm of [audio1]",
    "modelId": "seedance-2-5",
    "aspectRatio": "adaptive",
    "resolution": "480p",
    "duration": 5,
    "referenceVideos": [
      "https://images.meigen.ai/generations/eagle-dive.mp4",
      "https://images.meigen.ai/ref-videos/2026-09-17/river-pan.mp4"
    ],
    "referenceAudios": ["https://images.meigen.ai/ref-videos/2026-09-17/theme.mp3"]
  }'
```

计费：两条视频被探测为 3 秒和 4 秒，参考总时长 **7 秒**。计费秒数 = max(7 + 5, 9) = 12 秒，按 480p 带参考视频的 11 积分/秒，共 **132 积分**。参考音频加 **0** —— 它从不计费，时长也不计入总和。`[video1]` / `[video2]` / `[audio1]` 在请求抵达模型前会被改写成 `Video 1` / `Video 2` / `Audio 1`。

### 让系统自动选比例（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` 字段返回 —— 本次请求的响应和状态端点里都有。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.