apimart-zoe 视频生成

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "apimart-zoe",
    "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "apimart-zoe",
    "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KZOEEXAMPLE"
    }
  ]
}

POST

videos

generations

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "apimart-zoe",
    "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "apimart-zoe",
    "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KZOEEXAMPLE"
    }
  ]
}

本接口采用异步处理。提交后读取 data[0].task_id，再通过获取任务状态查询结果。通常需要 1–3 分钟，建议每 5–10 秒查询一次，实际耗时以任务状态为准。

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "apimart-zoe",
    "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "apimart-zoe",
    "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KZOEEXAMPLE"
    }
  ]
}

模式选择

模式	传参方式
文生视频	提供 `prompt`，不传素材。
首尾帧生视频	使用 `image_with_roles` 的 `first_frame` 角色，可选 `last_frame`；也可使用 `first_frame_image` / `last_frame_image`。
参考生视频	使用参考图或参考视频，可搭配参考音频；不能只传参考音频。
样片	设置 `draft: true`，输出 `480p`。
正片	使用已成功样片的 `draft_task_id`，输出 `1080p`。
视频编辑	设置 `omni_reference_task_type: "edit"`，至少提供 1 段源视频，输出时长和画幅跟随源视频。

请求头

string

必填

Bearer 认证，格式为 Bearer <token>，其中 <token> 为你的 APIMart API Key。请求正文使用 Content-Type: application/json。

请求参数

string

必填

固定为 apimart-zoe。

string

最长 204,800 字符。文生视频必填；只传素材时可省略。通过 draft_task_id 生成正片时禁止传入，自动沿用样片提示词。

string

支持 480p、720p、1080p、2k、4k，大小写不敏感。普通生成默认 720p。draft: true 时只能为 480p，省略时自动使用 480p；传入 draft_task_id 时只能为 1080p，省略时自动使用 1080p。

string

支持 21:9、16:9、4:3、1:1、3:4、9:16、adaptive。默认 adaptive，由模型或素材决定。生成正片时禁止传入，沿用样片画幅。视频编辑（edit）时只能省略或传 adaptive，画幅跟随源视频。

string

aspect_ratio 的另一种写法，支持相同取值。建议只使用其中一个字段；生成正片时省略。

integer

普通生成：整数秒 4–30，默认 5。指定时长或使用默认值时，按该秒数计费，完成后不按成片长度调整。传 -1 时由模型决定时长：提交时按 30 秒预扣，完成后将成片实际时长四舍五入到整数秒，再多退少补。生成正片时禁止传入，沿用样片时长。视频编辑（edit）时只能省略或传 -1；省略时自动按 -1 处理，输出时长跟随源视频。

integer

duration 的别名，规则相同。建议只使用其中一个字段；生成正片时省略。

boolean

是否同时生成音频，类型为布尔值；别名为 generate_audio。省略时由模型决定。生成正片时禁止传入。此字段控制输出音频，与输入参考音频 audio_urls 不同。audio 与 generate_audio 同时传入时，值必须相同，否则返回 HTTP 400。省略时通常会生成声音，具体由模型决定。

boolean

audio 的别名，规则相同。建议只使用其中一个字段；生成正片时省略。audio 与 generate_audio 同时传入时，值必须相同，否则返回 HTTP 400。省略时通常会生成声音，具体由模型决定。

integer

随机种子，整数。生成正片时禁止传入。

boolean

默认不审核；设置 true 才启用。可选布尔值，设为 true 时启用内容审核。审核范围为提示词 prompt、image_urls、image_with_roles、首尾帧图片，以及 asset:// 图片素材；参考视频和参考音频不送审。正片请求不携带提示词和素材，样片 → 正片流程的审核在生成样片时进行。命中时返回 HTTP 400（nsfw_content_detected），error.message 包含命中类别；应按审核拒绝展示，不按普通参数错误处理。审核服务异常或调用失败时，生成请求会继续提交，因此开启此参数不保证每次请求都完成审核。

string

支持 auto（默认，等同省略，由模型判断）、reference（参考生视频）和 edit（视频编辑）。reference / edit 只能用于带参考素材的请求；文生视频或首尾帧请求传入这两个值会返回 HTTP 400。edit 至少需要 1 段 video_urls，不能与 draft: true 同用。extend 暂不支持，传入返回 HTTP 400。生成正片时禁止传入。

boolean

设为 true 时额外返回成片最后一帧的 PNG 图片，地址位于 data.result.last_frame_url。默认不返回；生成正片时禁止传入。

string

支持 mp4（默认）或 mov（QuickTime 封装），其他取值返回 HTTP 400。别名为 response_format；两个字段都传时以 output_format 为准。生成正片时禁止传入。

string

output_format 的别名，支持 mp4 / mov；两个字段都传时以 output_format 为准。生成正片时禁止传入。

