跳转到主要内容
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.0",
    "prompt": "一个小女孩走在路上，电影感画面",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

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

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.0",
    "prompt": "一个小女孩走在路上，电影感画面",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

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

​
认证

​
Authorization
string
必填
所有接口均需要使用 Bearer Token 进行认证获取 API Key：访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加：
Authorization: Bearer YOUR_API_KEY

​
模式路由

happyhorse-1.0 是文生视频 / 图生视频 / 参考图生视频 / 视频编辑的统一入口，后端根据传入参数自动判断模式，所有模式按统一规则计费（仅按分辨率 × 秒）：
你传的字段路由到模式说明
仅 prompt文生视频（T2V）纯文字描述生成视频
prompt + first_frame_image图生视频（I2V）以图为首帧动起来
prompt + image_urls（1~9 张）参考图生视频（R2V）一组参考图生成全新画面
prompt + video_url（可选 image_urls 0~5 张作风格参考 / audio_setting）视频编辑（EDIT）对源视频进行改写/风格化
路由优先级（从高到低）：video_url > first_frame_image > image_urls > 仅 prompt。 字段互斥规则：三个媒体字段（first_frame_image / image_urls / video_url）两两互斥，唯一例外是 video_url + image_urls（EDIT 模式 + 参考图）是合法组合。同时传两个互斥字段会返回 400 mixed_media_not_allowed。

​
请求参数

​
model
string
必填
视频生成模型名称，固定为 happyhorse-1.0
​
prompt
string
视频内容描述，最多 2500 字符，不能包含特殊 token
  • T2V / R2V / EDIT 模式：必填
  • I2V 模式：可选，但建议填写以指导运镜和动作
示例："一个小女孩走在路上，电影感画面"
​
first_frame_image
string
首帧图片，触发 I2V（图生视频）。支持 URL 或 base64（data:image/<mime>;base64,<payload>，网关自动转储到 OSS）与 image_urls / video_url 互斥
首帧图片要求：
  • 格式：JPEG / JPG / PNG / BMP / WEBP
  • 短边像素：≥ 300px
  • 宽高比：1:2.5 ~ 2.5:1
  • 大小：≤ 10MB
​
image_urls
array<string>
图片数组：
  • R2V 模式（仅传 image_urls）：1~9 张，作为主体/风格参考生成全新画面
  • EDIT 模式（同时传 video_url）：0~5 张，作为风格参考图
支持 URL 或 base64与 first_frame_image 互斥；可与 video_url 同时使用
参考图要求：
  • 格式：JPEG / JPG / PNG / BMP / WEBP
  • 短边像素：推荐 ≥ 720p
  • 宽高比：短边 / 长边 ≥ 0.4
  • 大小：≤ 10MB
  • 数量：R2V 必须 1~9 张；EDIT 最多 5 张
​
video_url
string
源视频 URL，触发 EDIT（视频编辑）。暂不支持 base64，请提供 HTTP/HTTPS 直链与 first_frame_image 互斥；可与 image_urls（≤ 5 张）同时使用
源视频要求：
  • 时长：3 ~ 60 秒（> 15s 上游自动从 0 截到 15s）
  • 分辨率：最小 480p，短边 ≥ 360
  • 宽高比：1:8 ~ 8:1
  • 格式：MP4 / MOV（建议 H.264 编码）
  • 帧率：> 8 fps
  • 大小：≤ 100MB
EDIT 模式下生成视频的时长与源视频一致（源视频 > 15s 时按截取后的 15s 计算），此时 duration 参数不生效。如需控制输出时长，请先自行将源视频裁剪到目标长度后再上传。
​
audio_setting
string
默认值:"auto"
音频设置，仅 EDIT 模式生效（必须同时传 video_url）可选值：
  • auto - 自动生成音频（默认）
  • origin - 保留原视频音轨
在非 EDIT 模式下传该字段会返回 400 audio_setting_only_for_edit
​
resolution
string
默认值:"1080P"
视频分辨率（影响计费）可选值：
  • 720P - 标清
  • 1080P - 高清（默认）
