# 智能剪辑-口播混剪 API Documentation

> 口播混剪：音频/素材 + 模板生成成片（create/query/config）；按分辨率×输入秒计费

## Overview

This document describes how to call the **智能剪辑-口播混剪** API.

- **Model / path slug**: `smartclip/broadcast_mixcut`
- **Task type**: `async` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/26`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `POST https://apis.xiaobao.ink/api/smartclip/broadcast_mixcut`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `POST`

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `styleId` | Yes | 模板ID（必填） |
| `materials` | Yes | 素材数组（必填） |
| `audioUrl` | Yes | 音频URL（优先用于探测计费） |
| `resolution` | Yes | 720p\|1080p（默认720p） |
| `callback_url` | Yes | 用户回调（create必填） |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/smartclip/broadcast_mixcut?key=你的密钥&action=create
```

## Details

## 多规格计费：

720P 3（≈￥0.030） 点/输入秒，1080P 4（≈￥0.040） 点/输入秒

| 规格 | 价格 |
| --- | --- |
| 720P | 3（≈￥0.030） 点/输入秒 |
| 1080P | 4（≈￥0.040） 点/输入秒 |

计费公式：`ceil(输入秒) × 对应规格单价`。有 `audioUrl` 时探测音频时长；否则汇总 `materials`（图片按 2 秒）。 可通过参数 `resolution`（720p / 1080p，默认 720p）指定输出规格。无法解析有效输入媒体时长时请求会被拒绝。

## URL 参数 action：

通过 URL 参数 `action` 区分操作：

- `create` — 创建任务（POST JSON）

- `query` — 查询任务（GET/POST，需 `task_id`）

- `config` — 获取配置（GET，不扣点）

## create 请求示例 URL：

`http://test.xiaobao.ink/api/smartclip/broadcast_mixcut?key=你的密钥&action=create`

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json |

**鉴权说明：**请在 URL 参数或 JSON Body 中携带 `key`（平台 API 密钥）。使用 POST + JSON 时，`key` 必须写在 JSON Body 内。

## create 请求参数说明（POST JSON）：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| key | 是 | string | 你的密钥 | 平台 API 密钥 |
| styleId | 是 | string | 68aebb91b8619ed6f4168f40 | 视频模板 ID |
| materials | 是 | array | [{type,fileUrl,soundSwitch}] | 素材列表，至少 1 项 |
| audioUrl | 否 | string | https://example.com/a.mp3 | 音频 URL（mp3/wav/m4a），与 content 二选一；有音频时优先按音频时长计费 |
| resolution | 否 | string | 720p | 输出规格：720p / 1080p，影响单价 |
| content | 否 | string |  | 文本内容（3-1800 字）；当前平台不支持 content+speakerId 定制声音分支 |
| callback_url | 是 | string | https://example.com/hook | 用户回调地址 |
| title | 否 | string |  | 标题 |
| language | 否 | string | zh-CN | 音频语种 |
| subtitle | 否 | array |  | 字幕数组 |
| introduceCard | 否 | object |  | 身份栏 |
| packRules | 否 | object |  | 包装规则 |
| processRules | 否 | object |  | 水印、首帧封面等 |
| structLayers | 否 | array |  | 图层修改 |

## 视频生成方式：

参考文档支持两种方式：

| 方式 | 字段 | 说明 |
| --- | --- | --- |
| 文本内容 + 定制声音 | content + speakerId | 文本字符数要求 3-1800，声音 ID 为定制声音产生的声音 ID |
| 音频文件 | audioUrl | 音频时长小于 5 分钟，格式 mp3、wav、m4a，文件大小小于等于 100MB，需要能够语音转文本 |

当前平台应用仅支持 `audioUrl` 或素材输入链路，不支持 `content + speakerId` 定制声音分支。若传入 `content` 或 `speakerId`，平台会返回 `unsupported_speaker_branch`。

## speakerExtra：

| 字段 | 类型 | 必填 | 默认值 / 范围 | 说明 |
| --- | --- | --- | --- | --- |
| speedRatio | number | 否 | 默认 1，范围 0.5-2 | 语速，支持 1 位小数，1 表示常速，例如 0.6、0.9、1.2 |
| language | string | 否 | - | 语种，特指该克隆声音文本（content）支持的语种 |
| marks | array | 否 | - | 文本标记特殊处理处，传 content 时有效 |
| marks[].type | string | 是 | break | 标记类型，break 表示停顿 |
| marks[].index | integer | 是 | 从 0 开始 | 文本索引处，最大值为 content 文本长度 |
| marks[].time | integer | 是 | 100-10000 | 时长，单位 ms |

## processRules：

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| watermarkShow | boolean | 否 | false | 是否添加“AI生成”字样水印 |
| metadata | object | 否 | - | 元水印数据，仅支持写入一组数据，且 value 值需为字符串 |
| firstFrameCover | object | 否 | - | 首帧封面配置 |

## 重要规则：

- 音频驱动的 `audioUrl`、素材 `materials[].fileUrl`、背景音乐 `packRules.backgroundMusic.audioUrl`、AI 封面的 `resultImageUrl` 地址不能重名，重名会导致渲染异常。

- `packRules` 仅用于控制标题、字幕、素材、背景音乐、关键词等图层是否参与效果包装，不能控制对应图层的显示/隐藏。

- 如果期望生成的视频不显示标题，请不要设置标题值。

- `callback_url` / `callbackUrl` 作为平台任务通知地址保存，任务完成或失败后由平台发起通知。

