---
url: /docs/timelines.zh.md
---
# TIMELINES API 接口文档

## 🌐 语言切换

[中文版](/docs/timelines.zh) | [English](/docs/timelines)

## 接口信息

```
POST /openapi/capcut-mate/v1/timelines
```

## 功能描述

根据指定的时长和数量创建时间线。该接口用于生成视频编辑所需的时间线配置，支持多种时间线类型和起始时间设置，为后续的素材添加和编辑提供时间参考。

## 请求参数

```json
{
  "duration": 10000000,
  "num": 3,
  "start": 0,
  "type": 0
}
```

### 参数说明

| 参数名 | 类型 |必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| duration | integer |✅ | - |总时长(微秒) |
| num | integer |✅ | - | 时间段数量 |
| start | integer |✅ | - |时间(微秒) |
| type | integer |✅ | - | 时间线类型：0 平均分，1 随机 |

### 参数详解

#### duration

* **类型**: integer
* **说明**:总时长，单位为微秒（1秒 = 1,000,000微秒）
* **示例**: 10000000 (10秒)

#### num

* **类型**: integer
* **说明**:需要创建的时间段数量
* **示例**: 3 (创建3个时间段)

#### start

* **类型**: integer
* **说明**: 时间线的起始时间，单位为微秒
* **示例**: 2000000 (从2秒开始)

#### type

* **类型**: integer
* **说明**: 时间线分割类型
* **可选值**:
  * 0 - 平均分时间线
  * 1 - 随机时间线
* **示例**: 0

## 响应格式

### 成功响应 (200)

```json
{
  "code": 0,
  "message": "success",
  "timelines": [
    {
      "start": 0,
      "end": 3333333
    },
    {
      "start": 3333333,
      "end": 6666666
    },
    {
      "start": 6666666,
      "end": 10000000
    }
  ],
  "all_timelines": [
    {
      "start": 0,
      "end": 10000000
    }
  ]
}
```

\###响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| timelines | array | 分段时间线数组 |
| all\_timelines | array |完整时间线数组 |
| start | number | 时间段开始时间(微秒) |
| end | number | 时间段结束时间(微秒) |

### 错误响应

```json
{
  "code": 1001,
  "message": "参数校验失败"
}
```

## 使用示例

### cURL 示例

#### 1.基本时间线创建

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/timelines \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 15000000,
    "num": 5,
    "start": 0,
    "type": 0
  }'
```

#### 2.带始时间的时间线

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/timelines \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 20000000,
    "num": 4,
    "start": 5000000,
    "type": 0
  }'
```

\##错误码说明

| 错误码 |错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 1001 | 参数校验失败 | 请求体未通过字段校验（`duration`/`num`/`start`/`type` 缺失或不是整数） | 检查参数类型与必填字段 |

## 注意事项

1. **时间单位**:所有时间参数使用微秒（1秒 = 1,000,000微秒）
2. **参数要求**: duration、num、start、type 均为必填参数
3. **时间范围**: `all_timelines` 覆盖 `start` 到 `start + duration`，分段时间线均在该范围内生成
4. **类型选择**:根据实际需求选择合适的时间线类型
5. **精度考虑**:微秒级别的时间精度适合精确的视频编辑

\##工作流程

1.验证必填参数（duration, num, start, type）
2.检查参数类型（整数）
3.根据type类型计算时间线分割方式
4\. 生成分段时间线数组
5\. 生成完整时间线数组
6\. 返回时间线配置结果

\##相关接口

* [创建草稿](/docs/create_draft)
* [音频时间线](/docs/audio_timelines)
* [视频信息](/docs/video_infos)
* [图片信息](/docs/imgs_infos)

***

📚 **项目资源**\
**GitHub**: <https://github.com/Hommy-master/capcut-mate>\
**Gitee**: <https://gitee.com/taohongmin-gitee/capcut-mate>

### 语言切换

[中文版](/docs/timelines.zh) | [English](/docs/timelines)