# CAPTION_INFOS API Documentation

## 🌐 Language Switch
[中文版](./caption_infos.zh.md) | [English](./caption_infos.md)

## Interface Information

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

## Function Description

Build a caption-info JSON string from text list + timelines. The result can be passed directly to `add_captions` as `captions`. Supports font size, keyword highlight (color/border/size/shadow), intro/loop/outro animations, and transition fields.

## Request Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| texts | array[string] | ✅ | - | Caption text list; one item per caption |
| timelines | array[object] | ✅ | - | Timeline list, index-aligned with `texts` |
| timelines[].start | integer | ✅ | - | Caption start time (µs), must be `>= 0` |
| timelines[].end | integer | ✅ | - | Caption end time (µs), must be greater than `start` |
| font_size | integer | ❌ | `null` | Normal text size written into each caption; omitted from output if not provided |
| keyword_color | string | ❌ | `null` | Keyword color (hex), written into each caption |
| keyword_border_color | string | ❌ | `null` | Keyword stroke color (hex), written into each caption |
| keyword_font | string | ❌ | `null` | Keyword font name, written into each caption |
| keyword_font_size | integer | ❌ | `null` | Keyword font size, written into each caption |
| keyword_has_shadow | boolean | ❌ | `null` | Whether to enable keyword shadow, written into each caption |
| keyword_shadow_info | object | ❌ | `null` | Keyword shadow params (same fields as `add_captions.shadow_info`) |
| keywords | array[string] | ❌ | `null` | Keyword list assigned by index to `texts[i]`; missing indexes get empty `keyword` |
| in_animation | string | ❌ | `null` | Intro animation name, e.g. `"向上滑动"` |
| in_animation_duration | integer | ❌ | `null` | Intro duration (µs) |
| loop_animation | string | ❌ | `null` | Loop animation name, e.g. `"弹幕滚动"` |
| loop_animation_duration | integer | ❌ | `null` | Single-loop duration (µs) |
| out_animation | string | ❌ | `null` | Outro animation name, e.g. `"向下滑动"` |
| out_animation_duration | integer | ❌ | `null` | Outro duration (µs) |
| transition | string | ❌ | `null` | Transition name written into generated infos |
| transition_duration | integer | ❌ | `null` | Transition duration (µs) |

### keyword_shadow_info Fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| shadow_alpha | number | ❌ | `1.0` | Shadow opacity `[0, 1]` |
| shadow_color | string | ❌ | `"#000000"` | Shadow color (hex) |
| shadow_diffuse | number | ❌ | `15.0` | Diffuse amount `[0, 100]` |
| shadow_distance | number | ❌ | `5.0` | Distance `[0, 100]` |
| shadow_angle | number | ❌ | `-45.0` | Angle `[-180, 180]` |

### Notes

1. If `texts` and `timelines` lengths differ, the shorter length is used (no hard error).
2. `keywords[i]` becomes caption `i`'s `keyword`; shorter `keywords` yields empty string for remaining items.
3. Optional fields are written into output only when not `null`.

## Fully Annotated Request Example

`//` comments are documentation-only and are **not** valid in a real request body.

```js
{
  // [Required] Caption texts, one per item
  "texts": [
    "Welcome to the CapCut tutorial",
    "This is a caption example"
  ],

  // [Required] Timelines, index-aligned with texts
  "timelines": [
    {
      "start": 0,                 // [Required] first caption start (µs)
      "end": 3000000              // [Required] first caption end (µs)
    },
    {
      "start": 3000000,           // [Required] second caption start (µs)
      "end": 6000000              // [Required] second caption end (µs)
    }
  ],

  "font_size": 24,                // [Optional] normal text size
  "keyword_color": "#FF5500",     // [Optional] keyword color
  "keyword_border_color": "#000000", // [Optional] keyword stroke color
  "keyword_font": "思源中宋",          // [Optional] keyword font
  "keyword_font_size": 28,        // [Optional] keyword font size
  "keyword_has_shadow": true,     // [Optional] enable keyword shadow
  "keyword_shadow_info": {        // [Optional] keyword shadow details
    "shadow_alpha": 0.85,         // opacity [0,1]
    "shadow_color": "#000000",    // shadow color
    "shadow_diffuse": 18.0,       // diffuse [0,100]
    "shadow_distance": 6.0,       // distance [0,100]
    "shadow_angle": -45.0         // angle [-180,180]
  },
  "keywords": [                   // [Optional] keywords assigned by index
    "CapCut",
    "caption"
  ],
  "in_animation": "向上滑动",      // [Optional] intro animation
  "in_animation_duration": 500000, // [Optional] intro duration (µs)
  "loop_animation": "弹幕滚动",    // [Optional] loop animation
  "loop_animation_duration": 1000000, // [Optional] single-loop duration (µs)
  "out_animation": "向下滑动",     // [Optional] outro animation
  "out_animation_duration": 500000, // [Optional] outro duration (µs)
  "transition": "淡入淡出",        // [Optional] transition name
  "transition_duration": 300000   // [Optional] transition duration (µs)
}
```

