返回首页
目录
1. 概述2. 认证方式3. 通用说明3.1 Base URL3.2 请求格式3.3 响应格式3.4 字段说明4. 文件上传4.1 获取预签名上传地址4.2 上传文件5. 提交视频生成任务请求参数Prompt 引用素材语法请求示例成功响应6. 查询任务状态路径参数请求示例成功响应响应字段任务状态说明轮询建议7. 任务列表查询参数请求示例成功响应响应字段8. 余额查询请求示例成功响应响应字段9. 计费说明9.1 计费模式9.2 并发额度9.3 积分体系10. 错误码10.1 业务错误码10.2 系统错误码10.3 任务失败错误码10.4 错误响应示例11. 完整接入示例11.1 Python：上传图片 + 图生视频11.2 Python：纯文本生成视频11.3 cURL：完整流程附录A. 接口一览B. 常见问题

剧火 Open API 文档

版本：v1  |  最后更新：2026-04-08

1. 概述

剧火 Open API 提供视频生成能力的程序化接口。通过该接口，您可以：

  • 上传素材：将图片或视频文件上传至剧火云存储
  • 提交生成任务：基于文本描述、参考图片或参考视频生成短视频
  • 查询任务进度：轮询任务状态，获取生成结果

典型流程：

上传素材（可选） → 提交生成任务 → 轮询任务状态 → 获取视频 URL

2. 认证方式

所有 API 请求必须在 HTTP Header 中携带 API Key 进行身份认证。

Header 格式：

Authorization: Bearer <api_key>

API Key 规则：

属性说明
格式sk- + 32 位字母数字字符串
获取方式联系管理员开通并获取
示例sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

请求示例：

bash
curl https://api.juhuo.cn/open-api/v1/video/tasks   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

注意：请妥善保管您的 API Key，不要将其暴露在前端代码或公开仓库中。

3. 通用说明

3.1 Base URL

https://api.juhuo.cn

3.2 请求格式

  • Content-Type：application/json
  • 字符编码：UTF-8
  • HTTP 方法：各接口单独指定

3.3 响应格式

所有接口返回统一的 JSON 结构：

成功响应：

json
{
  "code": "200",
  "message": "Success",
  "result": { ... }
}

错误响应：

json
{
  "code": "4000",
  "message": "参数错误：duration范围为4-15"
}

3.4 字段说明

字段类型说明
codestring状态码，"200" 表示成功，其他值表示具体错误
messagestring状态描述，成功时为 "Success"
resultobject业务数据，错误时可能为 null

4. 文件上传

在提交生成任务前，如果需要使用参考图片或参考视频，需先通过预签名接口获取上传地址，再使用 HTTP PUT 将文件上传至云存储。

4.1 获取预签名上传地址

POST /open-api/v1/upload/presign

请求参数

字段类型必填说明
fileNamestring是文件名（含扩展名）
contentTypestring是文件的 MIME 类型

fileName 规则

  • 仅允许英文字母、数字、下划线 _、短横线 - 和点号 .
  • 正则：^[a-zA-Z0-9_-]+.[a-zA-Z0-9]+$
  • 最大长度：128 字符
  • 示例：scene1.png、my-video_01.mp4

contentType 允许值

类型contentType对应扩展名
图片image/png.png
图片image/jpeg.jpg .jpeg
图片image/webp.webp
视频video/mp4.mp4
视频video/quicktime.mov
视频video/webm.webm

文件扩展名必须与 contentType 匹配，否则会返回错误。

请求示例

bash
curl -X POST https://api.juhuo.cn/open-api/v1/upload/presign   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"   -H "Content-Type: application/json"   -d '{
    "fileName": "scene1.png",
    "contentType": "image/png"
  }'

成功响应

json
{
  "code": "200",
  "message": "Success",
  "result": {
    "uploadUrl": "https://oss.example.com/api/user123/upload/scene1.png?signature=xxx&expires=yyy",
    "ossKey": "api/user123/upload/scene1.png",
    "method": "PUT"
  }
}

响应字段

字段类型说明
uploadUrlstring预签名上传地址（有效期有限，请尽快使用）
ossKeystring文件在云存储中的唯一标识，提交任务时需要引用
methodstring上传 HTTP 方法，固定为 "PUT"

4.2 上传文件

获取预签名地址后，使用 HTTP PUT 直接上传文件：

bash
curl -X PUT "https://oss.example.com/api/user123/upload/scene1.png?signature=xxx&expires=yyy"   -H "Content-Type: image/png"   --data-binary @./scene1.png

