> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# apimart-zoe 视频生成

> 支持文生视频、首尾帧、图片/视频/音频参考及视频编辑，输出 480p 至 4k，支持尾帧图片、MOV 和样片转正片。

> [!NOTE]
>
> 本接口采用异步处理。提交后读取 `data[0].task_id`，再通过 [获取任务状态](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 查询结果。通常需要 1–3 分钟，建议每 5–10 秒查询一次，实际耗时以任务状态为准。

```bash cURL theme={null}
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
  }'
```

```python Python theme={null}
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())
```

```javascript JavaScript theme={null}
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());
```

```json 200 theme={null}
{
  "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 段源视频，输出时长和画幅跟随源视频。 |

## 请求头

**Authorization** `string` *required*

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

## 请求参数

**model** `string` *required*

固定为 `apimart-zoe`。

**prompt** `string`

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

**resolution** `string`

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

**aspect\_ratio** `string`

支持 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`。默认 `adaptive`，由模型或素材决定。生成正片时禁止传入，沿用样片画幅。

视频编辑（`edit`）时只能省略或传 `adaptive`，画幅跟随源视频。

**size** `string`

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

**duration** `integer`

普通生成：整数秒 `4`–`30`，默认 `5`。指定时长或使用默认值时，按该秒数计费，完成后不按成片长度调整。传 `-1` 时由模型决定时长：提交时按 30 秒预扣，完成后将成片实际时长四舍五入到整数秒，再多退少补。生成正片时禁止传入，沿用样片时长。

视频编辑（`edit`）时只能省略或传 `-1`；省略时自动按 `-1` 处理，输出时长跟随源视频。

**seconds** `integer`

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

**audio** `boolean`

是否同时生成音频，类型为布尔值；别名为 `generate_audio`。省略时由模型决定。生成正片时禁止传入。此字段控制输出音频，与输入参考音频 `audio_urls` 不同。

`audio` 与 `generate_audio` 同时传入时，值必须相同，否则返回 HTTP 400。省略时通常会生成声音，具体由模型决定。

**generate\_audio** `boolean`

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

`audio` 与 `generate_audio` 同时传入时，值必须相同，否则返回 HTTP 400。省略时通常会生成声音，具体由模型决定。

**seed** `integer`

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

**nsfw\_check** `boolean`

默认不审核；设置 `true` 才启用。

可选布尔值，设为 `true` 时启用内容审核。审核范围为提示词 `prompt`、`image_urls`、`image_with_roles`、首尾帧图片，以及 `asset://` 图片素材；参考视频和参考音频不送审。

正片请求不携带提示词和素材，样片 → 正片流程的审核在生成样片时进行。

命中时返回 HTTP 400（`nsfw_content_detected`），`error.message` 包含命中类别；应按审核拒绝展示，不按普通参数错误处理。审核服务异常或调用失败时，生成请求会继续提交，因此开启此参数不保证每次请求都完成审核。

**omni\_reference\_task\_type** `string`

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

**return\_last\_frame** `boolean`

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

**output\_format** `string`

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

**response\_format** `string`

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

**enhance\_prompt** `boolean`

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

**image\_with\_roles** `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`，不能绕过此限制。

**image\_urls** `string[]`

参考图数组，最多 30 张。格式、尺寸和大小限制见下方素材要求。

`image_urls` 与 `image_with_roles` 不能同时传入，否则提交返回 HTTP 400（`invalid_request_error`），不扣费。`image`、`images`、`image_url` 这些别名也计入 `image_urls`，不能绕过此限制。

**first\_frame\_image** `string`

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

**last\_frame\_image** `string`

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

**video\_urls** `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` 秒。按精确时长检查，不先取整。

**audio\_urls** `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，不扣费。

**draft** `boolean`

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

视频编辑（`edit`）不能生成样片。

**draft\_task\_id** `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 秒及相应误差范围限制。

> [!WARNING]
>
> 以下字段只要出现在请求中就返回 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 为占位示例，请替换为实际可访问的素材地址。

### 首尾帧生视频

```json theme={null}
{
  "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` 提供首尾帧。不要在同一请求中再加入参考图、参考视频或参考音频。

### 图片、视频和音频参考

```json theme={null}
{
  "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 秒及相应误差范围限制。

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

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

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

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

## 样片 → 正片

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

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

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

```json theme={null}
{
  "model": "apimart-zoe",
  "draft_task_id": "task_01KZOEEXAMPLE"
}
```

> [!WARNING]
>
> 正片沿用样片的提示词、素材、时长、画幅、种子和音频设置。只传 `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 小时内用于生成正片；两次生成分别计费。

## 查询任务与结果

```bash cURL theme={null}
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 存储。下面仅展示查询成功时的关键字段。

```json theme={null}
{
  "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，预扣费用已自动退回。 |

## 计费规则

按秒计费，单价按输出分辨率以及是否有参考视频分档，实际单价和账户优惠以 [价格页](https://apimart.ai/pricing) 为准。下表中的 `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` | 样片生成通道不可用或样片查询暂时失败，稍后重试或重新生成样片。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.