- 如无法解析有效输入媒体时长，本次请求会被拒绝，不使用默认时长。

## 通用对象字段：

**subtitle[]**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| startMs | integer | 是 | 时间戳开始，单位 ms |
| endMs | integer | 是 | 时间戳结束，单位 ms，最大支持 310000ms |
| text | string | 是 | 文本，只支持单字符级别 |

**materials[]**

| 字段 | 类型 | 必填 | 可选值 / 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| type | string | 是 | image / video | 素材类型 |
| fileUrl | string | 是 | - | 素材 url |
| soundSwitch | boolean | 否 | false | 当素材为视频时原声开关，素材混剪和新闻体视频支持 |

**introduceCard**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 否 | 名称 |
| description | string | 否 | 描述 |

**packRules**

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| headerSwitch | boolean | 否 | - | 标题包装开关 |
| materialSwitch | boolean | 否 | - | 素材包装开关 |
| subtitleSwitch | boolean | 否 | - | 字幕包装开关 |
| keywordSwitch | boolean | 否 | - | 关键词包装开关 |
| backgroundMusic | object | 否 | - | 背景音乐设置 |
| backgroundMusic.audioSwitch | boolean | 否 | - | 音乐开关 |
| backgroundMusic.audioUrl | string | 否 | - | 音频 url，模板内置背景音乐和传递 audioUrl，优先使用 audioUrl |
| backgroundMusic.volume | number | 否 | 0.3 | 音量，保留一位小数，范围 0-1 |

**processRules.firstFrameCover**

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| coverSwitch | boolean | 否 | false | 封面开关 |
| templateId | string | 否 | - | 模版 ID，如果未设置则系统匹配 |
| imageUrl | string | 否 | - | 图片地址，用于生成 AI 封面图的底图，imageUrl 和 resultImageUrl 二选一必填 |
| resultImageUrl | string | 否 | - | 图片生成接口的结果图片地址或其他封面图片地址；传了此值将直接运用作为视频首帧封面，优先级更高 |

**structLayers[]**

| 字段 | 类型 | 必填 | 可选值 | 说明 |
| --- | --- | --- | --- | --- |
| markCode | string | 是 | headerLayer / subtitleLayer / ipLayer / backgroundLayer / figureLayer | 图层，对应模板详情接口返回的图层数据 |
| show | boolean | 否 | - | 是否显示，不设置时默认跟随模板；backgroundLayer、figureLayer 不支持设置，默认显示 |
| showMode | string | 否 | always / customize | 显示模式，markCode=headerLayer 时生效，不设置时默认跟随模板 |
| showTime | number | 条件必填 | 大于 0 | 显示时长，markCode=headerLayer 且 showMode=customize 时生效且必填，保留 3 位小数 |
| layer.transform.position | integer[] | 否 | - | 锚点定位，对应模板详情 transform.position |
| layer.uri | string | 否 | - | 背景图片资源链接，仅 backgroundLayer 生效 |

## 素材与媒体要求：

- 输入视频格式：mp4、mov；视频编码 h264、HEVC(h265)；帧率 10-60fps，推荐 25；单边分辨率小于 2000px。

- 真人口播 videoUrl 时长小于 5 分钟，文件大小小于 500MB，视频中的音频需要能够语音转文本。

- 素材总量限制：单张图片计算为 2 秒，单个视频素材不能超过 60 秒，所有素材总时长不能超过 5 分钟。

- 素材图片格式支持 jpg、png、webp 静态图，单边分辨率小于 2000px。

- 素材视频格式支持 mp4、mov，单个视频小于 500MB，单边分辨率小于 2000px。

- 背景音乐格式支持 mp3、wav、m4a，文件大小不超过 120MB，时长不超过 5 分钟。

- 首帧封面 `imageUrl`、`resultImageUrl` 格式支持 jpg/jpeg、png，文件大小不超过 10MB，单边分辨率小于 2000px。

## query / 回调：

query 需 `task_id`；回调字段同真人口播接口。

## 响应字段：

| 字段 | 类型 | 必返 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 是 | 平台任务 ID |
| status | string / int | 是 | 平台任务状态：上游多为 processing / queued；本平台 create/query 返回 1 处理中、2 完成、3 失败 |
| app | string | 是 | 应用编码，固定为 smart_clip（上游 data；本平台见 upstream 透传） |
| api | string | 是 | API 编码，固定为 broadcast_mixcut（上游 data；本平台见 upstream 透传） |

## 任务结果：

任务完成后，平台任务查询结果 / 用户回调中的结果通常包含：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| video_url | string | 视频 url 地址，视频生成类任务返回 |
| cover_url | string | 视频封面 url 地址 |
| duration | number | 生成的视频或音频时长，单位：秒 |
| data | object | 完整结果数据 |

任务失败时返回错误码和错误描述（本平台字段为 `fail_reason`）。

## Response Example

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "task_id": "task_8b4125d2a045655f7b4d69d4",
        "status": 1,
        "progress": 0,
        "power_cost": 150
    }
}
```

## Error Codes

| Status / code | Description |
|---------------|-------------|
| 200 / success | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed, please check API Key |
| 402 | Insufficient account balance / points |
| 429 | Request rate limit exceeded |
| 500 | Internal server error |

## Usage Flow

1. **Create Task**: Call this API with your `key` and required parameters
2. **Get Task ID**: Read the task id from the response
3. **Wait for Results**: Use the notify/callback URL if provided, or poll the related query endpoint
4. **Get Results**: When the task succeeds, read result URLs / payload from the response

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._