boolean

设为 true 时在生成前自动优化提示词。默认不优化，按原提示词生成。生成正片时禁止传入。

object[]

每项包含 url 和 role。role 支持 first_frame（首帧）、last_frame（尾帧）、reference_image（参考图）。首帧、尾帧各最多 1 张；有尾帧时必须同时提供首帧。首尾帧不能与参考素材混用。image_urls 与 image_with_roles 不能同时传入，否则提交返回 HTTP 400（invalid_request_error），不扣费。image、images、image_url 这些别名也计入 image_urls，不能绕过此限制。

string[]

参考图数组，最多 30 张。格式、尺寸和大小限制见下方素材要求。image_urls 与 image_with_roles 不能同时传入，否则提交返回 HTTP 400（invalid_request_error），不扣费。image、images、image_url 这些别名也计入 image_urls，不能绕过此限制。

string

首帧图片地址，等价于 image_with_roles 中的 first_frame 角色。

string

尾帧图片地址，等价于 image_with_roles 中的 last_frame 角色；必须同时提供首帧。

string[]

参考视频数组，最多 10 段。支持公网 http(s) URL 或 asset://<素材 ID>，不支持 data: Base64。提交时按下方规则校验视频尺寸、精确时长和帧率。计费时，参考视频各段时长相加后向下取整到秒，之后不再调整；此取整不用于判断单段时长是否合法。无法访问或探测时长失败时返回 HTTP 400（input_video_probe_failed），不扣费。auto / reference：2–15 秒，允许范围 1.8 ≤ t ≤ 15.2 秒；edit 源视频：4–30 秒，允许范围 3.8 ≤ t < 30.2 秒。按精确时长检查，不先取整。

string[]

最多 10 段；WAV / MP3；单段 2–15 秒、≤ 15 MB，合计不超过 30 秒。允许 ±0.2 秒误差：单段 1.8 ≤ t ≤ 15.2 秒、合计 ≤ 30.2 秒。必须搭配参考图或参考视频。支持公网 http(s) URL 或 asset://<素材 ID>，不支持 data: Base64。音频时长在提交时校验，不符合时同步返回 HTTP 400，不扣费。

boolean

设置为 true 时生成 480p 样片，其余参数遵循普通生成规则。不要在生成正片的请求中传入此字段。视频编辑（edit）不能生成样片。

string

已成功样片的 task_id，用于生成 1080p 正片。样片须在创建后 24 小时内用于生成正片。正片自动沿用样片的提示词、素材、时长和画幅，不得重复传入这些字段。生成正片时也不能传入 seed、audio 或其别名 generate_audio。

素材地址与组合限制

图片、视频和音频均支持公网 http(s) URL 或本平台私域素材 asset://<素材 ID>，都不接受 data: Base64；请先上传素材。平台会自动登记素材，无需额外调用素材接口；登记失败时任务失败，已扣费用自动退回。

素材	要求
参考图	最多 30 张；JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF；宽高比 0.4–2.5；宽、高均为 300–6000 像素；单张 `< 30 MB`。
参考视频	最多 10 段；MP4 / MOV（H.264 / H.265；音轨： AAC / MP3）；单段 `≤ 200 MB`。尺寸、时长和帧率要求见下方。
参考音频	最多 10 段；WAV / MP3；单段 2–15 秒、`≤ 15 MB`，合计不超过 30 秒。允许 ±0.2 秒误差：单段 `1.8 ≤ t ≤ 15.2` 秒、合计 `≤ 30.2` 秒。必须搭配参考图或参考视频。

参考视频校验规则

项目	要求
宽、高	宽、高各 300–6000 像素。
像素面积（宽 × 高）	409,600–8,295,044 像素。
宽高比（宽 / 高）	0.4–2.5。
单段时长	`auto` / `reference`：2–15 秒，允许范围 `1.8 ≤ t ≤ 15.2` 秒；`edit` 源视频：4–30 秒，允许范围 `3.8 ≤ t < 30.2` 秒。按精确时长检查，不先取整。
帧率	先四舍五入到整数，再判断是否在 24–60fps 之间；23.976 和 59.94 均符合。

视频宽高、像素面积、宽高比、精确时长和帧率，以及参考音频时长均在提交时校验；不符合时同步返回 HTTP 400，不扣费。视频规格错误使用 invalid_request_error，说明包含实测值。请按像素面积判断，不要用“短边至少 480、长边最多 4096”替代。仅看尺寸：420×1000（420,000 像素）符合要求；720×480（345,600 像素）、848×480（407,040 像素）和 4096×2160（8,847,360 像素）不符合面积要求。时长、帧率及其他素材条件仍须满足。图片尺寸、文件大小和编码在生成阶段校验；不符合时任务失败，已扣费用自动退回，建议调用前自行检查。