## Response Format

### Success Response (200)

```json
{
  "code": 0,
  "message": "success",
  "infos": "[{\"start\":0,\"end\":3000000,\"text\":\"Welcome to the CapCut tutorial\",\"keyword\":\"CapCut\",\"keyword_color\":\"#FF5500\",\"keyword_border_color\":\"#000000\",\"keyword_font\":\"思源中宋\",\"keyword_font_size\":28,\"keyword_has_shadow\":true,\"keyword_shadow_info\":{\"shadow_alpha\":0.85,\"shadow_color\":\"#000000\",\"shadow_diffuse\":18.0,\"shadow_distance\":6.0,\"shadow_angle\":-45.0},\"font_size\":24,\"in_animation\":\"向上滑动\",\"in_animation_duration\":500000,\"loop_animation\":\"弹幕滚动\",\"loop_animation_duration\":1000000,\"out_animation\":\"向下滑动\",\"out_animation_duration\":500000,\"transition\":\"淡入淡出\",\"transition_duration\":300000},{\"start\":3000000,\"end\":6000000,\"text\":\"This is a caption example\",\"keyword\":\"caption\",\"keyword_color\":\"#FF5500\",\"keyword_border_color\":\"#000000\",\"keyword_font\":\"思源中宋\",\"keyword_font_size\":28,\"keyword_has_shadow\":true,\"keyword_shadow_info\":{\"shadow_alpha\":0.85,\"shadow_color\":\"#000000\",\"shadow_diffuse\":18.0,\"shadow_distance\":6.0,\"shadow_angle\":-45.0},\"font_size\":24,\"in_animation\":\"向上滑动\",\"in_animation_duration\":500000,\"loop_animation\":\"弹幕滚动\",\"loop_animation_duration\":1000000,\"out_animation\":\"向下滑动\",\"out_animation_duration\":500000,\"transition\":\"淡入淡出\",\"transition_duration\":300000}]"
}
```

### Response Field Description

| Field | Type | Description |
|-------|------|-------------|
| infos | string | Caption info JSON string; usable as `add_captions.captions` |

### Error Response

```json
{
  "code": 1001,
  "message": "Parameter validation failed"
}
```

## Usage Examples

### cURL Examples

#### 1. Full-parameter request (all required + optional fields)

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Welcome to the CapCut tutorial", "This is a caption example"],
    "timelines": [
      {"start": 0, "end": 3000000},
      {"start": 3000000, "end": 6000000}
    ],
    "font_size": 24,
    "keyword_color": "#FF5500",
    "keyword_border_color": "#000000",
    "keyword_font": "思源中宋",
    "keyword_font_size": 28,
    "keyword_has_shadow": true,
    "keyword_shadow_info": {
      "shadow_alpha": 0.85,
      "shadow_color": "#000000",
      "shadow_diffuse": 18.0,
      "shadow_distance": 6.0,
      "shadow_angle": -45.0
    },
    "keywords": ["CapCut", "caption"],
    "in_animation": "向上滑动",
    "in_animation_duration": 500000,
    "loop_animation": "弹幕滚动",
    "loop_animation_duration": 1000000,
    "out_animation": "向下滑动",
    "out_animation_duration": 500000,
    "transition": "淡入淡出",
    "transition_duration": 300000
  }'
