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

# REST API 概览

> MeiGen REST API — 将 AI 图片与视频生成集成到你的应用。支持 GPT Image 2、Nanobanana 2、Midjourney、Seedream、Seedance、Veo 等模型，统一接口，Bearer Token 认证。

MeiGen API 允许你以编程方式生成图片和视频。

<Tip>
  **偏好自然语言？** 如果你使用 Claude Code、Cursor 或 OpenClaw，可以试试 [MCP 服务器](/zh/mcp/overview)，无需写 HTTP 代码即可生成图片。
</Tip>

## 认证

API 请求需要 Bearer token。有两种认证方式：

### API Token（推荐）

使用以 `meigen_sk_` 开头的 API Key。在你的[账户设置](https://www.meigen.ai)中的 **API Keys** 下创建。

```bash theme={null}
Authorization: Bearer meigen_sk_YOUR_API_KEY
```

<Warning>
  API Token 只能使用**购买积分**。每日免费积分不可用于 API 调用。在发起 API 请求前，请确保你的账户有购买积分。
</Warning>

### Session Token

面向 meigen.ai 内部的浏览器集成，使用登录后的 session access token。每日免费积分**仅可用于基础模型**（当前为 Z Image Turbo、Flux 2 Klein、Agnes Image 2.1 Flash 和 Agnes Video 2.0）；其余模型始终需要消耗注册赠送或购买积分。第三方集成请统一使用上面的 API Token。

## 基础 URL

```
https://www.meigen.ai/api
```

## 请求格式

所有请求体必须以 JSON 格式发送，并设置 `Content-Type: application/json` 请求头。

```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", "modelId": "gpt-image-2"}'
```

## 响应格式

所有响应返回 JSON。成功响应包含 `success: true` 字段：

```json theme={null}
{
  "success": true,
  "generationId": "abc-123",
  "status": "processing"
}
```

错误响应包含 `error` 字段：

```json theme={null}
{
  "error": "Error description"
}
```

## 异步生成

图片生成是**异步**的。流程如下：

1. **提交**生成请求 → `POST /api/generate/v2`
2. **轮询**状态端点 → `GET /api/generate/v2/status/:id`
3. 当 `status === "completed"` 时，直接从状态响应读取 `imageUrl` / `imageUrls` / `videoUrl`。

### 轮询最佳实践

* **推荐间隔**：每 3 秒检查一次状态
* **停止条件**：当 `status` 为 `completed` 或 `failed` 时
* **超时建议**：图片模型留到 6 分钟，视频留到 12 分钟。超时仍未完成的任务会以 `failed` 返回并**全额退还积分**，产物直接丢弃，不会迟到送达。未超时则相反：客户端过早停止轮询，任务仍会跑完并照常计费。请轮询到 `status` 进入终态（`completed` / `failed`），上面的墙钟时间只作兜底。最慢的情形是高分辨率 / 长时长的 Seedance 2.0 与 Veo 3.1。各模型典型耗时见[模型](/zh/features/models)页面。

## 缓存

部分 GET 端点返回缓存响应：

| 端点                    | 缓存时长                            |
| --------------------- | ------------------------------- |
| `GET /api/models`     | 1 小时（另有 stale-while-revalidate） |
| `GET /api/images/:id` | 1 小时                            |
| `POST` 端点             | 无缓存                             |

因此模型清单的变更——上新、下线、切换默认模型——最长可能 1 小时后才可见，请据此设计自己的刷新节奏。

## 积分

每次生成会从账户扣除积分。图片模型按张计费（单价可能随分辨率与画质变化）；视频模型按秒或按次计费，取决于具体模型。各模型完整定价表见[模型](/zh/features/models)页面。

## 错误响应

| 状态码 | 含义                |
| --- | ----------------- |
| 400 | 请求无效 — 参数错误       |
| 401 | 未授权 — token 无效或缺失 |
| 402 | 需要付费 — 积分不足       |
| 404 | 未找到               |
| 500 | 服务器错误             |

`POST /api/generate/v2` 的错误响应会附带便于排查的额外字段，且大多在人类可读的 `error` 之外还带一个可供程序判断的 `code`：

| `code`                  | 状态码 | 含义                                                          |
| ----------------------- | --- | ----------------------------------------------------------- |
| `premium_model_paywall` | 402 | 所选模型需要购买积分                                                  |
| `insufficient_credits`  | 402 | 本次请求的可用积分不足                                                 |
| `invalid_reference_url` | 400 | `referenceImages` / `referenceVideo` 中存在不合法的 URL 或 base64 值 |

不带 `code` 的错误（如比例不被支持）请按状态码与 `error` 文案处理。

```json theme={null}
// 400 — 比例不被该模型支持
{
  "success": false,
  "error": "Aspect ratio 32:9 is not supported by GPT Image 2.0",
  "supportedRatios": ["1:1", "1:3", "16:9", "2:3", "21:9", "3:1", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "9:21"]
}

// 400 — 参考图不可用
{
  "success": false,
  "code": "invalid_reference_url",
  "error": "Reference images must be public HTTP(S) URLs or data:image/*;base64 inline data. Local file paths (e.g. C:/Users/...) and file:// URIs are not supported — upload the file to a public URL or pass base64 inline.",
  "received": "C:/Users/me/ref.png"
}

// 402 — 高级模型，且无购买积分
{
  "success": false,
  "code": "premium_model_paywall",
  "error": "Premium model requires purchased credits",
  "required": 10,
  "available": 4
}
```

## 端点

<CardGroup cols={2}>
  <Card title="生成图片" icon="wand-magic-sparkles" href="/zh/api-reference/endpoint/generate">
    POST /api/generate/v2
  </Card>

  <Card title="模型列表" icon="robot" href="/zh/api-reference/endpoint/models">
    GET /api/models
  </Card>

  <Card title="图片详情" icon="image" href="/zh/api-reference/endpoint/images">
    GET /api/images/:id
  </Card>

  <Card title="API Token" icon="key" href="/zh/api-reference/endpoint/tokens">
    在账户设置中创建与撤销
  </Card>
</CardGroup>