素材组合规则

image_urls 与 image_with_roles 不能同时传入，否则提交返回 HTTP 400（invalid_request_error），不扣费。image、images、image_url 这些别名也计入 image_urls，不能绕过此限制。
首尾帧与参考素材（参考图、参考视频、参考音频）不能出现在同一请求中。
首帧、尾帧各最多 1 张；尾帧必须配合首帧。
参考图最多 30 张、参考视频最多 10 段、参考音频最多 10 段，素材合计最多 50 个。
违反上述组合或数量限制时，提交同步返回 HTTP 400，不扣费。
omni_reference_task_type: "edit" 至少需要 1 段源视频（3.8 ≤ t < 30.2 秒）。duration / seconds 只能省略或传 -1，aspect_ratio / size 只能省略或传 adaptive，不能与 draft: true 同用。自动或参考模式的单段视频仍受 2–15 秒及相应误差范围限制。

以下字段只要出现在请求中就返回 HTTP 400，即使值为 ""、[]、false 或 null，也必须整个移除：negative_prompt、camera_fixed、camerafixed、extend_from_task_id、mask_url、video_list、element_list、multi_shot、tools。n 只能省略或传 1。

请求示例

以下素材 URL 为占位示例，请替换为实际可访问的素材地址。

首尾帧生视频

{
  "model": "apimart-zoe",
  "prompt": "镜头从首帧自然过渡到尾帧，保持光影连续",
  "image_with_roles": [
    {
      "url": "https://example.com/start.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/end.jpg",
      "role": "last_frame"
    }
  ],
  "duration": 6
}

也可用 first_frame_image 和 last_frame_image 提供首尾帧。不要在同一请求中再加入参考图、参考视频或参考音频。

图片、视频和音频参考

{
  "model": "apimart-zoe",
  "prompt": "参考图中的角色在参考视频的场景里自然运动，背景音乐与画面节奏一致",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "video_urls": [
    "https://example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://example.com/bgm.mp3"
  ],
  "duration": -1
}

image_urls 中的图片按参考图处理；duration: -1 表示由模型自动决定输出时长。

视频编辑

omni_reference_task_type: "edit" 至少需要 1 段源视频（3.8 ≤ t < 30.2 秒）。duration / seconds 只能省略或传 -1，aspect_ratio / size 只能省略或传 adaptive，不能与 draft: true 同用。自动或参考模式的单段视频仍受 2–15 秒及相应误差范围限制。

{
  "model": "apimart-zoe",
  "prompt": "把画面整体改成黑白老电影风格，保留原有的镜头运动和构图",
  "video_urls": [
    "https://example.com/source_20s.mp4"
  ],
  "omni_reference_task_type": "edit"
}

视频编辑按有参考视频的档位计费：先按 30 秒输出时长预扣，完成后将成片实际时长四舍五入到整秒结算，并计入参考视频时长，按下方公式多退少补。

返回尾帧、MOV 输出和提示词优化

{
  "model": "apimart-zoe",
  "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
  "duration": 5,
  "return_last_frame": true,
  "output_format": "mov",
  "enhance_prompt": true
}

样片 → 正片

提交样片：设置 draft: true。resolution 不传时自动使用 480p，传入时也只能是 480p。

{
  "model": "apimart-zoe",
  "prompt": "一只橙色小猫在窗台上看向镜头，阳光从侧面洒入，镜头缓缓推进",
  "draft": true
}

等待样片任务成功，然后使用它的 task_id 提交正片。只需传入 model 和 draft_task_id；如显式指定 resolution，只能为 1080p。

{
  "model": "apimart-zoe",
  "draft_task_id": "task_01KZOEEXAMPLE"
}

正片沿用样片的提示词、素材、时长、画幅、种子和音频设置。只传 model、draft_task_id，以及可选的 resolution: "1080p" 和 nsfw_check / webhook 等通用字段。以下生成字段禁止出现，空串、空数组、false、null 同样返回 HTTP 400：prompt、image_urls、image_with_roles、image、images、image_url、first_frame_image、last_frame_image、video_urls、audio_urls、duration、seconds、aspect_ratio、size、seed、audio、generate_audio、draft、omni_reference_task_type、return_last_frame、output_format、response_format、enhance_prompt。样片须在创建后 24 小时内用于生成正片；两次生成分别计费。

查询任务与结果

cURL

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KZOEEXAMPLE \
  --header 'Authorization: Bearer <token>'

提交响应中的 data 是数组；查询响应中的 data 是任务对象。使用 data.status 判断任务状态：pending 为排队中，processing 为生成中，completed 为成功，failed 为失败。成功后从 data.result.videos[].url 数组读取视频地址，例如 data.result.videos[0].url[0]。视频已转存到 APIMart 存储。下面仅展示查询成功时的关键字段。

