apimart-zoe API

apimart-zoe 是 APIMart 推出的多模态视频生成模型，调用时的模型 ID 为 apimart-zoe。apimart-zoe API 支持文生视频、首尾帧生视频、图片/视频/音频参考生视频、视频编辑、可选的音画同出，以及「480p 样片 → 1080p 正片」两步生成。视频时长 4–30 秒，分辨率可选 480p、720p、1080p、2k 或 4k。

使用 Authorization: Bearer <API Key>，向 POST /v1/videos/generations 提交 model 为 apimart-zoe 的请求和提示词，响应会返回 task_id。出片通常需要 1–3 分钟：每 5–10 秒轮询一次 GET /v1/tasks/{task_id}，直到 data.status 为 completed，再从 data.result.videos[0].url[0] 读取视频地址。本页示例提供 cURL 和 Python 代码，完整的 apimart-zoe API 文档见 APIMart 文档中心。

model（apimart-zoe）必填。prompt 在文生视频时必填，只传素材时可省略，最长 204,800 字符。可选参数包括 resolution（480p、720p、1080p、2k 或 4k）、aspect_ratio 或 size（21:9、16:9、4:3、1:1、3:4、9:16 或 adaptive）、duration 或 seconds（4–30 或 -1）、audio 或 generate_audio、seed、image_with_roles、image_urls（别名 image、images、image_url）、first_frame_image、last_frame_image、video_urls、audio_urls、draft、draft_task_id、omni_reference_task_type（auto、reference 或 edit）、return_last_frame、output_format 或 response_format（mp4 或 mov）、enhance_prompt，以及 APIMart 平台字段 nsfw_check。negative_prompt、camera_fixed（含 camerafixed）、extend_from_task_id、mask_url、video_list、element_list、multi_shot 和 tools 不支持，只要字段出现在请求中就返回 400，空串、空数组、false、null 也一样；n 只能不传或传 1。默认值与限制见本页参数表。

duration（或 seconds）可设为 4–30 之间的整数，默认 5 秒，设为 -1 则由模型决定时长。resolution 为 480p、720p（默认）、1080p、2k 或 4k，大小写不敏感。aspect_ratio（也可写作 size）为 21:9、16:9、4:3、1:1、3:4、9:16 或 adaptive（默认，由模型或素材决定画幅）。视频编辑时不传 duration 和 aspect_ratio（或传 -1 和 adaptive），成片时长和画幅跟随源视频。样片固定 480p，正片固定 1080p。

能。通过 image_with_roles 传入 first_frame 和 last_frame，或使用 first_frame_image 和 last_frame_image。首帧、尾帧各 1 张，传尾帧必须同时传首帧。首尾帧请求不能同时包含参考图、参考视频或参考音频，否则返回 400 且不扣费。可以在提示词中描述镜头如何从首帧过渡到尾帧。

最多 30 张参考图、10 段参考视频和 10 段参考音频，素材合计最多 50 个；参考音频必须同时带参考图或参考视频。图片支持 jpeg、png、webp、bmp、tiff、gif、heic、heif，边长 300–6000 像素，宽高比 0.4–2.5，单张小于 30MB。视频为 mp4 或 mov（H.264/H.265，音轨 AAC 或 MP3），单段 2–15 秒（允许 1.8–15.2 秒）、不超过 200MB，宽、高各 300–6000 像素，宽×高在 409,600–8,295,044 之间（约 640×640 到 3840×2160），宽高比 0.4–2.5，帧率 24–60（四舍五入后判断，23.976、59.94 均可）；视频编辑的源视频可为 4–30 秒（最短 3.8 秒，须短于 30.2 秒），不指定任务类型时，超过 15 秒的视频请用 edit。音频为 wav 或 mp3，单段 2–15 秒（允许 1.8–15.2 秒）且不超过 15MB，合计不超过 30 秒（≤30.2 秒）。参考视频的时长、宽高、宽高比、帧率和参考音频的时长在提交时检查，不符合直接返回 400 invalid_request_error，不扣费；图片尺寸、文件大小和编码在生成时检查，不符合时任务失败、费用自动退回，建议调用前自行校验。所有素材都须使用公网 http(s) URL 或 asset:// 素材 ID，不接受 data: 内联数据，请先上传到可公网访问的地址；提交时平台自动登记素材，同一个文件 7 天内重复使用不会重复登记。只传素材时可以省略 prompt。

先提交 draft: true 的请求，得到低成本的 480p 预览；样片只能是 480p，且不能与视频编辑同时使用。样片成功后，再提交一个包含 model 和 draft_task_id（值为样片的 task_id）的请求。正片以 1080p 生成，沿用样片的提示词、素材、时长、画幅、种子和音频设置；除 model、draft_task_id、resolution 和 nsfw_check、webhook 这类通用字段外，其他字段都不能出现，prompt、素材、duration、aspect_ratio、seed、audio、omni_reference_task_type、return_last_frame、output_format、enhance_prompt 即使传空值也返回 400。正片需在样片创建后 24 小时内生成：draft_task_id 不存在、不是样片、样片未完成或已超过 24 小时，都会返回 400。样片和正片各算一次生成费用，正片按 1080p、以样片的时长计费（样片为 -1 时取样片成片的实际时长）。

