modelId 选择。
请求
请求头
请求体参数
string
必填
GPT Image 2 与 2.5 的长提示词会自动压缩以适配模型限制,请明确写出关键要求和需要保留的内容。要生成的图片或视频的文本描述。要引用已创建的角色,在文本中内嵌
[character:<uuid>] ——例如 "[character:550e8400-e29b-41d4-a716-446655440000] standing in a neon-lit alley, cinematic lighting"。每次生成最多引用 3 个角色。支持范围:所有接受参考图的图片模型(Flux 3 Image Klein 除外)+ 视频侧 Seedance 2.5 / 2.0 和 HeyGen。角色图片与用户上传图片共用内容参考图预算。模型不支持、角色不存在或无权访问、引用数超限均返回 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 的第二项,而不是全部素材里的第二个。Seedance 请求抵达模型前,两类标记的处理方式不同:[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]会原样留在提示词里,不会被删除 —— 所以图片编号不要超过你实际传的张数。
[imageN]、[videoN]、[audioN],按实际素材编号;越界 token 在扣点前拒绝。普通 Picture N / Video N 文字不会创建引用。首帧引用改写成自然描述,不生成内容参考 token;角色图占用 9 张内容图额度,首帧不能与内容图/视频/音频/角色混用。string
用于生成的模型。不传则使用平台当前默认模型(可能随平台配置变化)。模型列表是模型 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 调用)。
string
默认值:"auto"
生成媒体的宽高比。
- 默认
auto(推荐):为你自动挑选合适的比例。 - 也可显式指定——必须是 模型列表 返回的
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 字段返回。
HeyGen 文本/内容图/参考视频使用 auto 或受支持的固定比例,仅首帧模式使用 adaptive;1080p/2K 内容模式只接受 16:9 或 9:16。boolean
默认值:"false"
显式启用 Seedance 2.5 付费草稿,固定为 480p。先检查
capabilities.draft.enabled,普通生成不传此字段。草稿完成后可确认当前费用并单独付费生成 1080p 成片,详见视频草稿。string
输出分辨率。HeyGen 支持
480p、768p(默认)、1080p、2k(小写 k)。可用性取决于模型。不传则使用所选模型的默认分辨率。可选值取决于模型:图片模型用 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。完整矩阵见模型对比。Grok Video 1.5 的 Lite / Standard 两档均支持 480p、720p、1080p,默认 480p。同时省略 tier 和 duration 时使用 Lite × 4 秒(480p 共 16 积分)。两档的 modelId 都是 grok-video。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。通过模型列表读取 extra_config.qualities 与 extra_config.pricing。GPT 不支持的质量值返回 400 / unsupported_quality。string
仅 GPT Image 2.5 支持:
sunburst(质量优先,配置默认值)或 flare(速度优先)。两者都支持图片生成和参考图编辑,同分辨率、同质量下同价。添加参考图不会自动改变此设置。与 modelId: "gpt-image-2.5" 一起使用。不要把型号选项名称当作独立模型 ID,也不要为 GPT Image 2 或其他模型传此字段。非法组合返回 400 / unsupported_model_variant。string[]
参考图数组。每一项必须是可公开访问的 HTTP(S) URL,或形如 最大数量按模型不同。图片模型和视频首帧/末帧输入请读模型列表返回的
data:image/png;base64,... 的内联 base64 数据。本地文件路径(如 C:/Users/...)与 file:// URI 会被拒绝,返回 400 / invalid_reference_url。Agnes Video 2.5 Flash —— 图生视频会忽略
aspectRatio。(该模型自 2026-09-22 起暂时下线,
以下规则在其启用时适用。)该模型的输出比例由首帧图本身
决定。对托管在 images.meigen.ai 上的图片(你在 MeiGen 生成或上传过的),我们会先在
CDN 边缘把首帧裁到你请求的 aspectRatio,因此输出与你选的比例一致;对其他来源
(外部 URL 或 data: base64),图片原样透传,输出比例跟随你的图片,而不是
aspectRatio。如果外部图片也需要精确的输出比例,请在发送前自行裁到该比例,或改传此前生成产物的
imageUrl(本来就在我们 CDN 上)。max_reference_images;Seedance 的 content 模式改读 extra_config.maxContentReferenceImages。撰写时的实况:content 模式下,Seedance 2.5 最多接受 30 张图片,Seedance 2.0 最多 9 张;使用角色时,角色解析出的图片也计入同一上限。string[]
HeyGen 在此仅接受 1 张首帧,不支持尾帧,且不可与内容图、视频、音频或角色混用。Seedance 的结构化首尾帧输入为可选,顺序为首帧、末帧,最多 2 张。需要同时控制首尾帧与内容参考时,可与
contentReferenceImages 一起使用。结构化字段优先于旧的 referenceImages / referenceMode 组合。string[]
HeyGen 接受最多 9 张内容图(含角色图),与首帧互斥,可配合视频或音频,不能同时配合两者。Seedance 的结构化内容参考图为可选:Seedance 2.5 最多 30 张,Seedance 2.0 最多 9 张。可与
frameReferenceImages、referenceVideos、referenceAudios 和角色引用同时使用。图片、视频、音频是三份互不占用的预算;角色图片计入本图片上限。string
默认值:"frame"
用于 Seedance 2.5、Seedance 2.0 和 HeyGen 的旧字段
referenceImages。HeyGen 的 frame 最多 1 张,content 最多 9 张;新接入建议使用结构化字段。frame(默认)—— 首/尾帧参考,最多 2 张content—— 内容参考,不绑定具体帧位置。当前 API 上限请读extra_config.maxContentReferenceImages(Seedance 2.5 为 30,Seedance 2.0 为 9)
400——Seedance frame 模式为 frame_reference_limit,内容参考或其他模型上限为 too_many_references。object
Midjourney V8.2 高级参数。对其他模型无效。(字段名沿用历史命名,向后兼容。)
string
默认值:"content"
仅用于 Midjourney V8.2。参考图片的解读方式。
content— 用作主题素材参考style— 仅提取视觉风格
number
视频时长(秒)。不传则按该模型自身的默认时长出片与计费:
实际扣除的积分始终以响应中的
creditsUsed 为准,不要自行推算。string
支持多档位模型的画质档位。
- Seedance 2.0:
mini(默认)、fast或pro - Veo 3.1:
fast(默认)或pro - Grok Video 1.5:
lite(默认)或standard,两档都必须提供一张首帧图
mini。完整价格矩阵见模型。string[]
用于
capabilities.video.referenceVideo.enabled 模型的参考视频数组,包括 Seedance 和 HeyGen。每一项都必须是 https://images.meigen.ai/... 地址 —— 要么来自此前 MeiGen 生成结果的 videoUrl,要么是通过参考素材上传端点上传的文件。不接受任意公网 URL:其他域名一律在扣点前返回 400 / invalid_reference_video。同一个 URL 只能出现一次,重复条目会在扣点前返回 400 / invalid_input,不会被探测和计费两次。服务端会逐条探测参考视频,以探测到的时长为准;你传的时长只作诊断提示。参考视频或参考音频的探测在预算内没完成时,请求在扣点前失败,返回
503 / reference_probe_timeout 且 retryable: true:用同一个 idempotencyKey 原样重试即可。计费按所有参考视频时长的总和:计费秒数 = max(参考视频时长总和 + 输出时长, 最低计费秒数)完整费率和示例见模型。Seedance 的参考视频、音频与内容参考图是独立预算。HeyGen 的 MP4 比例需为 1:4–4:1;按输出秒数+每段参考视频分别向上取整后的秒数计费,无最低秒数门槛;全部参考素材合计不超过 12 项。视频不能与单独音频同时提交(扣点前返回 reference_video_audio_conflict),视频自带音轨可保留。旧字段别名。 单数形式 referenceVideo(字符串)仍然受理,等价于只含一项的 referenceVideos 数组,并会长期保留。两者同时传时,referenceVideo 必须是 referenceVideos 的第一项;其他组合返回 400 / invalid_input。duration 设为原视频四舍五入后的整数秒数。多段视频都可能被选作编辑对象时,每段都必须与所选输出时长一致;使用单段原视频可避免歧义。上游明确返回编辑时长限制后,后端仅在不改变已计费输出秒数的条件下,尝试一次继承原视频时长的恢复。时长不匹配则失败并按正常流程退款,不会自动追加扣费。公开 API 仍只接受正整数;duration=-1 和 omni_reference_task_type 仅为内部供应商参数。已失败并退款的任务若需修改输入重做,必须另行授权并使用新请求 ID;结果不确定的提交仍用原 ID 和完全相同的输入恢复。
Seedance 参考视频若能可靠测得帧率且不在 23.8–60 FPS 内,会在扣费前以 400 / unsupported_reference_video_frame_rate 拒绝;请重新导出为 24–60 FPS。分片或不完整的时间表可能无法可靠确定帧率,仍可能由上游拒绝;此时以任务终态和实际退款状态为准。
string[]
用于
capabilities.video.referenceAudio.enabled 模型的参考音频数组,包括 Seedance 和 HeyGen。每一项都必须是通过参考素材上传端点得到的 https://images.meigen.ai/... 地址,格式为 wav 或 mp3,Seedance 单条不超过 15MB,HeyGen 不超过 16MB。不接受任意公网 URL:其他域名一律在扣点前返回 400 / invalid_reference_audio。格式按文件自身字节校验,不看扩展名或 Content-Type。参考音频秒数不计费:Seedance 加音频不改变价格;HeyGen 图片/音频输入采用内容参考费率,音频不额外增加秒数。Seedance 只带参考音频、不带参考视频的请求按该模型的直接生成每秒单价计费,不走带参考视频的折扣价。校验失败都是扣费前的
400:reference_audio_not_supported、too_many_reference_audios、reference_audio_total_seconds_exceeded、reference_audio_requires_visual;音频读不出、不是 wav/mp3、或单条时长越界则是 invalid_reference_audio。number
已弃用的兼容提示,新集成应省略。若仍传入,必须是有限的非负数,服务端可能用它与探测值做诊断比对,但它不决定计费或裁剪。Seedance 2.5 / 2.0 续写均以服务端探测到的真实时长为准;使用
referenceVideos 时,计费用的是每条探测时长之和。音频没有对应字段 —— 音频时长始终由服务端探测,且从不计费。string
可选 UUID。用于防止重复提交——例如弱网超时后的重试。对于新的 API Token 请求,此 UUID 标识所属账号的一次逻辑尝试;提交前应保存 ID 和精确输入。沿用原 ID 与相同参数可恢复该尝试;已经建单时返回
deduped: true,不再扣费。修改参数返回 409 idempotency_conflict,不同账务上下文可能返回 request_id_collision,不能自动换 ID 绕过。对象字段顺序不影响比对,其它调用参数值在模型默认值应用前比较。旧任务可能缺少完整输入指纹,不能据此追溯保证所有旧回执。详见按请求 ID 恢复。MCP 普通生成把此句柄称为 requestId。响应
boolean
请求是否被接受。
string
生成请求的唯一 ID。用此 ID 轮询状态。
string
初始状态,始终为
"processing"。number
本次生成扣除的积分数。
string
本次生成使用的模型。
string
本次生成所请求的宽高比。默认
auto 会选择合适的比例,提交时即在此返回 —— 无需等第一次轮询,可用于在界面上按正确比例预留占位。除一种情况外,此值都与实际产物一致:Agnes Video 2.5 Flash 的图生视频,且首帧图是
我们无法预裁的来源(外部 URL 或
data: base64)—— 此时输出比例跟随你的首帧图。
若该场景下构图很关键,请直接读取返回视频的实际尺寸,不要依赖此字段。boolean
若本次响应命中了此前请求的同一个
idempotencyKey,该字段为 true——未再次扣除积分。object
扣除后更新的积分余额。
查询生成状态
响应(处理中)
expectedWaitSeconds—— 该模型 + 分辨率的预估总等待秒数(从提交时算起)。pollHintSeconds—— 建议还需继续轮询的秒数,会逐步归零,归零即可停止轮询。用它来驱动轮询节奏,而不要写死固定超时——参考视频续写、更高档位耗时可能明显长于普通文生视频。- 这两个字段只在
status为"processing"时出现。
响应(图片已完成)
响应(视频已完成)
aspectRatio是该次生成最终采用的比例(如果你传了auto,这里是实际落地的值)。mediaType取值image或video。视频生成时imageUrl/imageUrls为null,反之亦然。- Midjourney V8.2 每次返回 4 张候选图片,
imageUrls包含全部候选,imageUrl始终指向第一张。其他图片模型返回单张。
响应(失败)
creditsStatus 确认退款是否落地:pending(已预扣,结果未定)、confirmed(已实际扣费)、refunded(已退回余额)。
上传参考视频与音频
referenceVideos 与 referenceAudios 只接受托管在 images.meigen.ai 上的文件。本端点用于为本地文件申请预签名上传 URL,再由你自己 PUT 文件字节。它同时接受 API Token(Bearer meigen_sk_...)和登录态 session access token —— 只读 Bearer 请求头,不读 cookie。视频和音频共用该端点,用 kind 区分。
API Token 调用还要求账户已购积分余额大于零。上传本身不扣点,但余额为零时返回 402 —— 为同一账号充值后重试。session 调用不受此限。
请求体参数
string
必填
原始文件名。服务端只校验它是非空字符串:既不存储也不回显,它不会进入存储对象,也不会出现在响应里。对象的存储扩展名只由
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 的后缀判断容器的。string
必填
文件的 MIME 类型,也是决定存储扩展名的唯一依据。视频接受
video/mp4 和 video/quicktime;音频接受 audio/wav、audio/x-wav、audio/wave、audio/vnd.wave、audio/mpeg 和 audio/mp3。它必须与 kind 一致 —— 音频类型配 kind: "video"(或反过来)会返回 400。后续 PUT 必须使用完全相同的值。number
必填
文件的精确字节数。签发 URL 前会按所选模型的上限校验:参考视频在 Seedance 2.5 上 ≤200MB、Seedance 2.0 上 ≤50MB;参考音频两个模型都是 ≤15MB。
string
你接下来打算用于生成的模型,决定适用哪一档大小上限。不传时音频按 15MB 的历史兜底值处理。
string
默认值:"video"
video 或 audio。为兼容已有集成,默认值是 video。响应
string
短时效的上传 URL,用
PUT 直接写入原始文件字节。请带上你在上一步声明的同一个 Content-Type,且不要带 Authorization 头。string
上传完成后用于
referenceVideos / referenceAudios 的 https://images.meigen.ai/... 地址。string
对象存储 key,形如
ref-videos/YYYY-MM-DD/{id}.{mp4|mov|wav|mp3}。音频与视频共用该前缀。上传的参考素材会在上传后 7 天自动删除。需要重新提交请保留源文件 —— 已经开始的生成不受影响,但过期的
publicUrl 会在新请求里校验失败。工作流示例
N 个脚本 → 首帧 → 视频、持久化 ID、在途预算预留与有限并发,详见组合工作流。HTTP 使用idempotencyKey,MCP 使用 requestId。新 ID 表示新尝试,不能用于超时恢复。
示例
基本生成
省略modelId 时使用当前图片默认模型。请读取模型列表的 is_default,默认值可能变化:
显式设置 GPT Image 2.5
当活跃模型列表中返回gpt-image-2.5 时,可使用此示例。
resolution: "4K"、quality: "max"、modelVariant: "flare"(88 积分)。添加 referenceImages 即可编辑或使用视觉参考,不额外收取参考图积分。实扣以 creditsUsed 为准。
只有重试相同请求时才复用同一个 idempotencyKey。修改质量或型号选项属于新请求,应使用新的 key。
带参考图片
Midjourney V8.2 风格参考
Seedance 2.5 视频生成(文生视频)
Seedance 2.5 视频续写(参考视频)
duration = 5 秒。
Seedance 2.5 两条参考视频 + 一条参考音频
[video1] / [video2] / [audio1] 在请求抵达模型前会被改写成 Video 1 / Video 2 / Audio 1。
让系统自动选比例(Auto)
省略aspectRatio 或显式传 "auto",由 MeiGen 自动挑选合适比例:
aspectRatio 字段返回 —— 本次请求的响应和状态端点里都有。
生成草稿成片
POST /api/generate/v2/draft-final 要求同一账户认证及 meigen:generate 权限。API 凭据调用须传 idempotencyKey(持久化 UUID)、sourceDraftGenerationId 和 confirmedCredits,先从草稿的认证状态查询中读取当前 seedanceDraft.finalCredits 报价。仅在单独授权重试失败成片时传 retryFailedGenerationId。使用 meigen:read 权限,通过 /api/generate/v2/requests/{requestId} 恢复任务。
报价变化返回 409 price_changed 及 required;重新确认后,使用新 ID 和新金额提交。410 draft_expired 表示不能再生成新成片。成片仅能来自本账户草稿,沿用原任务,API 调用只扣购买积分。同一请求 ID 不会自动替换失败任务。