注意：

  • 上传时的 Content-Type 须与获取预签名时的 contentType 一致
  • 预签名地址有效期有限，获取后请尽快上传
  • 上传完成后，使用返回的 ossKey 在生成任务中引用该文件

5. 提交视频生成任务

POST /open-api/v1/video/submit

请求参数

字段类型必填默认值说明
promptstring是-视频生成提示词
modelstring否seedance-2.0模型选择
soundstring否on是否生成音效
durationint否8视频时长（秒）
resolutionint否480视频分辨率
aspectRatiostring否9:16画面比例
inputImagesarray<object>否-参考图片列表
inputVideosarray<object>否-参考视频列表

参数详细说明

model 可选值：

值说明
seedance-2.0标准模型（默认）
seedance-2.0-fast快速模型

sound 可选值： on（开启）、off（关闭）

duration 取值范围： 4 ~ 15（整数，单位：秒）

resolution 可选值：

modelresolution 可选值
seedance-2.0480、720、1080
seedance-2.0-fast480、720

aspectRatio 可选值： 9:16、16:9、3:4、4:3、1:1、21:9

inputImages 数组元素：

字段类型说明
namestring图片名称，在 prompt 中通过 <<<name>>> 引用
ossKeystring上传接口返回的 ossKey

inputVideos 数组元素：

字段类型说明
namestring视频名称，在 prompt 中通过 <<<name>>> 引用
ossKeystring上传接口返回的 ossKey

Prompt 引用素材语法

在 prompt 中使用 <<<素材名称>>> 引用已上传的图片或视频：

一只猫从 <<<Image 1>>> 中走出来，走进 <<<Image 2>>> 的场景中

对应的 inputImages：

json
[
  { "name": "Image 1", "ossKey": "api/.../cat.png" },
  { "name": "Image 2", "ossKey": "api/.../room.png" }
]

请求示例

文本生成视频：

bash
curl -X POST https://api.juhuo.cn/open-api/v1/video/submit   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"   -H "Content-Type: application/json"   -d '{
    "prompt": "一只橘猫在樱花树下奔跑，阳光洒落，画面温暖治愈",
    "model": "seedance-2.0",
    "duration": 8,
    "resolution": 1080,
    "aspectRatio": "16:9"
  }'

图片参考生成视频：

bash
curl -X POST https://api.juhuo.cn/open-api/v1/video/submit   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"   -H "Content-Type: application/json"   -d '{
    "prompt": "<<<Image 1>>> 中的角色缓缓转身，微风吹动发丝",
    "inputImages": [
      {
        "name": "Image 1",
        "ossKey": "api/user123/upload/character.png"
      }
    ],
    "duration": 10,
    "resolution": 720,
    "aspectRatio": "9:16"
  }'

成功响应

json
{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "gen_abc123def456"
  }
}

6. 查询任务状态

GET /open-api/v1/video/task/{taskId}

路径参数

参数类型说明
taskIdstring任务 ID

请求示例

bash
curl https://api.juhuo.cn/open-api/v1/video/task/gen_abc123def456   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

成功响应

json
{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "gen_abc123def456",
    "status": "success",
    "outputUrl": "https://cdn.example.com/output/video.mp4?token=xxx",
    "coverUrl": "https://cdn.example.com/output/cover.jpg?token=xxx",
    "errorCode": "",
    "errorMsg": "",
    "creditCost": 1.15,
    "gmtCreate": 1712534400000
  }
}

响应字段

字段类型说明
taskIdstring任务 ID
statusstring任务状态（见下方状态表）
outputUrlstring生成视频的下载地址（成功时返回，签名有效期 7 天）
coverUrlstring视频封面图地址（成功时返回，签名有效期 7 天）
errorCodestring错误码（失败时返回）
errorMsgstring错误描述（失败时返回）
creditCostnumber本次任务消耗的积分（成功后结算）
gmtCreatelong任务创建时间（Unix 毫秒时间戳，东八区）

任务状态说明

状态说明是否终态
queued排队等待中否
init初始化中否
uploading素材上传至生成平台中否
submitted已提交生成平台否
generating视频生成中否
downloading结果下载中否
success生成成功是
fail生成失败是

轮询建议

  • 建议轮询间隔：5 ~ 10 秒
  • 当 status 为 success 或 fail 时停止轮询
  • 生成时间通常在 1 ~ 5 分钟，视时长和分辨率而定

7. 任务列表

GET /open-api/v1/video/tasks

分页查询当前用户的所有 API 生成任务。

查询参数

参数类型必填默认值说明
pageNoint否1页码（从 1 开始）
pageSizeint否20每页数量

请求示例