{
  "code": 200,
  "data": {
    "id": "task_01KZOEEXAMPLE",
    "status": "completed",
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "expires_at": 1794475442
        }
      ],
      "last_frame_url": "https://example.com/generated-last-frame.png"
    },
    "progress": 100,
    "completed": 1794389042
  }
}

任务失败时，读取 data.error.message 获取原因；已扣费用自动退回。

字段	说明
`data.progress`	任务进度，0–100。
`data.result.videos[].url`	视频地址数组，已转存到 APIMart 存储。
`data.result.videos[].expires_at`	地址有效期为任务完成后 24 小时，请及时下载。
`data.result.last_frame_url`	PNG 尾帧图片地址，已转存到 APIMart 存储；仅任务成功且请求包含 `return_last_frame: true` 时出现。
`data.error.message`	任务失败时的原因，仅在 `failed` 时出现。
`data.error.code`	任务失败时为字符串 `task_failed`。
`data.cost`	本次费用；失败任务为 0，预扣费用已自动退回。

计费规则

按秒计费，单价按输出分辨率以及是否有参考视频分档，实际单价和账户优惠以价格页为准。下表中的 D 是计费所用的输出时长，单位为秒。

情况	输出计费时长 D
普通生成：指定 `duration: 4–30`，或省略（默认 5）	按请求秒数计费，完成后不按成片长度调整。
`duration: -1` / 视频编辑 `edit`	先按 30 秒预扣；完成后取成片实际时长，四舍五入到整数秒，多退少补。
正片	沿用样片时长；样片使用 `duration: -1` 时，以样片成片的实际时长为依据，不按正片成片长度重新调整。

参考视频总时长 R：提交时探测每段时长，相加后向下取整到整数秒，之后不再调整。
无参考视频：计费秒数 = D。有参考视频：计费秒数 = D + max(R, ceil(D × 2/3))，其中 ceil 表示向上取整；使用有参考视频对应的单价。
例如请求 8 秒，即使成片为 8.2 秒，D 仍为 8；自动时长成片为 8.5 秒时，D 为 9。两段参考视频为 2.8 秒和 3.8 秒时，先相加得到 6.6 秒，再向下取整，R 为 6。
样片按 480p 计费，正片按 1080p 计费，分别收取生成费用。样片带参考视频时，正片仍计入原参考视频时长，无需重复上传素材。
提交失败不扣费；任务失败时已扣费用自动退回。

常见错误

提交失败返回 error 对象，读取 error.message 获取说明、error.code 获取字符串业务错误码；HTTP 状态码与 error.code 不同。提交失败不扣费。

HTTP	`error.code`	场景与处理方式
400	`invalid_request_error`	检查时长、分辨率、比例、素材数量及组合、不支持的参数和样片正片限制；`draft_task_id` 不存在、不是样片、未完成或超过创建后 24 小时也会返回此错误。参考视频尺寸、精确时长或帧率不符合要求，以及混用 `image_urls`（含别名）与 `image_with_roles`，也返回此错误；视频规格错误说明中包含实测值。还应检查参考音频时长、任务类型与编辑约束、`output_format` 取值、音频别名是否一致，以及禁止字段是否仍出现在请求中。
400	`nsfw_content_detected`	内容审核命中，`error.message` 包含类别。按审核拒绝展示，调整内容后再提交；不扣费。
400	`input_video_probe_failed`	参考视频无法访问或探测不到时长，检查素材地址和内容。
402	`payment_required`	余额不足；自动时长会按 30 秒预扣。
503	`draft_channel_unavailable` / `draft_task_unavailable`	样片生成通道不可用或样片查询暂时失败，稍后重试或重新生成样片。

概览

模型

文字系列

图像系列

视频系列

音频系列

审核系列

上传管理

任务管理

账户管理

apimart-zoe 视频生成

模式选择

请求头

请求参数

素材地址与组合限制

参考视频校验规则

素材组合规则

请求示例

首尾帧生视频

图片、视频和音频参考

视频编辑

返回尾帧、MOV 输出和提示词优化

样片 → 正片

查询任务与结果

计费规则

常见错误

​模式选择

​请求头

​请求参数

​素材地址与组合限制

​参考视频校验规则

​素材组合规则

​请求示例

​首尾帧生视频

​图片、视频和音频参考

​视频编辑

​返回尾帧、MOV 输出和提示词优化

​样片 → 正片

​查询任务与结果

​计费规则

​常见错误

模式选择

请求头

请求参数

素材地址与组合限制

参考视频校验规则

素材组合规则

请求示例

首尾帧生视频

图片、视频和音频参考

视频编辑

返回尾帧、MOV 输出和提示词优化

样片 → 正片

查询任务与结果

计费规则

常见错误