提交失败统一返回包含 message、type、param、code 的 error 对象，且不扣费。400 invalid_request_error 涵盖参数取值、素材数量与组合（如首尾帧与参考素材同时出现、image_urls 与 image_with_roles 混用）、参考视频时长 / 宽高 / 宽高比 / 帧率与参考音频时长超限、任务类型与视频编辑约束、output_format 取值、样片和正片的约束，以及 negative_prompt、camera_fixed 等不支持的参数。400 input_video_probe_failed 表示参考视频无法访问或探测不到时长。402 payment_required 表示余额不足；duration 为 -1 或视频编辑时按 30 秒预扣。400 nsfw_content_detected 表示 nsfw_check 审核命中，message 中会给出命中类别。503 draft_channel_unavailable 或 draft_task_unavailable 表示样片通道或样片查询暂时不可用，请稍后重试或重新生成样片。

出片通常需要 1–3 分钟，建议每 5–10 秒查询一次。data.status 为 pending、processing、completed 或 failed，data.progress 为 0–100。data.result.videos[0].url 中的视频地址已转存到 APIMart 存储，完成后 72 小时内有效，请及时下载；传了 return_last_frame: true 时，data.result.last_frame_url 还会返回 png 格式的尾帧图片。任务失败时（包括素材登记未通过，或图片尺寸、文件大小、编码在生成时检查不通过），data.error.message 给出失败原因，data.error.code 为 task_failed，data.cost 为 0，预扣费用已自动退回。

apimart-zoe API 按输出秒数计价，480p、720p、1080p、2k、4k 各有单价，带参考视频的请求另有一档单价。传了 duration（4–30）或不传（默认 5）时，按请求的秒数计费，完成后不按成片长度调整；duration 为 -1 或视频编辑（omni_reference_task_type: edit）时先按 30 秒预扣，完成后取成片实际时长（四舍五入到整秒）多退少补；视频编辑按带参考视频的单价计费。有参考视频时，计费秒数 = 视频时长 + max(参考视频总时长, ⌈视频时长 × 2/3⌉)；参考视频总时长在提交时逐段探测、相加后向下取整到秒，之后不再调整。由样片生成的正片按 1080p 计费，时长沿用样片（样片为 -1 时取样片成片的实际时长）；若样片带参考视频，正片同样计入参考视频时长。实际扣费按会员或账户分组折扣计算，以本页实时价格表为准。

在 APIMart 上，两个模型都使用 POST /v1/videos/generations 和 GET /v1/tasks/{task_id}，都能生成 4–30 秒、21:9 到 9:16 各种画幅的视频，每次最多 30 张参考图、10 段视频和 10 段音频，都支持 seed、音频生成、return_last_frame、output_format 和视频编辑（omni_reference_task_type: edit），也都支持 480p 样片转 1080p 正片。差异在于：apimart-zoe（模型 ID apimart-zoe）还支持 2k 和 4k 输出，首尾帧不能与参考素材同时使用，传参考音频时必须同时带参考图或参考视频，不传 audio 时由模型决定是否生成音频；Seedance 2.5（seedance-2.5）的 generate_audio 默认开启，并且还支持视频延长（extend），apimart-zoe 的 extend 暂未开放。带参考视频时，两者的计费秒数算法也不同。本页对比表列出了各项差异和当前每秒价格。

取决于分辨率以及是否带参考视频。本页的价格对比列出两个模型有无参考视频时的当前每秒单价、价差百分比，以及常见时长的成本示例。带参考视频时，apimart-zoe 在输出秒数上加 max(参考视频总秒数向下取整, ⌈输出秒数 × 2/3⌉)，Seedance 2.5 加的是参考视频秒数，请对照与你视频时长相符的示例。apimart-zoe 还有 Seedance 2.5 没有的 2k 和 4k 档。单价从 APIMart 价格接口读取，并取决于你的会员等级。

不免费。它按输出秒数按量付费，样片和由它生成的正片各算一次生成费用。提交阶段的错误不扣费，余额不足时返回 402，失败任务的费用会自动退回，data.cost 显示为 0。价格取决于你的会员等级或账户分组，各分辨率的当前价格以本页实时价格表为准。

注册 APIMart，在控制台打开 API Keys 页面并创建新 Key，然后以 Authorization: Bearer <key> 的形式发送。同一个 Key 可调用 apimart-zoe API 及 APIMart 上的其他模型，按量付费，无需订阅。