bash
curl "https://api.juhuo.cn/open-api/v1/video/tasks?pageNo=1&pageSize=10"   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

成功响应

json
{
  "code": "200",
  "message": "Success",
  "result": {
    "data": [
      {
        "taskId": "gen_abc123def456",
        "status": "success",
        "outputUrl": "https://cdn.example.com/output/video.mp4?token=xxx",
        "coverUrl": "https://cdn.example.com/output/cover.jpg?token=xxx",
        "errorCode": "",
        "errorMsg": "",
        "creditCost": 1.15,
        "gmtCreate": 1712534400000
      }
    ],
    "total": 42,
    "pageNo": 1,
    "pageSize": 10
  }
}

响应字段

字段类型说明
dataarray<object>任务列表，每项结构同「查询任务状态」
totalint总任务数
pageNoint当前页码
pageSizeint每页数量

8. 余额查询

GET /open-api/v1/account/balance

查询当前 API Key 关联账户的积分余额。

请求示例

bash
curl https://api.juhuo.cn/open-api/v1/account/balance   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

成功响应

json
{
  "code": "200",
  "message": "Success",
  "result": {
    "totalCredits": 10000.00,
    "usedCredits": 3250.50,
    "remainCredits": 6749.50
  }
}

响应字段

字段类型说明
totalCreditsnumber账户总积分
usedCreditsnumber已消耗积分
remainCreditsnumber剩余可用积分

9. 计费说明

9.1 计费模式

API 采用后付费模式：任务成功完成后才扣除积分，失败的任务不扣费。

9.2 并发额度

系统根据账户累计充值金额自动调整最大并行任务数：

累计充值金额最大并发数
1.5W ~ 4.9W8
5W10
10W20
15W30
20W40
25W50
  • 并发数指同时处于生成中的任务上限，超出部分自动排队

9.3 积分体系

  • API 积分与 Web 端积分相互独立
  • API 积分仅用于 Open API 调用
  • 充值请联系管理员

10. 错误码

10.1 业务错误码

错误码说明常见原因
4000参数错误请求参数缺失、格式不正确或值不在允许范围内
4003积分余额不足API 积分账户余额为零或不足
4004资源不存在任务 ID 不存在或不属于当前用户
4009资源冲突重复创建（如用户已存在 API Key）
4403未授权API Key 缺失、格式错误或已失效

10.2 系统错误码

错误码说明处理建议
5000服务器内部错误请稍后重试，如持续出现请联系管理员
5003服务繁忙请稍后重试

10.3 任务失败错误码

任务状态为 fail 时，errorCode 可能包含以下值：

errorCode说明
PAYLOAD_PARSE_ERROR任务参数解析失败
UPLOAD_FAILED素材上传至生成平台失败
SUBMIT_FAILED提交生成平台失败
PIPELINE_TIMEOUT生成超时
TRANSFER_FAILED结果文件传输失败

10.4 错误响应示例

json
{
  "code": "4000",
  "message": "duration范围为4-15"
}
json
{
  "code": "4403",
  "message": "未授权"
}

11. 完整接入示例

11.1 Python：上传图片 + 图生视频

python
import requests
import time

API_BASE = "https://api.juhuo.cn"
API_KEY = "sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def upload_file(file_path, file_name, content_type):
    """步骤 1：获取预签名地址并上传文件"""
    # 获取预签名上传地址
    resp = requests.post(
        f"{API_BASE}/open-api/v1/upload/presign",
        headers=headers,
        json={"fileName": file_name, "contentType": content_type},
    )
    resp.raise_for_status()
    data = resp.json()["result"]

    upload_url = data["uploadUrl"]
    oss_key = data["ossKey"]

    # 上传文件
    with open(file_path, "rb") as f:
        put_resp = requests.put(
            upload_url,
            headers={"Content-Type": content_type},
            data=f,
        )
        put_resp.raise_for_status()

    print(f"上传成功: {oss_key}")
    return oss_key


def submit_image_to_video(oss_key, image_name="Image 1"):
    """步骤 2：提交图生视频任务"""
    resp = requests.post(
        f"{API_BASE}/open-api/v1/video/submit",
        headers=headers,
        json={
            "prompt": f"<<<{image_name}>>> 中的人物缓缓转身，微风吹动发丝，电影感镜头",
            "model": "seedance-2.0",
            "duration": 8,
            "resolution": 480,
            "aspectRatio": "16:9",
            "inputImages": [{"name": image_name, "ossKey": oss_key}],
        },
    )
    resp.raise_for_status()
    task_id = resp.json()["result"]["taskId"]
    print(f"任务已提交: {task_id}")
    return task_id