​
duration
integer
默认值:"5"
视频时长（秒，影响计费）支持范围：3 ~ 15 的任意整数默认值：5
EDIT 模式（传入 video_url）下此参数不生效：生成视频的时长与源视频保持一致（源视频 > 15s 时按截取后的 15s 计费）。如需控制输出时长，请先自行裁剪源视频。
​
size
string
默认值:"16:9"
画面宽高比支持的格式：
  • 16:9 - 横版宽屏（默认）
  • 9:16 - 竖版长屏
  • 1:1 - 正方形
  • 4:3 - 横版
  • 3:4 - 竖版
I2V / EDIT 模式下此参数会被忽略，输出宽高比由输入媒体（首帧图 / 源视频）自动决定
​
watermark
boolean
默认值:"true"
是否在生成的视频上添加水印
  • true：添加水印（默认）
  • false：不添加水印
​
seed
integer
随机种子，用于控制生成内容的随机性取值范围：[0, 2147483647]，省略则随机
  • 相同的请求下，模型收到不同的 seed 值（如：不指定 seed 值），将生成不同的结果
  • 相同的请求下，模型收到相同的 seed 值，会生成类似的结果，但不保证完全一致

​
响应

​
code
integer
响应状态码，成功时为 200
​
data
array
返回数据数组

​
使用场景

​
场景 1：文生视频 T2V（最简请求）

{
  "model": "happyhorse-1.0",
  "prompt": "一个小女孩走在路上，电影感画面"
}

​
场景 2：文生视频 T2V（完整参数）

{
  "model": "happyhorse-1.0",
  "prompt": "夕阳下的海边公路，慢镜头推进，电影感画面",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "watermark": false,
  "seed": 42
}

​
场景 3：图生视频 I2V（first_frame_image）

{
  "model": "happyhorse-1.0",
  "prompt": "让图片中的场景动起来",
  "first_frame_image": "https://example.com/first_frame.png",
  "resolution": "1080P",
  "duration": 5
}

​
场景 4：参考图生视频 R2V（多张参考图）

{
  "model": "happyhorse-1.0",
  "prompt": "图1中的主角在图2的场景中奔跑，随后拿起图3中的道具。画面保持3D卡通风格，动作流畅。",
  "image_urls": [
    "https://example.com/img_01.jpg",
    "https://example.com/img_02.png",
    "https://example.com/img_03.jpeg"
  ],
  "resolution": "1080P",
  "size": "16:9",
  "duration": 5,
  "watermark": false
}

​
场景 5：视频编辑 EDIT（保留原音轨 + 风格参考）

{
  "model": "happyhorse-1.0",
  "prompt": "把视频中的角色换成卡通风格，保留原有动作",
  "video_url": "https://example.com/source.mp4",
  "image_urls": [
    "https://example.com/style_ref.jpg"
  ],
  "resolution": "1080P",
  "audio_setting": "origin",
  "seed": 42
}

​
场景 6：720P 节省额度

{
  "model": "happyhorse-1.0",
  "prompt": "海浪拍打沙滩，日落时分",
  "resolution": "720P",
  "size": "16:9",
  "duration": 5
}

​
模式选择建议

需求推荐方式
纯文字描述生成视频仅传 prompt（T2V）
让图片”动起来”（以图为首帧）传 first_frame_image（I2V）
用一组参考图生成全新画面传 image_urls（1~9 张，R2V）
对已有视频改写 / 风格化传 video_url（EDIT），可叠加 image_urls 0~5 张做风格参考
节省额度指定 resolution: "720P"

​
使用建议

  1. 统一入口逻辑：根据传入字段自动路由模式，注意三个媒体字段（first_frame_image / image_urls / video_url）两两互斥
  2. size 仅 T2V/R2V 生效：I2V / EDIT 模式下 size 会被忽略，输出宽高比由输入媒体决定
  3. 时长建议：5~10 秒为甜点区，过短动作不连贯，过长上游耗时显著增加
  4. 首帧图片质量：清晰、构图明确、主体居中，能显著提升 I2V 效果
  5. prompt 写作：描述运动 / 镜头 / 氛围（如 “缓慢推近、电影感、暖色调”），比单纯描述静态场景效果更好
  6. EDIT 输入视频：> 15 秒会被上游自动从 0 秒截取到 15 秒，需要其他片段请先自行切片
查询任务结果视频生成为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。