REST API 概览 - MeiGen Docs

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

偏好自然语言？ 如果你使用 Claude Code、Cursor 或 OpenClaw，可以试试 MCP 服务器，无需写 HTTP 代码即可生成图片。

认证

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

API Token（推荐）

使用以 meigen_sk_ 开头的 API Key。在你的账户设置中的 API Keys 下创建。

Authorization: Bearer meigen_sk_YOUR_API_KEY

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

Session Token

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

基础 URL

https://www.meigen.ai/api

选模型前先调用模型列表。以下示例要求 gpt-image-2.5 已启用。该端点仍返回 GPT Image 2 时，可继续使用旧模型 ID 与原有价格。

请求格式

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

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.5", "resolution": "2K", "quality": "low", "modelVariant": "sunburst"}'

响应格式

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

{
  "success": true,
  "generationId": "abc-123",
  "status": "processing"
}

错误响应包含 error 字段：

{
  "error": "Error description"
}

异步生成

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

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

轮询最佳实践

推荐间隔：每 3 秒检查一次状态
停止条件：当 status 为 completed 或 failed 时
当 status 为 processing 时，响应会带上 expectedWaitSeconds（该模型 + 分辨率的预估剩余等待秒数）与 pollHintSeconds（建议继续轮询的剩余秒数，归零表示可以停止）。用这两个字段替代写死的超时时间——实际耗时会随模型、分辨率、时长变化。各模型典型耗时见模型页面。
客户端过早停止轮询不影响结果：任务仍会跑完并照常计费，请务必轮询到 status 进入终态。

缓存

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

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

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

积分

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

错误响应

状态码	含义
400	请求无效 — 参数错误
401	未授权 — token 无效或缺失
402	需要付费 — 积分不足
403	禁止访问 — 该模型在当前平台不可用
404	未找到
409	冲突 — 幂等键已被占用，换一个重试
5xx	服务器错误 — 稍后重试；生成失败的积分会自动退还

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

`code`	状态码	含义
`insufficient_credits`	402	本次请求的可用积分不足
`premium_model_paywall`	402	所选模型需要购买积分（每日免费积分不适用）
`unsupported_quality`	400	所选 GPT Image 模型不支持此质量档位
`unsupported_model_variant`	400	型号选项不合法，或为 GPT Image 2.5 以外的模型传了 `modelVariant`
`invalid_model`	400	模型不存在、未启用，或仅供技能工作流使用
`unsupported_duration`	400	该模型不支持这个时长
`unsupported_tier`	400	该模型不支持这个档位
`unsupported_resolution`	400	该模型/档位不支持这个分辨率
`first_frame_required`	400	该模型必须提供首帧图
`reference_video_not_supported`	400	该模型/档位/分辨率不支持参考视频续写
`invalid_reference_video`	400	参考视频无法读取或不符合所选模型限制。请读取 `capabilities.video.referenceVideo`：Seedance 2.5 为 2–30 秒、≤200MB；Seedance 2.0 为 2–15 秒、≤50MB；链接必须来自平台内
`invalid_reference_url`	400	`referenceImages` 中存在不合法的 URL 或 base64 值
`frame_reference_limit`	400	`referenceMode: "frame"` 最多 2 张图，改用 `referenceMode: "content"` 可传更多
`too_many_references`	400	参考图数量超出该模型上限
`too_many_characters`	400	每次生成最多引用 3 个 `[character:...]`
`character_not_found`	400	该角色不存在或不属于当前账号
`characters_not_supported`	400	该模型不支持角色引用
`character_tier_required`	400	该角色需要更高档位
`model_not_available`	403	该模型在当前平台不可用
`idempotency_conflict`	409	换一个新的 `idempotencyKey` 重试

除上述之外的错误——包括所有 5xx 响应——都代表服务端暂时不可用。稍后重试即可，生成失败的积分会自动退还。不带 code 的错误（如比例不被支持）请按状态码与 error 文案处理。

// 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
}

端点

生成图片

POST /api/generate/v2

模型列表

GET /api/models

图片详情

GET /api/images/:id

API Token

在账户设置中创建与撤销

​认证

​API Token（推荐）

​Session Token

​基础 URL

​请求格式

​响应格式

​异步生成

​轮询最佳实践

​缓存

​积分

​错误响应

​端点

生成图片

模型列表

图片详情

API Token

认证

API Token（推荐）

Session Token

基础 URL

请求格式

响应格式

异步生成

轮询最佳实践

缓存

积分

错误响应

端点