def poll_task(task_id, interval=5, timeout=600):
    """步骤 3：轮询任务状态"""
    elapsed = 0
    while elapsed < timeout:
        resp = requests.get(
            f"{API_BASE}/open-api/v1/video/task/{task_id}",
            headers=headers,
        )
        resp.raise_for_status()
        task = resp.json()["result"]

        status = task["status"]
        print(f"[{elapsed}s] 状态: {status}")

        if status == "success":
            print(f"生成成功！")
            print(f"  视频地址: {task['outputUrl']}")
            print(f"  封面地址: {task['coverUrl']}")
            print(f"  消耗积分: {task['creditCost']}")
            return task

        if status == "fail":
            print(f"生成失败: [{task['errorCode']}] {task['errorMsg']}")
            return task

        time.sleep(interval)
        elapsed += interval

    print("轮询超时")
    return None


# 主流程
if __name__ == "__main__":
    # 1. 上传图片
    oss_key = upload_file("./character.png", "character.png", "image/png")

    # 2. 提交生成任务
    task_id = submit_image_to_video(oss_key)

    # 3. 轮询等待结果
    result = poll_task(task_id)

11.2 Python：纯文本生成视频

无需上传素材，直接提交任务即可：

python
import requests
import time

API_BASE = "https://api.juhuo.cn"
API_KEY = "sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 提交文本生成视频任务
resp = requests.post(
    f"{API_BASE}/open-api/v1/video/submit",
    headers=headers,
    json={
        "prompt": "浩瀚星空下，一艘宇宙飞船缓缓驶过土星光环，镜头跟随飞船移动，画面壮观震撼",
        "model": "seedance-2.0",
        "sound": "on",
        "duration": 10,
        "resolution": 720,
        "aspectRatio": "21:9",
    },
)
resp.raise_for_status()
task_id = resp.json()["result"]["taskId"]
print(f"任务已提交: {task_id}")

# 轮询任务状态
while True:
    resp = requests.get(
        f"{API_BASE}/open-api/v1/video/task/{task_id}",
        headers=headers,
    )
    task = resp.json()["result"]
    print(f"状态: {task['status']}")

    if task["status"] == "success":
        print(f"视频地址: {task['outputUrl']}")
        break
    elif task["status"] == "fail":
        print(f"失败: {task['errorMsg']}")
        break

    time.sleep(8)

11.3 cURL：完整流程

bash
# 步骤 1：获取上传地址
curl -X POST https://api.juhuo.cn/open-api/v1/upload/presign   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"   -H "Content-Type: application/json"   -d '{"fileName": "scene.png", "contentType": "image/png"}'

# 步骤 2：上传文件（使用步骤 1 返回的 uploadUrl）
curl -X PUT "<uploadUrl>"   -H "Content-Type: image/png"   --data-binary @./scene.png

# 步骤 3：提交生成任务（使用步骤 1 返回的 ossKey）
curl -X POST https://api.juhuo.cn/open-api/v1/video/submit   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"   -H "Content-Type: application/json"   -d '{
    "prompt": "<<<Image 1>>> 中的场景逐渐活过来，花朵盛开，蝴蝶飞舞",
    "inputImages": [{"name": "Image 1", "ossKey": "<ossKey>"}],
    "duration": 8,
    "aspectRatio": "16:9"
  }'

# 步骤 4：查询任务状态（使用步骤 3 返回的 taskId）
curl https://api.juhuo.cn/open-api/v1/video/task/<taskId>   -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

附录

A. 接口一览

方法路径说明
POST/open-api/v1/upload/presign获取预签名上传地址
POST/open-api/v1/video/submit提交视频生成任务
GET/open-api/v1/video/task/{taskId}查询任务状态
GET/open-api/v1/video/tasks任务列表（分页）
GET/open-api/v1/account/balance查询积分余额

B. 常见问题

Q：API Key 无效怎么办？ A：请确认 Key 以 sk- 开头，并检查是否有多余的空格。如果 Key 已被禁用，请联系管理员。

Q：任务一直处于 queued 状态？ A：说明当前并行任务数已达上限。等待正在运行的任务完成后，排队任务会自动开始。也可能是积分余额不足导致暂停。

Q：上传返回的 ossKey 有效期是多久？ A：ossKey 本身长期有效，可在后续多次任务中复用。但 uploadUrl（预签名地址）有时效限制，请在获取后尽快上传。

Q：生成的视频地址有效期？ A：outputUrl 和 coverUrl 为签名链接，有效期 7 天。过期后可重新调用任务查询接口获取新的签名链接。