LocoPal AiLocoPal Ai

API 文档

视频生成 API

视频任务创建、多图与参考视频提交、任务查询、状态和错误响应

接口路径、认证方式、参数与任务状态说明

视频生成 API

视频生成采用异步任务。创建成功后保存响应中的 id，再通过查询接口读取进度和结果。一次创建请求只对应一个任务；查询和页面刷新不会重复创建或重复计费。

接口概览

用途方法路径
创建视频任务POST/v1/video/generations
查询视频任务GET/v1/video/generations/{task_id}

基础地址为 https://locopalai.com。两个接口都使用模型 API Key：

Authorization: Bearer sk-your-api-key
Content-Type: application/json

API Key 可在“API 密钥”页面创建。模型 ID 必须来自当前 Key 调用 GET /v1/models 得到的 data[].id。

创建视频任务

POST https://locopalai.com/v1/video/generations

提交文生视频、图生视频、首尾帧或多模态参考视频任务。创建成功表示任务已受理，不表示视频已经生成完成。

请求体 · application/json

参数类型必填说明
modelstring是当前 API Key 可用的视频模型 ID。
contentobject[]条件文本和参考素材列表。多图、首尾帧、参考视频或音频使用此字段。
promptstring条件简单文生视频提示词；使用 content 时可省略。
imagestring否单张参考图兼容字段。复杂引用优先使用 content。
imagesstring[]否多张普通参考图兼容字段。需要指定角色时使用 content。
resolutionstring否输出清晰度，例如 480p、720p、1080p，以模型详情为准。
ratiostring否输出比例，例如 16:9、9:16、1:1、adaptive。
durationinteger否视频时长，单位秒；可用档位以模型详情为准。
framesinteger否视频帧数；部分模型支持，与 duration 二选一。
seedinteger否随机种子；支持范围以模型详情为准。
generate_audioboolean否是否生成同步声音。
draftboolean否是否使用样片模式，仅在模型明确支持时传入。
callback_urlstring否任务状态回调地址，仅在模型明确支持时传入。
return_last_frameboolean否是否在结果中返回尾帧。
watermarkboolean否是否添加水印。
camera_fixedboolean否是否固定摄像头。
service_tierstring否服务等级，仅在模型详情明确支持时传入。
priorityinteger否任务优先级，仅在模型详情明确支持时传入。

prompt 与 content 至少提供一种有效文本输入。不要向模型传入详情页未声明支持的参数。

content 元素

type内容字段role说明
texttext省略文本提示词。
image_urlimage_url.urlreference_image普通参考图，可提交多张。
image_urlimage_url.urlfirst_frame视频首帧。
image_urlimage_url.urllast_frame视频尾帧。
video_urlvideo_url.urlreference_video动作、运镜、节奏或画面参考视频。
audio_urlaudio_url.urlreference_audio声音或节奏参考。

公网素材必须使用可直接下载的 HTTPS URL，不能依赖 Cookie、Referer 或登录页面。图片也可以按模型支持情况使用 data:image/...;base64,...。素材库中状态为 Active 的素材使用 asset://<ASSET_ID>。

文生视频示例

curl -X POST "https://locopalai.com/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "available-video-model-id",
    "content": [
      {
        "type": "text",
        "text": "雨后的城市街道，镜头从水面倒影缓慢抬升，电影感"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true,
    "watermark": false
  }'

单图生视频示例

{
  "model": "available-video-model-id",
  "content": [
    { "type": "text", "text": "人物自然转身，衣摆随风摆动，镜头轻微环绕" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://cdn.example.com/person.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

首尾帧示例

首帧和尾帧必须分别标记 first_frame 与 last_frame，并使用两份不同图片。

{
  "model": "available-video-model-id",
  "content": [
    { "type": "text", "text": "镜头从室内平滑移动到窗外城市夜景" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://cdn.example.com/first.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://cdn.example.com/last.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

多图 + 深度视频提交示例

“深度视频”作为参考视频提交：type 使用 video_url，role 使用 reference_video。每张参考图各占一个 content 元素，不能把多个 URL 放进一个 image_url.url。

curl -X POST "https://locopalai.com/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "available-seedance-model-id",
    "content": [
      {
        "type": "text",
        "text": "以图片1的人物为主体，沿用图片2的服装，参考视频的动作节奏和运镜，保持人物身份与产品外观一致。"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://cdn.example.com/person.png" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "asset://asset-product-id" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://cdn.example.com/style.jpg" }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": { "url": "https://cdn.example.com/motion.mp4" }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": { "url": "https://cdn.example.com/music.mp3" }
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true,
    "watermark": false
  }'

参考图片数量、参考视频、参考音频、输出分辨率和时长由模型能力决定。提交前在模型广场查看所选模型详情。

创建响应参数

字段类型说明
idstring公开任务 ID，查询任务时使用。
task_idstring与 id 相同的兼容字段。
objectstring固定为 video。
modelstring本次请求使用的模型 ID。
statusstring创建成功时为 queued。
progressinteger当前进度，范围 0 至 100。
created_atinteger任务创建时间，Unix 秒。

创建响应体 200

{
  "id": "task-public-id",
  "task_id": "task-public-id",
  "object": "video",
  "model": "available-seedance-model-id",
  "status": "queued",
  "progress": 0,
  "created_at": 1788868800
}

客户端应优先保存 id。收到 200 和任务 ID 后，即使本地等待超时，也只查询原任务，不应自动重新创建。

查询视频任务

GET https://locopalai.com/v1/video/generations/{task_id}

路径参数

参数类型必填说明
task_idstring是创建响应中的 id。

请求示例

curl -X GET "https://locopalai.com/v1/video/generations/task-public-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

响应参数

字段类型说明
idstring公开任务 ID。
task_idstring与 id 相同的兼容字段。
objectstringvideo。
modelstring视频模型 ID。
statusstringqueued、in_progress、completed、failed 或 unknown。
progressinteger当前进度，范围 0 至 100。
created_atinteger创建时间，Unix 秒。
completed_atinteger任务完成时间，未完成时省略。
metadata.urlstring生成视频地址，成功时返回。
error.codestring失败错误码，仅失败时返回。
error.messagestring失败原因，仅失败时返回。

执行中响应体 200

{
  "id": "task-public-id",
  "task_id": "task-public-id",
  "object": "video",
  "model": "available-seedance-model-id",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1788868800
}

成功响应体 200

{
  "id": "task-public-id",
  "task_id": "task-public-id",
  "object": "video",
  "model": "available-seedance-model-id",
  "status": "completed",
  "progress": 100,
  "created_at": 1788868800,
  "completed_at": 1788868920,
  "metadata": {
    "url": "https://cdn.example.com/result.mp4"
  }
}

失败响应体 200

{
  "id": "task-public-id",
  "task_id": "task-public-id",
  "object": "video",
  "model": "available-seedance-model-id",
  "status": "failed",
  "progress": 100,
  "created_at": 1788868800,
  "completed_at": 1788868815,
  "error": {
    "code": "InvalidParameter",
    "message": "The parameter content[1].image_url is not valid"
  }
}

状态处理

状态客户端处理
queued任务已进入队列，继续查询同一个任务 ID。
in_progress正在生成，更新进度和等待时间，不创建新任务。
completed读取 metadata.url 并及时下载或转存。
failed展示一次 error.code 与 error.message，由用户决定是否重新提交。
unknown暂时无法判断状态，保留任务 ID 后稍后查询。

客户端不应使用固定等待秒数判断完成，也不应因一次网络超时重复创建任务。

错误响应

创建请求在未受理时会返回标准错误对象：

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "content"
  }
}
HTTP常见原因处理
400JSON、模型参数或参考素材格式错误修正请求后重新提交。
401API Key 缺失、失效或无权使用更换有效 Key。
429额度或请求频率受限按响应提示等待，避免重复提交。
500任务创建或查询失败读取错误码和消息；已有任务 ID 时继续查询原任务。
503当前模型暂不可用重新查询 /v1/models，切换可用模型或稍后再试。

参考素材下载失败

错误若指向 content[n].image_url、video_url 或 resource download failed，先按数组下标定位具体元素，再检查：

  1. URL 能否从公网直接 GET 并返回 200。
  2. 是否跳转到登录页或依赖 Cookie、Referer、IP 白名单。
  3. Content-Type 是否与文件真实格式一致。
  4. 临时签名 URL 是否在下载和处理期间仍有效。
  5. asset:// 素材是否属于当前账户且状态为 Active。
  6. 当前模型是否支持该素材类型和数量。

修正素材后重新创建任务。错误信息只需向用户显示一次可读原因，不要把多层转义 JSON 重复拼接展示。

并发、重试与计费

  • 不同视频任务可以并发创建。
  • 同一创建响应必须使用同一个任务 ID 查询。
  • 只有任务明确失败并且用户主动重试时，才发起新的创建请求。
  • 新尝试的等待时间从新任务创建时重新计算。
  • 价格可能按模型、分辨率、时长和参考视频输入细分，以模型广场和最终账单为准。

API 概览

认证、通用约定、模型列表与文本生成接口

素材库 API

AccessKey 签名、虚拟素材入库、单个状态查询与真人扫码授权完整格式

本页目录

视频生成 API接口概览创建视频任务请求体 · application/jsoncontent 元素文生视频示例单图生视频示例首尾帧示例多图 + 深度视频提交示例创建响应参数创建响应体 200查询视频任务路径参数请求示例响应参数执行中响应体 200成功响应体 200失败响应体 200状态处理错误响应参考素材下载失败并发、重试与计费