```

**Full-parameter meanings:**

| Parameter | Example | Meaning |
|-----------|---------|---------|
| texts | `["Welcome to the CapCut tutorial", "This is a caption example"]` | [Required] Two caption texts |
| timelines[0].start / end | `0` / `3000000` | [Required] First caption time range (µs) |
| timelines[1].start / end | `3000000` / `6000000` | [Required] Second caption time range (µs) |
| font_size | `24` | [Optional] Normal text size |
| keyword_color | `#FF5500` | [Optional] Keyword color |
| keyword_border_color | `#000000` | [Optional] Keyword stroke color |
| keyword_font | `思源中宋` | [Optional] Keyword font |
| keyword_font_size | `28` | [Optional] Keyword font size |
| keyword_has_shadow | `true` | [Optional] Enable keyword shadow |
| keyword_shadow_info.shadow_alpha | `0.85` | [Optional] Keyword shadow opacity |
| keyword_shadow_info.shadow_color | `#000000` | [Optional] Keyword shadow color |
| keyword_shadow_info.shadow_diffuse | `18.0` | [Optional] Keyword shadow diffuse |
| keyword_shadow_info.shadow_distance | `6.0` | [Optional] Keyword shadow distance |
| keyword_shadow_info.shadow_angle | `-45.0` | [Optional] Keyword shadow angle |
| keywords | `["CapCut", "caption"]` | [Optional] Keywords assigned by index |
| in_animation | `向上滑动` | [Optional] Intro animation |
| in_animation_duration | `500000` | [Optional] Intro duration (µs) |
| loop_animation | `弹幕滚动` | [Optional] Loop animation |
| loop_animation_duration | `1000000` | [Optional] Single-loop duration (µs) |
| out_animation | `向下滑动` | [Optional] Outro animation |
| out_animation_duration | `500000` | [Optional] Outro duration (µs) |
| transition | `淡入淡出` | [Optional] Transition name |
| transition_duration | `300000` | [Optional] Transition duration (µs) |

#### 2. Required parameters only

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Hello World"],
    "timelines": [{"start": 0, "end": 3000000}]
  }'
```

#### 3. Keyword highlight + keyword shadow

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Welcome to watch our video", "This is a wonderful example"],
    "timelines": [
      {"start": 0, "end": 3000000},
      {"start": 3000000, "end": 6000000}
    ],
    "font_size": 24,
    "keyword_color": "#FF5500",
    "keyword_border_color": "#111111",
    "keyword_font": "思源中宋",
    "keyword_font_size": 28,
    "keyword_has_shadow": true,
    "keyword_shadow_info": {
      "shadow_alpha": 0.9,
      "shadow_color": "#000000",
      "shadow_diffuse": 15.0,
      "shadow_distance": 5.0,
      "shadow_angle": -45.0
    },
    "keywords": ["video", "wonderful"]
  }'
```

#### 4. Use with add_captions

1. Call `caption_infos` and read `infos` from the response.
2. Pass that string unchanged as `add_captions.captions`.

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "captions": "[{\"start\":0,\"end\":3000000,\"text\":\"Welcome to the CapCut tutorial\",\"keyword\":\"CapCut\",\"keyword_color\":\"#FF5500\",\"keyword_has_shadow\":true,\"font_size\":24}]",
    "text_color": "#ffffff",
    "alignment": 1
  }'
```

## Error Code Description

| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 1001 | Parameter validation failed | Missing texts | Provide non-empty `texts` |
| 1001 | Parameter validation failed | Missing timelines | Provide valid `timelines` |
| 9998 | Internal server error | Internal error | Contact support |

## Notes

1. **Time unit**: microseconds (`1s = 1_000_000µs`)
2. **Color format**: hex, e.g. `#FF0000`
3. **Animation names**: prefer names from `get_text_animations`
4. **Output usage**: response `infos` can be used as `add_captions.captions`
5. **Keyword shadow**: this API only writes fields; rendering happens in `add_captions`

## Workflow

1. Validate `texts` / `timelines`
2. Align arrays by shorter length
3. Build each caption object (keywords + optional style/animation fields)
4. Serialize to JSON string and return

## Related Interfaces

- [Create Draft](./create_draft.md)
- [Add Captions](./add_captions.md)
- [Get Text Animations](./get_text_animations.md)
- [Save Draft](./save_draft.md)

---

<div align="right">

📚 **Project Resources**  
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)  
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)

</div>