视频生成

这页能做什么

你可以提交一段文字或一张首帧图，生成视频任务，再用任务 ID 查询进度和结果。

前置条件

已有 LokoSpace API Key，请求头使用 Authorization: Bearer <你的 LokoSpace API Key>
账号积分足够支付本次生成
模型出现在 GET /videos/models 的返回里。看不到某个模型，说明它未上架、未配置按秒定价，或对应渠道不可用
文生视频和图生视频的能力要与模型匹配。传 image_url 就是图生视频，不传就是文生视频
请求体使用 Content-Type: application/json

可用模型

curl https://sheverai.com/8811c8/api/llm/v1/videos/models \
  -H "Authorization: Bearer $LOKO_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "<视频模型 ID>",
      "object": "model",
      "owned_by": "lokospace",
      "display_name": "示例视频模型",
      "billing_mode": "per_second",
      "credits_per_second": "<最低每秒积分>",
      "min_billing_seconds": 1,
      "default_duration_seconds": 5,
      "pricing": [
        {
          "resolution": "720P",
          "credits_per_second": "<720P 每秒积分>",
          "min_billing_seconds": 1
        }
      ]
    }
  ]
}

字段	类型	说明
`object`	string	固定为 `list`
`data`	array	可用视频模型
`data[].id`	string	请求体里的 `model`
`data[].object`	string	固定为 `model`
`data[].owned_by`	string	固定为 `lokospace`
`data[].display_name`	string	展示名称
`data[].billing_mode`	string	视频固定为 `per_second`
`data[].credits_per_second`	number	该模型最低的每秒积分价
`data[].min_billing_seconds`	integer	最短计费秒数
`data[].default_duration_seconds`	integer \| null	未传 `duration` 时的默认时长
`data[].pricing`	array	按分辨率拆分的价格档位
`data[].pricing[].resolution`	string \| null	档位名；`null` 表示不区分分辨率
`data[].pricing[].credits_per_second`	number	该档位每秒积分
`data[].pricing[].min_billing_seconds`	integer	该档位最短计费秒数

credits_per_second 只用于快速比较。实际扣费按请求匹配到的 pricing 档位和计费秒数计算。

调用示例

curl https://sheverai.com/8811c8/api/llm/v1/videos/generations \
  -H "Authorization: Bearer $LOKO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-20261022-001" \
  -d '{
    "model": "<视频模型 ID>",
    "prompt": "雨夜街道，镜头缓慢推进",
    "duration": 5.5,
    "aspect_ratio": "16:9",
    "resolution": "720P"
  }'

字段	类型	必填	说明
`model`	string	是	取自 `/videos/models`，最长 100 字符
`prompt`	string	是	画面描述，最长 32000 字符
`image_url`	string	否	首帧或参考图，必须是 http(s) 地址，最长 2048 字符
`duration`	number	否	时长秒数，可带小数，最大 120。不传时用模型默认值
`aspect_ratio`	string	否	画面比例，如 `16:9`、`9:16`。具体支持范围由模型决定
`resolution`	string	否	分辨率档位，取自 `pricing[].resolution`
`Idempotency-Key`	string	否	请求头。建议传，用于防重复扣费和任务重放

duration 不传时，依次使用模型默认时长、default_duration_seconds，最后兜底 5 秒。

返回示例

提交成功通常立即返回任务 ID，状态为 queued：

{
  "id": "<视频任务 ID>",
  "status": "queued",
  "lokospace_billing": {
    "requestId": "<请求 ID>",
    "creditsUsed": "<本次扣除积分>",
    "balanceAfter": "<扣除后余额>",
    "duplicate": false
  }
}

如果上游同步完成，会直接返回 completed 和 url。

提交成功时响应带 x-lokospace-request-id 和 x-lokospace-credits-used。

查询任务：

curl "https://sheverai.com/8811c8/api/llm/v1/videos/generations/<视频任务 ID>" \
  -H "Authorization: Bearer $LOKO_KEY"

处理中：

{
  "id": "<视频任务 ID>",
  "status": "processing",
  "progress": 40
}

完成：

{
  "id": "<视频任务 ID>",
  "status": "completed",
  "url": "https://cdn.example.com/generated/video.mp4"
}

失败：

{
  "id": "<视频任务 ID>",
  "status": "failed",
  "error": "视频生成失败"
}

字段	类型	说明
`id`	string	任务 ID，32 位十六进制字符串
`status`	string	`queued`、`processing`、`completed` 或 `failed`
`progress`	integer	进度百分比，可能缺省
`url`	string	视频地址，仅在 `completed` 时返回
`error`	string	失败原因，仅在 `failed` 时返回
`lokospace_billing`	object	仅提交接口返回，查询接口不返回

计费说明

视频按 per_second 计费。计费秒数 = ceil(max(duration, min_billing_seconds))，总价 = 每秒积分 × 计费秒数。

例如 duration 为 5.5 秒、最短计费 1 秒时，按 6 秒计费。不同分辨率可能有不同单价。

单价从 model_pricing 读取，文档不写死具体价格，以 GET /models 返回为准；调用前也可以用 GET /videos/models 查看各档位单价。

1 元 = 100 积分。服务端先扣费再提交上游；上游立即失败或后续查询到失败都会退款。相同幂等键重试返回同一任务，不会重复扣费。

错误与常见问题

状态	含义	处理
400	参数不合法，如任务 ID 格式错误、模型不支持当前模式、`image_url` 不是 http(s)	按返回的 `message` 修正
401	密钥缺失、无效、已撤销或已过期	重新创建或更换密钥
402	积分不足	充值后重试。响应里的 `available_credits` 是可用余额
404	模型不存在，或任务不存在	重新拉取 `/videos/models`；任务 ID 要与创建时一致
429	上游模型服务并发或频率受限	退避后重试。视频入口没有单独限流
502	上游模型服务生成失败、没有返回任务 ID，或模型队列排队超时	稍后重试；生成失败会自动退款，查询失败可重试查询
503	没有可用的按秒定价，或渠道凭证不可用	联系管理员检查模型定价与渠道

常见问题：

为什么提交后只拿到 queued？视频是异步任务，用返回的 id 轮询查询接口。建议每 5 到 10 秒查一次。
服务端会自动轮询吗？会，后台默认每 10 秒查一次，最多 30 分钟，但只在当前 Node 进程存活时运行。进程重启后，需要客户端再次查询才会继续。
任务一直不完成怎么办？超过 2 小时仍未完成，会在查询时按失败处理并退款。
相同幂等键会创建第二个任务吗？不会，返回的是同一个任务状态。需要新任务时换一个幂等键。

开发者文档