--- url: /docs/caption_infos.md --- # CAPTION\_INFOS API Documentation ## 🌐 Language Switch [中文版](/docs/caption_infos.zh) | [English](/docs/caption_infos) ## 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](/docs/create_draft) * [Add Captions](/docs/add_captions) * [Get Text Animations](/docs/get_text_animations) * [Save Draft](/docs/save_draft) *** 📚 **Project Resources**\ **GitHub**: \ **Gitee**: