# 智能剪辑-真人口播 API Documentation

> 真人口播混剪：上传真人视频 + 模板生成成片（create/query/config）；按分辨率×输入秒计费

## Overview

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

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

## 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/realman_broadcast`
- **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（必填） |
| `videoUrl` | Yes | 真人视频URL（必填，探测时长计费） |
| `resolution` | Yes | 720p\|1080p（默认720p） |
| `callback_url` | Yes | 用户回调（create必填） |
| `title` | Yes | 标题 |
| `language` | Yes | 语种 |
| `materials` | Yes | 素材数组 |
| `subtitle` | Yes | 字幕数组 |
| `packRules` | Yes | 包装规则 |
| `processRules` | Yes | 处理规则 |
| `structLayers` | Yes | 图层修改 |

> **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/realman_broadcast?key=你的密钥&action=create
```

## Details

## 多规格计费：

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

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

计费公式：`ceil(输入秒) × 对应规格单价`。输入秒取自 `videoUrl` 媒体探测时长。 可通过参数 `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/realman_broadcast?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（来自模板列表 id） |
| videoUrl | 是 | string | https://example.com/a.mp4 | 真人视频 URL，mp4/mov，时长 |
| resolution | 否 | string | 720p | 输出规格：720p / 1080p，影响单价 |
| callback_url | 是 | string | https://example.com/hook | 任务完成/失败后平台回调你的地址（也支持 callbackUrl / notify） |
| title | 否 | string | 聊AI行业 | 标题；不显示标题则不要传 |
| language | 否 | string | zh-CN | 视频语种（ASR 用） |
| materials | 否 | array | [{type,fileUrl}] | 素材列表，type=image\|video |
| materialSoundSwitch | 否 | bool | false | 素材为视频时是否保留原声 |
| subtitle | 否 | array | [{startMs,endMs,text}] | 字幕/ASR 结果 |
| introduceCard | 否 | object | {name,description} | 身份栏 |
| packRules | 否 | object |  | 标题/素材/字幕/关键词/背景音乐包装开关 |
| processRules | 否 | object |  | 水印、预处理 roughCut/sliceMerge 等 |
| structLayers | 否 | array |  | 修改 headerLayer/subtitleLayer 等图层 |

## 特殊字段说明：

**subtitle（字幕信息）**
选填，不设置则由系统智能处理。
如果期望手动修改从视频中识别的文字，可以先调用音频转文字（ASR）接口识别出文本信息，更改其中的文字，然后保持 ASR 返回的格式设置到该字段。

**processRules.resourcePreprocessMethod（真人视频预处理方式）**
选填，不设置真人视频预处理方式时，默认保持原始视频时长。
`roughCut`：粗剪，按照系统内置规则智能处理，例如自动去掉无声片段等。
`sliceMerge`：按照 subtitle 字段中标注的开始/结束时间，自动去掉不连续时间范围的片段。

## processRules：

| 字段 | 类型 | 必填 | 默认值 | 可选值 / 范围 | 说明 |
| --- | --- | --- | --- | --- | --- |
| watermarkShow | boolean | 否 | false | true / false | 是否添加“AI生成”字样水印 |
| resourcePreprocessMethod | string | 否 | - | sliceMerge / roughCut | 真人视频预处理方式，不设置时默认保持原始视频时长 |
| materialMatchWay | string | 否 | preciseMatch | fuzzyMatch / preciseMatch | 素材匹配方式 |
| metadata | object | 否 | - | - | 元水印数据，仅支持写入一组数据，且 value 值需为字符串 |
| firstFrameCover | object | 否 | - | - | 首帧封面配置 |

## 重要规则：

- 视频驱动的 `videoUrl`、素材 `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 请求参数：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| action | 是 | string | query | URL 参数 |
| key | 是 | string | 你的密钥 | 平台 API 密钥 |
| task_id | 是 | string | task_xxx | create 返回的任务 ID |

## create 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 200 成功 |
| data.task_id | string | 任务 ID |
| data.status | int | 1 处理中；2 完成；3 失败 |
| data.progress | int | 进度 0-100 |
| data.resolution | string | 计费规格 |
| data.bill_seconds | int | 计费输入秒（ceil） |
| data.points_per_second | float | 该规格单价（点/输入秒） |
| data.power_cost | float | 本次扣点数 |

## 用户回调参数（POST 到你的 callback_url）：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| task_id | string | 任务 ID |
| status | int | 2 成功；3 失败 |
| video_url | string | 成片地址（成功时） |
| fail_reason | string | 失败原因（失败时） |

## 响应字段：

| 字段 | 类型 | 必返 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 是 | 平台任务 ID |
| status | string / int | 是 | 平台任务状态：上游多为 processing / queued；本平台 create/query 返回 1 处理中、2 完成、3 失败 |
| app | string | 是 | 应用编码，固定为 smart_clip（上游 data；本平台见 upstream 透传） |
| api | string | 是 | API 编码，固定为 realman_broadcast（上游 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_6139c79459b9594a32f4737b",
        "status": 1,
        "progress": 0,
        "api_type": "realman_broadcast",
        "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}`)._