更新文档。

2026-08-30 17:48:47 +08:00 · 2026-08-04 15:03:04 +08:00
parent f0e32ca5dc
commit fdc276f489
4 changed files with 915 additions and 500 deletions
@@ -11,7 +11,7 @@ POST /openapi/capcut-mate/v1/add_captions

 ## Function Description

-Batch add captions to existing drafts. This interface is used to add captions to Jianying drafts within specified time periods, supporting rich caption style settings including text color, border color, alignment, transparency, font, font size, letter spacing, line spacing, scaling, and position adjustments.
+Batch-add captions to an existing CapCut/Jianying draft. Supports text color, border, alignment, opacity, font, size, letter/line spacing, scale, position, underline/italic/bold, full-text shadow, keyword highlight and keyword shadow, text animations, and text effects (花字).

 ## More Documentation

@@ -19,93 +19,146 @@ Batch add captions to existing drafts. This interface is used to add captions to

 ## Request Parameters

-```json
-{
-  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
-  "captions": "[{\"start\":0,\"end\":10000000,\"text\":\"Hello, Jianying\",\"keyword\":\"Hello\",\"keyword_color\":\"#457616\",\"keyword_font_size\":15,\"font_size\":15}]",
-  "text_color": "#ffffff",
-  "border_color": null,
-  "alignment": 1,
-  "alpha": 1.0,
-  "font": null,
-  "font_size": 15,
-  "letter_spacing": null,
-  "line_spacing": null,
-  "scale_x": 1.0,
-  "scale_y": 1.0,
-  "transform_x": 0.0,
-  "transform_y": 0.0,
-  "style_text": false
-}
-```
-
-### Parameter Description
+### Top-level Parameters

 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| draft_url | string |✅ | - | Complete URL of the target draft |
-| captions | string |✅ | - | JSON string of caption information list |
-| text_color | string | ❌ | "#ffffff" | Text color (hexadecimal) |
-| border_color | string |❌ | null | Border color (hexadecimal) |
-| alignment | integer |❌ | 1 | Text alignment (0-5) |
-| alpha | number |❌ | 1.0 | Text transparency (0.0-1.0) |
-| font | string |❌ | null | Font name |
-| font_size | integer |❌ | 15 | Font size |
-| letter_spacing | number |❌ | null | Letter spacing |
-| line_spacing | number | ❌ | null | Line spacing |
-| scale_x | number |❌ | 1.0 | Horizontal scaling factor |
-| scale_y | number | ❌ | 1.0 | Vertical scaling factor |
-| transform_x | number | ❌ | 0.0 | Horizontal position offset |
-| transform_y | number | ❌ | 0.0 | Vertical position offset |
-| style_text | boolean |❌ | false | Whether to apply rich text styling |
+| draft_url | string | ✅ | - | Full draft URL including `draft_id` |
+| captions | string | ✅ | - | Caption list as a **JSON string** (not a raw JSON array) |
+| text_color | string | ❌ | `"#ffffff"` | Normal text color (hex) |
+| border_color | string | ❌ | `null` | Normal text stroke color (hex); `null` means no stroke |
+| alignment | integer | ❌ | `1` | Alignment: `0` left, `1` center, `2` right (`3`-`5` reserved) |
+| alpha | number | ❌ | `1.0` | Opacity in `[0.0, 1.0]` |
+| font | string | ❌ | `null` | Font name (enum/display/alias); `null` uses default |
+| font_size | integer | ❌ | `15` | Default font size when a caption item omits `font_size`; must be `>= 1` |
+| letter_spacing | number | ❌ | `null` | Letter spacing; `null` means `0` |
+| line_spacing | number | ❌ | `null` | Line spacing; `null` means `0` |
+| scale_x | number | ❌ | `1.0` | Horizontal scale (`1.0` = original) |
+| scale_y | number | ❌ | `1.0` | Vertical scale (`1.0` = original) |
+| transform_x | number | ❌ | `0.0` | Horizontal offset in pixels (positive = right) |
+| transform_y | number | ❌ | `0.0` | Vertical offset in pixels (positive = down) |
+| style_text | boolean | ❌ | `false` | Rich-text style switch (reserved) |
+| underline | boolean | ❌ | `false` | Underline |
+| italic | boolean | ❌ | `false` | Italic |
+| bold | boolean | ❌ | `false` | Bold |
+| has_shadow | boolean | ❌ | `false` | Enable **full-caption** text shadow |
+| shadow_info | object | ❌ | `null` | Full-caption shadow params; defaults apply if `has_shadow=true` and this is `null` |
+| text_effect | string | ❌ | `null` | Text effect name or `effect_id`; a valid effect resets color/border/shadow |

-### Parameter Details
+### captions Fields

-#### captions Array Structure
+`captions` is a JSON string that parses to an array of caption objects:

-`captions` is a JSON string containing an array of caption objects, each with the following fields:
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| start | integer | ✅ | - | Start time in microseconds (`1s = 1_000_000µs`), must be `>= 0` |
+| end | integer | ✅ | - | End time in microseconds, must be greater than `start` |
+| text | string | ✅ | - | Caption text, non-empty |
+| keyword | string | ❌ | `null` | Keywords separated by `\|`, e.g. `"Hello\|World"` |
+| keyword_color | string | ❌ | `"#ff7100"` | Keyword fill color (hex) |
+| keyword_border_color | string | ❌ | `null` | Keyword stroke color; falls back to top-level `border_color` |
+| keyword_font_size | integer | ❌ | `15` | Keyword font size, must be `> 0` |
+| keyword_has_shadow | boolean | ❌ | `false` | Enable **keyword-range** shadow |
+| keyword_shadow_info | object | ❌ | `null` | Keyword shadow params (same fields as `shadow_info`) |
+| font_size | integer | ❌ | `null` | Per-caption normal text size; falls back to top-level `font_size` |
+| in_animation | string | ❌ | `null` | Intro animation name from `get_text_animations`, e.g. `"向上滑动"` |
+| out_animation | string | ❌ | `null` | Outro animation name, e.g. `"向下滑动"` |
+| loop_animation | string | ❌ | `null` | Loop animation name, e.g. `"弹幕滚动"` |
+| in_animation_duration | integer | ❌ | `null` | Intro duration (µs); omit to use animation default |
+| out_animation_duration | integer | ❌ | `null` | Outro duration (µs); omit to use animation default |
+| loop_animation_duration | integer | ❌ | `null` | Single loop duration (µs); omit to use animation default |
+
+### shadow_info / 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]` |
+
+Default shadow when enabled without `*_shadow_info`:

 ```json
-[
-  {
-    "start": 0,
-    "end": 10000000,
-    "text": "Hello, Jianying",
-    "keyword": "Hello",
-    "keyword_color": "#457616",
-    "keyword_font_size": 15,
-    "font_size": 15
-  }
-]
+{
+  "shadow_color": "#000000",
+  "shadow_alpha": 0.9,
+  "shadow_diffuse": 15,
+  "shadow_distance": 5,
+  "shadow_angle": -45
+}
 ```

-**Field Description**:
- `start`: Caption start time (microseconds)
- `end`: Caption end time (microseconds)
- `text`: Caption text content
- `keyword`: Keyword to highlight
- `keyword_color`: Keyword highlight color
- `keyword_font_size`: Keyword font size
- `keyword_border_color`: Keyword border color
- `keyword_has_shadow`: Whether to enable keyword shadow
- `keyword_shadow_info`: Keyword shadow parameters (same fields as `shadow_info`)
- `font_size`: Base font size
+### Notes on text_effect vs shadow

-#### Time Parameters
+If `text_effect` resolves to a valid effect, the API resets `text_color` to `#ffffff`, `border_color` to `null`, `has_shadow` to `false`, and disables keyword shadow. Omit/leave `text_effect` null when you need custom colors or shadows.

- **start**: Start time of the caption on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
- **end**: End time of the caption on the timeline, unit microseconds
- **Duration**: Caption duration = end - start
+## Fully Annotated Request Example

-#### Style Parameters
+`//` comments are for documentation only and are **not** valid in a real request body.

- **text_color**: Main text color in hexadecimal format (e.g., "#ffffff" for white)
- **border_color**: Text border color, null means no border
- **alignment**: Text alignment mode (0-5)
- **alpha**: Text transparency (0.0 = fully transparent, 1.0 = fully opaque)
- **font_size**: Base font size in pixels
- **scale_x/scale_y**: Horizontal/vertical scaling factors
- **transform_x/transform_y**: Position offset values
+```js
+{
+  // [Required] Draft URL with draft_id
+  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+
+  // [Required] Caption list JSON string (shown as array for readability)
+  "captions": [
+    {
+      "start": 0,                              // [Required] start time (µs)
+      "end": 3000000,                          // [Required] end time (µs), must be > start
+      "text": "Hello, CapCut captions",        // [Required] caption text
+      "keyword": "CapCut|captions",            // [Optional] keywords separated by |
+      "keyword_color": "#ff7100",              // [Optional] keyword color
+      "keyword_border_color": "#000000",       // [Optional] keyword stroke color
+      "keyword_font_size": 22,                 // [Optional] keyword font size
+      "keyword_has_shadow": true,              // [Optional] enable keyword shadow
+      "keyword_shadow_info": {                 // [Optional] keyword shadow params
+        "shadow_alpha": 0.85,
+        "shadow_color": "#000000",
+        "shadow_diffuse": 18.0,
+        "shadow_distance": 6.0,
+        "shadow_angle": -45.0
+      },
+      "font_size": 18,                         // [Optional] this caption's normal font size
+      "in_animation": "向上滑动",               // [Optional] intro animation name
+      "out_animation": "向下滑动",              // [Optional] outro animation name
+      "loop_animation": "弹幕滚动",             // [Optional] loop animation name
+      "in_animation_duration": 500000,         // [Optional] intro duration (µs)
+      "out_animation_duration": 500000,        // [Optional] outro duration (µs)
+      "loop_animation_duration": 1000000       // [Optional] single loop duration (µs)
+    }
+  ],
+
+  "text_color": "#ffffff",                     // [Optional] normal text color
+  "border_color": "#333333",                   // [Optional] normal stroke color
+  "alignment": 1,                              // [Optional] 0 left / 1 center / 2 right
+  "alpha": 1.0,                                // [Optional] opacity [0,1]
+  "font": "思源黑体",                           // [Optional] font name
+  "font_size": 15,                             // [Optional] top-level default font size
+  "letter_spacing": 0,                         // [Optional] letter spacing
+  "line_spacing": 0,                           // [Optional] line spacing
+  "scale_x": 1.0,                              // [Optional] horizontal scale
+  "scale_y": 1.0,                              // [Optional] vertical scale
+  "transform_x": 0.0,                          // [Optional] X offset (px)
+  "transform_y": -200.0,                       // [Optional] Y offset (px)
+  "style_text": false,                         // [Optional] style-text switch
+  "underline": false,                          // [Optional] underline
+  "italic": false,                             // [Optional] italic
+  "bold": true,                                // [Optional] bold
+  "has_shadow": true,                          // [Optional] full-text shadow switch
+  "shadow_info": {                             // [Optional] full-text shadow params
+    "shadow_alpha": 0.9,
+    "shadow_color": "#000000",
+    "shadow_diffuse": 15.0,
+    "shadow_distance": 5.0,
+    "shadow_angle": -45.0
+  },
+  // [Optional] set null so custom colors/shadows remain effective
+  "text_effect": null
+}
+```

 ## Response Format

@@ -121,7 +174,7 @@ Batch add captions to existing drafts. This interface is used to add captions to
    {
      "id": "segment1-uuid",
      "start": 0,
-      "end": 5000000
+      "end": 3000000
    }
  ]
 }
@@ -133,9 +186,9 @@ Batch add captions to existing drafts. This interface is used to add captions to
 |-------|------|-------------|
 | draft_url | string | Updated draft URL |
 | track_id | string | Caption track ID |
-| text_ids | array | List of added text IDs |
-| segment_ids | array | List of segment IDs |
-| segment_infos | array | Segment information array |
+| text_ids | array | Added text material IDs |
+| segment_ids | array | Segment IDs |
+| segment_infos | array | Segment info objects (`id` / `start` / `end`) |

 ### Error Response (4xx/5xx)

@@ -149,49 +202,131 @@ Batch add captions to existing drafts. This interface is used to add captions to

 ### cURL Examples

-#### 1. Basic Caption Addition
+#### 1. Full-parameter request (all required + optional fields)
+
+> Runnable curl with a legal value for every parameter. `captions` must be a JSON string. `text_effect` is `null` so full-text and keyword shadows stay effective.

 ```bash
 curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"Welcome to Jianying\"}]",
+    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+    "captions": "[{\"start\":0,\"end\":3000000,\"text\":\"Hello, CapCut captions\",\"keyword\":\"CapCut|captions\",\"keyword_color\":\"#ff7100\",\"keyword_border_color\":\"#000000\",\"keyword_font_size\":22,\"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\":18,\"in_animation\":\"向上滑动\",\"out_animation\":\"向下滑动\",\"loop_animation\":\"弹幕滚动\",\"in_animation_duration\":500000,\"out_animation_duration\":500000,\"loop_animation_duration\":1000000},{\"start\":3000000,\"end\":6000000,\"text\":\"Welcome to caption features\",\"keyword\":\"caption\",\"keyword_color\":\"#457616\",\"keyword_border_color\":\"#111111\",\"keyword_font_size\":20,\"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},\"font_size\":16,\"in_animation\":\"右上弹入\",\"out_animation\":\"右上弹出\",\"loop_animation\":\"VHS\",\"in_animation_duration\":400000,\"out_animation_duration\":400000,\"loop_animation_duration\":800000}]",
    "text_color": "#ffffff",
-    "font_size": 18
+    "border_color": "#333333",
+    "alignment": 1,
+    "alpha": 1.0,
+    "font": "思源黑体",
+    "font_size": 15,
+    "letter_spacing": 0,
+    "line_spacing": 0,
+    "scale_x": 1.0,
+    "scale_y": 1.0,
+    "transform_x": 0.0,
+    "transform_y": -200.0,
+    "style_text": false,
+    "underline": false,
+    "italic": false,
+    "bold": true,
+    "has_shadow": true,
+    "shadow_info": {
+      "shadow_alpha": 0.9,
+      "shadow_color": "#000000",
+      "shadow_diffuse": 15.0,
+      "shadow_distance": 5.0,
+      "shadow_angle": -45.0
+    },
+    "text_effect": null
  }'
 ```

-#### 2. Caption with Keyword Highlighting
+**Top-level parameter meanings:**
+
+| Parameter | Example | Meaning |
+|-----------|---------|---------|
+| draft_url | `...draft_id=2025092811473036584258` | [Required] Target draft URL |
+| captions | JSON string with 2 captions | [Required] Caption content + per-item style/animation/keyword config |
+| text_color | `#ffffff` | [Optional] Normal text color |
+| border_color | `#333333` | [Optional] Normal stroke color |
+| alignment | `1` | [Optional] Center align |
+| alpha | `1.0` | [Optional] Fully opaque |
+| font | `思源黑体` | [Optional] Font name |
+| font_size | `15` | [Optional] Top-level default size |
+| letter_spacing / line_spacing | `0` | [Optional] Spacing |
+| scale_x / scale_y | `1.0` | [Optional] No scaling |
+| transform_x | `0.0` | [Optional] No horizontal offset |
+| transform_y | `-200.0` | [Optional] Move up 200 px |
+| style_text | `false` | [Optional] Style-text switch off |
+| underline / italic | `false` | [Optional] No underline / italic |
+| bold | `true` | [Optional] Bold on |
+| has_shadow | `true` | [Optional] Full-text shadow on |
+| shadow_info.* | see above | [Optional] Full-text shadow details |
+| text_effect | `null` | [Optional] No 花字, keep colors/shadows |
+
+**Per-caption field meanings:**
+
+| Field | Example | Meaning |
+|-------|---------|---------|
+| start / end | `0` / `3000000` | [Required] Time range (µs) |
+| text | `Hello, CapCut captions` | [Required] Caption text |
+| keyword | `CapCut\|captions` | [Optional] Highlight keywords |
+| keyword_color | `#ff7100` | [Optional] Keyword color |
+| keyword_border_color | `#000000` | [Optional] Keyword stroke |
+| keyword_font_size | `22` | [Optional] Keyword size |
+| keyword_has_shadow | `true` | [Optional] Keyword shadow on |
+| keyword_shadow_info.* | see above | [Optional] Keyword shadow params |
+| font_size | `18` | [Optional] This caption's normal size |
+| in/out/loop_animation | names above | [Optional] Animation names |
+| *_animation_duration | `500000` etc. | [Optional] Animation durations (µs) |
+
+#### 2. Required parameters only

 ```bash
 curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":0,\"end\":3000000,\"text\":\"Hello World\",\"keyword\":\"Hello\",\"keyword_color\":\"#ff0000\",\"keyword_font_size\":20}]",
-    "text_color": "#ffffff",
-    "font_size": 16
+    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"Hello, CapCut\"}]"
  }'
 ```

-#### 3. Styled Caption with Positioning
+#### 3. Keyword highlight + keyword shadow

 ```bash
 curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":2000000,\"end\":7000000,\"text\":\"Styled Caption\"}]",
-    "text_color": "#00ff00",
-    "border_color": "#000000",
-    "alignment": 2,
-    "alpha": 0.8,
+    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"Hello CapCut\",\"keyword\":\"CapCut\",\"keyword_color\":\"#ff0000\",\"keyword_font_size\":22,\"keyword_has_shadow\":true,\"keyword_shadow_info\":{\"shadow_alpha\":0.8,\"shadow_color\":\"#000000\",\"shadow_diffuse\":20.0,\"shadow_distance\":8.0,\"shadow_angle\":-45.0}}]",
+    "text_color": "#ffffff",
+    "font_size": 16,
+    "alignment": 1
+  }'
+```
+
+#### 4. Full-text shadow with default shadow_info
+
+```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\":5000000,\"text\":\"Hello, CapCut\"}]",
+    "text_color": "#ffffff",
    "font_size": 20,
-    "scale_x": 1.2,
-    "scale_y": 1.2,
-    "transform_x": 100,
-    "transform_y": 50
+    "has_shadow": true
+  }'
+```
+
+#### 5. Text effect (花字)
+
+```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\":5000000,\"text\":\"Effect demo\"}]",
+    "text_effect": "白字橘色发光花字"
  }'
 ```

@@ -199,47 +334,29 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \

 | Error Code | Error Message | Description | Solution |
 |------------|---------------|-------------|----------|
-| 400 | draft_url is required | Missing draft URL parameter | Provide a valid draft URL |
-| 400 | captions is required | Missing caption information parameter | Provide valid caption information JSON |
-| 400 | captions format error | JSON format is incorrect | Check JSON string format |
-| 400 | Caption configuration validation failed | Caption parameters do not meet requirements | Check parameters for each caption |
-| 400 | start is required | Caption start time missing | Provide start time for each caption |
-| 400 | end is required | Caption end time missing | Provide end time for each caption |
-| 400 | text is required | Caption text content missing | Provide text content for each caption |
-| 400 | Time range invalid | end must be greater than start | Ensure end time is greater than start time |
-| 400 | Font size invalid | font_size must be positive | Use positive font size value |
-| 400 | Alpha value invalid | alpha not in 0.0-1.0 range | Use alpha value between 0.0-1.0 |
-| 404 | Draft does not exist | Specified draft URL invalid | Check if draft URL is correct |
-| 500 | Caption processing failed | Internal processing error | Contact technical support |
+| 400 | draft_url is required | Missing draft URL | Provide a valid `draft_url` |
+| 400 | captions is required | Missing captions | Provide valid `captions` |
+| 400 | captions format error | Invalid JSON | Fix JSON string format |
+| 400 | Time range invalid | end must be > start | Fix start/end |
+| 404 | Draft does not exist | Invalid/missing draft | Check draft URL |
+| 500 | Caption processing failed | Internal error | Contact support |

 ## Notes

-1. **JSON Format**: captions must be a valid JSON string
-2. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
-3. **Color Format**: Colors use hexadecimal format (e.g., "#ffffff")
-4. **Font Support**: Ensure font names are supported by the system
-5. **Position Range**: transform_x and transform_y values should be within reasonable ranges
-6. **Scaling**: Scale factors should typically be between 0.1-5.0
-7. **Track Management**: Multiple captions will be added to the same caption track
-
-## Workflow
-
-1. Validate required parameters (draft_url, captions)
-2. Parse captions JSON string
-3. Validate parameter configuration for each caption
-4. Obtain and decrypt draft content
-5. Create caption track
-6. Add text segments to track
-7. Apply styling and positioning
-8. Save and encrypt draft
-9. Return processing result
+1. **Time unit**: microseconds (`1s = 1_000_000µs`)
+2. **captions format**: must be a valid JSON **string** inside the request JSON
+3. **Color format**: hex, e.g. `#ffffff`
+4. **Animation names**: from `get_text_animations`
+5. **Text effect names**: from `get_text_effects`
+6. **Coordinates**: `transform_x` / `transform_y` are pixels, converted internally by canvas size
+7. **Keyword shadow**: applies only to keyword ranges; full-text shadow uses `has_shadow` / `shadow_info`

 ## Related Interfaces

 - [Create Draft](./create_draft.md)
- [Add Videos](./add_videos.md)
- [Add Images](./add_images.md)
- [Add Text Style](./add_text_style.md)
+- [Caption Infos](./caption_infos.md)
+- [Get Text Animations](./get_text_animations.md)
+- [Get Text Effects](./get_text_effects.md)
 - [Save Draft](./save_draft.md)

 ---
@@ -250,4 +367,4 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
 **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>
+</div>
@@ -1,7 +1,7 @@
 # ADD_CAPTIONS API 接口文档

 ## 🌐 语言切换
-[中文版](./add_audios.zh.md) | [English](./add_audios.md)
+[中文版](./add_captions.zh.md) | [English](./add_captions.md)

 ## 接口信息

@@ -11,7 +11,7 @@ POST /openapi/capcut-mate/v1/add_captions

 ## 功能描述

-向现有草稿中批量添加字幕。该接口用于在指定的时间段内添加字幕到剪映草稿中，支持丰富的字幕样式设置，包括文本颜色、边框颜色、对齐方式、透明度、字体、字体大小、字间距、行间距、缩放和位置调整等。
+向现有草稿中批量添加字幕。该接口用于在指定的时间段内添加字幕到剪映草稿中，支持丰富的字幕样式设置，包括文本颜色、边框颜色、对齐方式、透明度、字体、字体大小、字间距、行间距、缩放、位置、下划线/斜体/加粗、文本阴影、关键词高亮与关键词阴影、文字动画、花字效果等。

 ## 更多文档

@@ -19,136 +19,66 @@ POST /openapi/capcut-mate/v1/add_captions

 ## 请求参数

-```json
-{
-  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
-  "captions": "[{\"start\":0,\"end\":10000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#457616\",\"keyword_font_size\":15,\"font_size\":15}]",
-  "text_color": "#ffffff",
-  "border_color": null,
-  "alignment": 1,
-  "alpha": 1.0,
-  "font": null,
-  "font_size": 15,
-  "letter_spacing": null,
-  "line_spacing": null,
-  "scale_x": 1.0,
-  "scale_y": 1.0,
-  "transform_x": 0.0,
-  "transform_y": 0.0,
-  "style_text": false
-}
-```
-
-### 参数说明
+### 接口级参数说明

 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
-| draft_url | string | ✅ | - | 目标草稿的完整URL |
-| captions | string | ✅ | - | 字幕信息列表的JSON字符串 |
-| text_color | string | ❌ | "#ffffff" | 文本颜色（十六进制） |
-| border_color | string | ❌ | null | 边框颜色（十六进制） |
-| alignment | integer | ❌ | 1 | 文本对齐方式（0-5） |
-| alpha | number | ❌ | 1.0 | 文本透明度（0.0-1.0） |
-| font | string | ❌ | null | 字体名称 |
-| font_size | integer | ❌ | 15 | 字体大小 |
-| letter_spacing | number | ❌ | null | 字间距 |
-| line_spacing | number | ❌ | null | 行间距 |
-| scale_x | number | ❌ | 1.0 | 水平缩放比例 |
-| scale_y | number | ❌ | 1.0 | 垂直缩放比例 |
-| transform_x | number | ❌ | 0.0 | X轴位置偏移（像素） |
-| transform_y | number | ❌ | 0.0 | Y轴位置偏移（像素） |
-| style_text | boolean | ❌ | false | 是否使用样式文本 |
-| has_shadow | boolean | ❌ | false | 是否启用文本阴影 |
-| shadow_info | object | ❌ | null | 文本阴影参数 |
+| draft_url | string | ✅ | - | 目标草稿的完整 URL，需包含 `draft_id` 查询参数 |
+| captions | string | ✅ | - | 字幕信息列表的 **JSON 字符串**（不是 JSON 数组本身） |
+| text_color | string | ❌ | `"#ffffff"` | 普通字幕文本颜色，十六进制，如 `#ffffff` |
+| border_color | string | ❌ | `null` | 普通字幕描边颜色，十六进制；`null` 表示无描边 |
+| alignment | integer | ❌ | `1` | 文本对齐方式：`0` 左对齐，`1` 居中，`2` 右对齐（`3`-`5` 为预留） |
+| alpha | number | ❌ | `1.0` | 文本透明度，取值范围 `[0.0, 1.0]`，`1.0` 为不透明 |
+| font | string | ❌ | `null` | 字体名称（枚举名、展示名或别名）；`null` 使用默认字体 |
+| font_size | integer | ❌ | `15` | 接口级默认字号；当 caption 项未指定 `font_size` 时生效，须 `>= 1` |
+| letter_spacing | number | ❌ | `null` | 字间距；`null` 表示使用默认值 `0` |
+| line_spacing | number | ❌ | `null` | 行间距；`null` 表示使用默认值 `0` |
+| scale_x | number | ❌ | `1.0` | 水平缩放，`1.0` 为原始大小 |
+| scale_y | number | ❌ | `1.0` | 垂直缩放，`1.0` 为原始大小 |
+| transform_x | number | ❌ | `0.0` | 水平位移（像素），正值向右，负值向左，以画布中心为原点 |
+| transform_y | number | ❌ | `0.0` | 垂直位移（像素），正值向下，负值向上，以画布中心为原点 |
+| style_text | boolean | ❌ | `false` | 是否使用样式文本（预留开关） |
+| underline | boolean | ❌ | `false` | 是否开启文字下划线 |
+| italic | boolean | ❌ | `false` | 是否开启文字斜体 |
+| bold | boolean | ❌ | `false` | 是否开启文字加粗 |
+| has_shadow | boolean | ❌ | `false` | 是否启用**整段字幕**文本阴影 |
+| shadow_info | object | ❌ | `null` | 整段字幕阴影参数；`has_shadow=true` 且本字段为 `null` 时使用默认阴影 |
+| text_effect | string | ❌ | `null` | 花字效果名称或 `effect_id`；有效花字会重置颜色/描边/阴影相关效果 |

-### captions字段详细说明
+### captions 字段详细说明

-captions是一个JSON字符串，包含字幕数组，每个字幕对象包含以下字段：
+`captions` 是一个 JSON 字符串，解析后为字幕对象数组。每个对象字段如下：

 | 字段名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
-| start | integer | ✅ | - | 字幕开始时间（微秒） |
-| end | integer | ✅ | - | 字幕结束时间（微秒） |
-| text | string | ✅ | - | 字幕文本内容 |
-| keyword | string | ❌ | null | 关键词（用\|分隔多个关键词） |
-| keyword_color | string | ❌ | "#ff7100" | 关键词颜色 |
-| keyword_font_size | integer | ❌ | 15 | 关键词字体大小 |
-| keyword_border_color | string | ❌ | null | 关键词边框颜色 |
-| keyword_has_shadow | boolean | ❌ | false | 是否启用关键词阴影 |
-| keyword_shadow_info | object | ❌ | null | 关键词阴影参数（字段同 shadow_info） |
-| font_size | integer | ❌ | 15 | 文本字体大小 |
-| in_animation | string | ❌ | null | 入场动画 |
-| out_animation | string | ❌ | null | 出场动画 |
-| loop_animation | string | ❌ | null | 循环动画 |
-| in_animation_duration | integer | ❌ | null | 入场动画时长 |
-| out_animation_duration | integer | ❌ | null | 出场动画时长 |
-| loop_animation_duration | integer | ❌ | null | 循环动画时长 |
+| start | integer | ✅ | - | 字幕开始时间（微秒），`1 秒 = 1_000_000 微秒`，须 `>= 0` |
+| end | integer | ✅ | - | 字幕结束时间（微秒），必须大于 `start` |
+| text | string | ✅ | - | 字幕文本内容，不能为空 |
+| keyword | string | ❌ | `null` | 关键词，多个用 `\|` 分隔，如 `"剪映\|字幕"` |
+| keyword_color | string | ❌ | `"#ff7100"` | 关键词填充颜色（十六进制） |
+| keyword_border_color | string | ❌ | `null` | 关键词描边颜色；未指定时回退使用接口级 `border_color` |
+| keyword_font_size | integer | ❌ | `15` | 关键词字号，须 `> 0` |
+| keyword_has_shadow | boolean | ❌ | `false` | 是否启用**关键词范围**阴影 |
+| keyword_shadow_info | object | ❌ | `null` | 关键词阴影参数，字段同 `shadow_info`；未提供时用默认阴影 |
+| font_size | integer | ❌ | `null` | 本条字幕普通文本字号；未指定则使用接口级 `font_size` |
+| in_animation | string | ❌ | `null` | 入场动画名称，需与 `get_text_animations` 返回的名称一致，如 `"向上滑动"` |
+| out_animation | string | ❌ | `null` | 出场动画名称，如 `"向下滑动"` |
+| loop_animation | string | ❌ | `null` | 循环动画名称，如 `"弹幕滚动"` |
+| in_animation_duration | integer | ❌ | `null` | 入场动画时长（微秒）；不填则用动画默认时长 |
+| out_animation_duration | integer | ❌ | `null` | 出场动画时长（微秒）；不填则用动画默认时长 |
+| loop_animation_duration | integer | ❌ | `null` | 循环动画**单次循环**时长（微秒）；不填则用动画默认时长 |

-### 参数详解
-
-#### 时间参数
-
- **start**: 字幕在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
- **end**: 字幕在时间轴上的结束时间，单位为微秒
- **duration**: 字幕显示时长 = end - start
-
-#### 对齐方式说明
-
-| 值 | 说明 |
-|---|------|
-| 0 | 左对齐 |
-| 1 | 居中对齐 |
-| 2 | 右对齐 |
-| 3 | 垂直居中 |
-| 4 | 垂直左对齐 |
-| 5 | 垂直右对齐 |
-
-#### 字体大小参数
-
- **font_size**: 普通文本（非关键词）的字体大小
-  - 默认值：15（仅在caption项中未指定font_size时生效）
-  - 建议范围：8-72
-  - 注意：如果在caption项中明确指定了font_size，则使用caption项中的值；如果未指定，则使用接口级别的font_size参数值
-
-#### 缩放参数
-
- **scale_x**: 字幕的水平缩放比例
-  - 1.0 = 原始大小
-  - 0.5 = 水平缩小到一半
-  - 2.0 = 水平放大到两倍
-
- **scale_y**: 字幕的垂直缩放比例
-  - 1.0 = 原始大小
-  - 0.5 = 垂直缩小到一半
-  - 2.0 = 垂直放大到两倍
-
-#### 位置参数
-
- **transform_x**: 字幕在X轴方向的位置偏移，单位为像素
-  - 正值向右移动
-  - 负值向左移动
-  - 以画布中心为原点
-  - 实际存储时会转换为半画布宽单位（假设画布宽度1920，即除以960）
-
- **transform_y**: 字幕在Y轴方向的位置偏移，单位为像素
-  - 正值向下移动
-  - 负值向上移动
-  - 以画布中心为原点
-  - 实际存储时会转换为半画布高单位（假设画布高度1080，即除以540）
-
-#### 文本阴影参数
-
-`shadow_info` 是一个对象，包含以下字段：
+### shadow_info / keyword_shadow_info 字段说明

 | 字段名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
-| shadow_alpha | number | ❌ | 1.0 | 阴影不透明度，取值范围为[0, 1] |
-| shadow_color | string | ❌ | "#000000" | 阴影颜色（十六进制） |
-| shadow_diffuse | number | ❌ | 15.0 | 阴影扩散程度，取值范围为[0, 100] |
-| shadow_distance | number | ❌ | 5.0 | 阴影距离，取值范围为[0, 100] |
-| shadow_angle | number | ❌ | -45.0 | 阴影角度，取值范围为[-180, 180] |
+| shadow_alpha | number | ❌ | `1.0` | 阴影不透明度，取值范围 `[0, 1]` |
+| shadow_color | string | ❌ | `"#000000"` | 阴影颜色（十六进制） |
+| shadow_diffuse | number | ❌ | `15.0` | 阴影扩散程度，取值范围 `[0, 100]` |
+| shadow_distance | number | ❌ | `5.0` | 阴影距离，取值范围 `[0, 100]` |
+| shadow_angle | number | ❌ | `-45.0` | 阴影角度，取值范围 `[-180, 180]` |

-当 `has_shadow` 设置为 `true` 但未提供 `shadow_info` 时，系统将使用以下默认阴影配置：
+当 `has_shadow=true`（或 `keyword_has_shadow=true`）且未提供对应 `*_shadow_info` 时，默认阴影为：

 ```json
 {
@@ -160,9 +90,88 @@ captions是一个JSON字符串，包含字幕数组，每个字幕对象包含
 }
 ```

-#### 关键词阴影参数
+### 参数详解

-`keyword_has_shadow` / `keyword_shadow_info` 作用于 captions 单项中的关键词高亮范围，字段与接口级 `shadow_info` 完全一致。当 `keyword_has_shadow` 为 `true` 且未提供 `keyword_shadow_info` 时，使用与上文相同的默认阴影配置。有效花字效果启用时，关键词阴影会被禁用（与整段 `has_shadow` 行为一致）。
+#### 对齐方式
+
+| 值 | 说明 |
+|---|------|
+| 0 | 左对齐 |
+| 1 | 居中对齐 |
+| 2 | 右对齐 |
+| 3 | 垂直居中（预留） |
+| 4 | 垂直左对齐（预留） |
+| 5 | 垂直右对齐（预留） |
+
+#### 花字与阴影的关系
+
+当 `text_effect` 能解析到有效花字时，系统会将 `text_color` 重置为 `#ffffff`、`border_color` 重置为 `null`、`has_shadow` 重置为 `false`，并禁用关键词阴影（`keyword_has_shadow` 不生效）。若需要自定义颜色/阴影，请不要同时传有效花字。
+
+## 完整参数请求示例（含注释）
+
+下列为**全部接口级参数 + captions 全部字段**的示意；`//` 注释仅用于说明，不能直接作为请求体。
+
+```js
+{
+  // 【必填】目标草稿 URL，必须带 draft_id
+  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+
+  // 【必填】字幕列表 JSON 字符串（下方用数组展示结构，实际请求需序列化为字符串）
+  "captions": [
+    {
+      "start": 0,                              // 【必填】开始时间（微秒）
+      "end": 3000000,                          // 【必填】结束时间（微秒），须 > start
+      "text": "你好，剪映字幕",                 // 【必填】字幕文本
+      "keyword": "剪映|字幕",                   // 【可选】关键词，多个用 | 分隔
+      "keyword_color": "#ff7100",              // 【可选】关键词颜色
+      "keyword_border_color": "#000000",       // 【可选】关键词描边颜色
+      "keyword_font_size": 22,                 // 【可选】关键词字号
+      "keyword_has_shadow": true,              // 【可选】是否启用关键词阴影
+      "keyword_shadow_info": {                 // 【可选】关键词阴影参数
+        "shadow_alpha": 0.85,                  // 阴影不透明度 [0,1]
+        "shadow_color": "#000000",             // 阴影颜色
+        "shadow_diffuse": 18.0,                // 阴影扩散 [0,100]
+        "shadow_distance": 6.0,                // 阴影距离 [0,100]
+        "shadow_angle": -45.0                  // 阴影角度 [-180,180]
+      },
+      "font_size": 18,                         // 【可选】本条普通文本字号
+      "in_animation": "向上滑动",               // 【可选】入场动画名称
+      "out_animation": "向下滑动",              // 【可选】出场动画名称
+      "loop_animation": "弹幕滚动",             // 【可选】循环动画名称
+      "in_animation_duration": 500000,         // 【可选】入场动画时长（微秒）
+      "out_animation_duration": 500000,        // 【可选】出场动画时长（微秒）
+      "loop_animation_duration": 1000000       // 【可选】循环动画单次时长（微秒）
+    }
+  ],
+
+  "text_color": "#ffffff",                     // 【可选】普通文本颜色
+  "border_color": "#333333",                   // 【可选】普通文本描边颜色
+  "alignment": 1,                              // 【可选】对齐：0左/1中/2右
+  "alpha": 1.0,                                // 【可选】透明度 [0,1]
+  "font": "思源黑体",                           // 【可选】字体名称
+  "font_size": 15,                             // 【可选】接口级默认字号
+  "letter_spacing": 0,                         // 【可选】字间距
+  "line_spacing": 0,                           // 【可选】行间距
+  "scale_x": 1.0,                              // 【可选】水平缩放
+  "scale_y": 1.0,                              // 【可选】垂直缩放
+  "transform_x": 0.0,                          // 【可选】水平位移（像素）
+  "transform_y": -200.0,                       // 【可选】垂直位移（像素）
+  "style_text": false,                         // 【可选】样式文本开关
+  "underline": false,                          // 【可选】下划线
+  "italic": false,                             // 【可选】斜体
+  "bold": true,                                // 【可选】加粗
+  "has_shadow": true,                          // 【可选】整段文本阴影开关
+  "shadow_info": {                             // 【可选】整段文本阴影参数
+    "shadow_alpha": 0.9,
+    "shadow_color": "#000000",
+    "shadow_diffuse": 15.0,
+    "shadow_distance": 5.0,
+    "shadow_angle": -45.0
+  },
+  // 【可选】花字；与自定义颜色/阴影冲突，完整示例中置为 null 以保留阴影效果
+  "text_effect": null
+}
+```

 ## 响应格式

@@ -178,12 +187,12 @@ captions是一个JSON字符串，包含字幕数组，每个字幕对象包含
    {
      "id": "seg_001",
      "start": 0,
-      "end": 5000000
+      "end": 3000000
    },
    {
      "id": "seg_002",
-      "start": 5000000,
-      "end": 10000000
+      "start": 3000000,
+      "end": 6000000
    }
  ]
 }
@@ -193,11 +202,11 @@ captions是一个JSON字符串，包含字幕数组，每个字幕对象包含

 | 字段名 | 类型 | 说明 |
 |--------|------|------|
-| draft_url | string | 更新后的草稿URL |
-| track_id | string | 字幕轨道ID |
-| text_ids | array | 字幕ID列表 |
-| segment_ids | array | 字幕片段ID列表 |
-| segment_infos | array | 片段信息列表 |
+| draft_url | string | 更新后的草稿 URL |
+| track_id | string | 字幕轨道 ID |
+| text_ids | array | 字幕素材 ID 列表 |
+| segment_ids | array | 字幕片段 ID 列表 |
+| segment_infos | array | 片段信息列表（含 `id`/`start`/`end`） |

 ### 错误响应 (4xx/5xx)

@@ -211,134 +220,173 @@ captions是一个JSON字符串，包含字幕数组，每个字幕对象包含

 ### cURL 示例

-#### 1. 基本字幕添加
+#### 1. 完整参数请求（全部必填 + 可选参数）
+
+> 下列 curl 可直接执行：每个参数都给出了合法值。`captions` 必须是 JSON 字符串。本示例将 `text_effect` 设为 `null`，以便整段阴影与关键词阴影生效。

 ```bash
 curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\"}]",
+    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+    "captions": "[{\"start\":0,\"end\":3000000,\"text\":\"你好，剪映字幕\",\"keyword\":\"剪映|字幕\",\"keyword_color\":\"#ff7100\",\"keyword_border_color\":\"#000000\",\"keyword_font_size\":22,\"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\":18,\"in_animation\":\"向上滑动\",\"out_animation\":\"向下滑动\",\"loop_animation\":\"弹幕滚动\",\"in_animation_duration\":500000,\"out_animation_duration\":500000,\"loop_animation_duration\":1000000},{\"start\":3000000,\"end\":6000000,\"text\":\"欢迎使用字幕功能\",\"keyword\":\"字幕\",\"keyword_color\":\"#457616\",\"keyword_border_color\":\"#111111\",\"keyword_font_size\":20,\"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},\"font_size\":16,\"in_animation\":\"右上弹入\",\"out_animation\":\"右上弹出\",\"loop_animation\":\"VHS\",\"in_animation_duration\":400000,\"out_animation_duration\":400000,\"loop_animation_duration\":800000}]",
    "text_color": "#ffffff",
+    "border_color": "#333333",
    "alignment": 1,
    "alpha": 1.0,
-    "font_size": 20
-  }'
-```
-
-#### 2. 多字幕添加
-
-```bash
-curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\"},{\"start\":5000000,\"end\":10000000,\"text\":\"欢迎使用字幕功能\"}]",
-    "text_color": "#ffffff",
-    "alignment": 1,
-    "alpha": 1.0,
-    "font_size": 16
-  }'
-```
-
-#### 3. 带样式和位置的字幕
-
-```bash
-curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#ff0000\"]",
-    "text_color": "#ffffff",
-    "alignment": 1,
-    "alpha": 1.0,
-    "font_size": 20,
-    "scale_x": 1.2,
-    "scale_y": 1.2,
-    "transform_x": 100.0,
-    "transform_y": -50.0
-  }'
-```
-
-#### 4. 带文本阴影的字幕
-
-```bash
-curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
-    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\"}]",
-    "text_color": "#ffffff",
-    "alignment": 1,
-    "alpha": 1.0,
-    "font_size": 20,
+    "font": "思源黑体",
+    "font_size": 15,
+    "letter_spacing": 0,
+    "line_spacing": 0,
+    "scale_x": 1.0,
+    "scale_y": 1.0,
+    "transform_x": 0.0,
+    "transform_y": -200.0,
+    "style_text": false,
+    "underline": false,
+    "italic": false,
+    "bold": true,
    "has_shadow": true,
    "shadow_info": {
-      "shadow_alpha": 0.8,
+      "shadow_alpha": 0.9,
      "shadow_color": "#000000",
-      "shadow_diffuse": 20.0,
-      "shadow_distance": 10.0,
+      "shadow_diffuse": 15.0,
+      "shadow_distance": 5.0,
      "shadow_angle": -45.0
-    }
+    },
+    "text_effect": null
  }'
 ```

-#### 5. 使用默认文本阴影的字幕
+**上述完整请求参数含义速查：**
+
+| 参数 | 示例值 | 含义 |
+|------|--------|------|
+| draft_url | `...draft_id=2025092811473036584258` | 【必填】目标草稿地址 |
+| captions | JSON 字符串（含 2 条字幕） | 【必填】字幕内容与每条字幕的样式/动画/关键词配置 |
+| text_color | `#ffffff` | 【可选】普通文本白色 |
+| border_color | `#333333` | 【可选】普通文本深灰描边 |
+| alignment | `1` | 【可选】居中对齐 |
+| alpha | `1.0` | 【可选】完全不透明 |
+| font | `思源黑体` | 【可选】字体名称 |
+| font_size | `15` | 【可选】接口级默认字号 |
+| letter_spacing | `0` | 【可选】字间距 |
+| line_spacing | `0` | 【可选】行间距 |
+| scale_x / scale_y | `1.0` | 【可选】不缩放 |
+| transform_x | `0.0` | 【可选】水平不偏移 |
+| transform_y | `-200.0` | 【可选】向上偏移 200 像素 |
+| style_text | `false` | 【可选】不启用样式文本开关 |
+| underline / italic | `false` | 【可选】无下划线、无斜体 |
+| bold | `true` | 【可选】加粗 |
+| has_shadow | `true` | 【可选】启用整段阴影 |
+| shadow_info.* | 见上 | 【可选】整段阴影详细参数 |
+| text_effect | `null` | 【可选】不使用花字，避免覆盖颜色/阴影 |
+
+**captions 内每条字幕字段含义速查：**
+
+| 字段 | 示例值 | 含义 |
+|------|--------|------|
+| start / end | `0` / `3000000` | 【必填】起止时间（微秒） |
+| text | `你好，剪映字幕` | 【必填】字幕文本 |
+| keyword | `剪映\|字幕` | 【可选】高亮关键词 |
+| keyword_color | `#ff7100` | 【可选】关键词颜色 |
+| keyword_border_color | `#000000` | 【可选】关键词描边 |
+| keyword_font_size | `22` | 【可选】关键词字号 |
+| keyword_has_shadow | `true` | 【可选】启用关键词阴影 |
+| keyword_shadow_info.* | 见上 | 【可选】关键词阴影参数 |
+| font_size | `18` | 【可选】本条普通文本字号 |
+| in_animation | `向上滑动` | 【可选】入场动画 |
+| out_animation | `向下滑动` | 【可选】出场动画 |
+| loop_animation | `弹幕滚动` | 【可选】循环动画 |
+| *_animation_duration | `500000` 等 | 【可选】对应动画时长（微秒） |
+
+#### 2. 仅必填参数

 ```bash
 curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
-    "draft_url": "YOUR_DRAFT_URL",
+    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
+    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\"}]"
+  }'
+```
+
+#### 3. 关键词高亮 + 关键词阴影
+
+```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\":5000000,\"text\":\"你好，剪映\",\"keyword\":\"剪映\",\"keyword_color\":\"#ff0000\",\"keyword_font_size\":22,\"keyword_has_shadow\":true,\"keyword_shadow_info\":{\"shadow_alpha\":0.8,\"shadow_color\":\"#000000\",\"shadow_diffuse\":20.0,\"shadow_distance\":8.0,\"shadow_angle\":-45.0}}]",
+    "text_color": "#ffffff",
+    "font_size": 16,
+    "alignment": 1
+  }'
+```
+
+#### 4. 整段文本阴影（使用默认 shadow_info）
+
+```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\":5000000,\"text\":\"你好，剪映\"}]",
    "text_color": "#ffffff",
-    "alignment": 1,
-    "alpha": 1.0,
    "font_size": 20,
    "has_shadow": true
  }'
 ```

+#### 5. 使用花字效果
+
+```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\":5000000,\"text\":\"花字演示\"}]",
+    "text_effect": "白字橘色发光花字"
+  }'
+```
+
 ## 错误码说明

 | 错误码 | 错误信息 | 说明 | 解决方案 |
 |--------|----------|------|----------|
-| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
-| 400 | captions是必填项 | 缺少字幕信息参数 | 提供有效的captions |
-| 400 | 无效的字幕信息，请检查captions字段值是否正确 | 字幕参数校验失败 | 检查字幕参数是否符合要求 |
-| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
-| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
+| 400 | draft_url是必填项 | 缺少草稿 URL | 提供有效的 `draft_url` |
+| 400 | captions是必填项 | 缺少字幕信息 | 提供有效的 `captions` |
+| 400 | 无效的字幕信息 | captions 校验失败 | 检查 JSON 与必填字段 |
+| 400 | 时间范围无效 | end 必须大于 start | 修正起止时间 |
+| 404 | 草稿不存在 | draft_id 无效或不在缓存中 | 检查草稿 URL |
 | 500 | 字幕添加失败 | 内部处理错误 | 联系技术支持 |

 ## 注意事项

-1. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
-2. **字幕时长**: end 时间必须大于 start 时间
-3. **颜色格式**: 颜色值使用十六进制格式，如 "#ffffff"、"#ff0000"
-4. **关键词高亮**: 暂未完全实现，目前为预留功能
-5. **动画效果**: 暂未完全实现，目前为预留功能
-6. **字体支持**: 字体名称需要系统支持或使用默认字体
-7. **对齐方式**: 目前仅支持基础对齐方式（0-2），高级对齐方式（3-5）为预留功能
-8. **坐标系统**: transform_x 和 transform_y 使用像素值，会自动转换为草稿相对坐标
-9. **缩放参数**: scale_x 和 scale_y 建议在合理范围内使用
+1. **时间单位**：所有时间参数使用微秒（`1 秒 = 1_000_000 微秒`）
+2. **captions 格式**：必须是合法 JSON **字符串**，外层再包一层请求 JSON
+3. **颜色格式**：十六进制，如 `#ffffff`、`#ff0000`
+4. **动画名称**：请通过 `get_text_animations` 获取可用名称
+5. **花字名称**：请通过 `get_text_effects` 获取可用名称或 `effect_id`
+6. **坐标系统**：`transform_x` / `transform_y` 使用像素，内部会按画布尺寸换算
+7. **关键词阴影**：仅作用于关键词字符范围；整段阴影由 `has_shadow` / `shadow_info` 控制

 ## 工作流程

-1. 验证必填参数（draft_url, captions）
-2. 检查时间范围的有效性
-3. 从缓存中获取草稿
-4. 创建字幕轨道（如果不存在）
-5. 遍历字幕信息，创建字幕片段
-6. 添加片段到轨道
-7. 保存草稿
-8. 返回字幕信息
+1. 验证必填参数（`draft_url`, `captions`）
+2. 解析并校验每条字幕
+3. 从缓存获取草稿
+4. 创建字幕轨道
+5. 创建文本片段并应用样式/关键词/动画/花字
+6. 保存草稿并返回结果

 ## 相关接口

 - [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
+- [生成字幕信息](./caption_infos.md)
+- [获取文字动画](./get_text_animations.md)
+- [获取花字效果](./get_text_effects.md)
 - [保存草稿](./save_draft.md)
 - [生成视频](./gen_video.md)

@@ -349,4 +397,4 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
 **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>
+</div>
@@ -11,7 +11,7 @@ POST /openapi/capcut-mate/v1/caption_infos

 ## Function Description

-Generate caption information based on text and timelines. This interface converts text content and timeline configurations into the caption information format required by Jianying drafts, supporting keyword highlighting, animation effects, and transition settings.
+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.

 ## More Documentation

@@ -19,48 +19,94 @@ Generate caption information based on text and timelines. This interface convert

 ## Request Parameters

-```json
-{
-  "texts": ["Welcome to watch", "This is an example"],
-  "timelines": [
-    {"start": 0, "end": 3000000},
-    {"start": 3000000, "end": 6000000}
-  ],
-  "font_size": 24,
-  "keyword_color": "#FF0000",
-  "keyword_font_size": 28,
-  "keywords": ["example"],
-  "in_animation": "fade_in",
-  "in_animation_duration": 500000,
-  "loop_animation": "bounce",
-  "loop_animation_duration": 1000000,
-  "out_animation": "fade_out",
-  "out_animation_duration": 500000,
-  "transition": "cross_fade",
-  "transition_duration": 300000
-}
-```
-
-### Parameter Description
-
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| texts | array[string] |✅ | - | Text content array |
-| timelines | array[object] |✅ | - | Timeline configuration array |
-| font_size | number |❌ | 24 | Font size |
-| keyword_color | string |❌ | "#FF0000" | Keyword color |
-| keyword_font_size | number |❌ | 28 | Keyword font size |
-| keyword_has_shadow | boolean |❌ | null | Whether to enable keyword shadow |
-| keyword_shadow_info | object |❌ | null | Keyword shadow parameters (same fields as add_captions shadow_info) |
-| keywords | array[string] |❌ | [] | Keyword array |
-| in_animation | string |❌ | None | Entrance animation effect |
-| in_animation_duration | number |❌ | 500000 | Entrance animation duration (microseconds) |
-| loop_animation | string |❌ | None | Loop animation effect |
-| loop_animation_duration | number |❌ | 1000000 | Loop animation duration (microseconds) |
-| out_animation | string |❌ | None | Exit animation effect |
-| out_animation_duration | number |❌ | 500000 | Exit animation duration (microseconds) |
-| transition | string |❌ | None | Transition effect |
-| transition_duration | number |❌ | 300000 | Transition duration (microseconds) |
+| 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_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_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

@@ -68,7 +114,7 @@ Generate caption information based on text and timelines. This interface convert

 ```json
 {
-  "infos": "[{\"text\":\"Welcome to watch\",\"start\":0,\"end\":3000000,\"duration\":5000000,\"font_size\":24,\"keyword_color\":\"#FF0000\",\"keyword_font_size\":28,\"keywords\":[\"watch\"],\"in_animation\":\"fade_in\",\"in_animation_duration\":500000,\"loop_animation\":\"bounce\",\"loop_animation_duration\":1000000,\"out_animation\":\"fade_out\",\"out_animation_duration\":500000,\"transition\":\"cross_fade\",\"transition_duration\":300000},{\"text\":\"This is an example\",\"start\":3000000,\"end\":6000000,\"duration\":5000000,\"font_size\":24,\"keyword_color\":\"#FF0000\",\"keyword_font_size\":28,\"keywords\":[\"example\"],\"in_animation\":\"fade_in\",\"in_animation_duration\":500000,\"loop_animation\":\"bounce\",\"loop_animation_duration\":1000000,\"out_animation\":\"fade_out\",\"out_animation_duration\":500000,\"transition\":\"cross_fade\",\"transition_duration\":300000}]"
+  "infos": "[{\"start\":0,\"end\":3000000,\"text\":\"Welcome to the CapCut tutorial\",\"keyword\":\"CapCut\",\"keyword_color\":\"#FF5500\",\"keyword_border_color\":\"#000000\",\"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_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}]"
 }
 ```

@@ -76,7 +122,7 @@ Generate caption information based on text and timelines. This interface convert

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

 ### Error Response (4xx/5xx)

@@ -90,30 +136,119 @@ Generate caption information based on text and timelines. This interface convert

 ### cURL Examples

-#### 1. Basic Caption Information Generation
+#### 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_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_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}],
-    "font_size": 28
+    "timelines": [{"start": 0, "end": 3000000}]
  }'
 ```

-#### 2. Caption Information with Highlighting
+#### 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}],
+    "timelines": [
+      {"start": 0, "end": 3000000},
+      {"start": 3000000, "end": 6000000}
+    ],
+    "font_size": 24,
    "keyword_color": "#FF5500",
-    "keywords": ["wonderful", "video"],
-    "in_animation": "fade_in",
-    "loop_animation": "bounce"
+    "keyword_border_color": "#111111",
+    "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
  }'
 ```

@@ -121,37 +256,30 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos

 | Error Code | Error Message | Description | Solution |
 |------------|---------------|-------------|----------|
-| 400 | texts is required | Missing text content parameter | Provide valid text content array |
-| 400 | timelines is required | Missing timeline parameter | Provide valid timeline array |
-| 400 | Array length mismatch | texts and timelines array lengths don't match | Ensure both arrays have the same length |
-| 400 | font_size must be greater than 0 | Invalid font size parameter | Use font size value greater than 0 |
-| 500 | Caption information generation failed | Internal processing error | Contact technical support |
+| 400 | texts is required | Missing texts | Provide non-empty `texts` |
+| 400 | timelines is required | Missing timelines | Provide valid `timelines` |
+| 500 | Caption information generation failed | Internal error | Contact support |

 ## Notes

-1. **Array Matching**: texts and timelines array lengths must be the same
-2. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
-3. **Keyword Matching**: Keywords in keywords array will be highlighted in text
-4. **Animation Effects**: Support entrance animation, loop animation, exit animation, and transition effects
-5. **Color Format**: keyword_color uses hexadecimal color format (e.g., "#FF0000")
-6. **Font Size**: Font size is in pixels
+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 required parameters (texts, timelines)
-2. Check array length matching
-3. Validate timeline parameter validity
-4. Set font and color parameters
-5. Apply animation effect parameters
-6. Generate corresponding caption information for each text content
-7. Convert information to JSON string format
-8. Return processing result
+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)
- [Timelines](./timelines.md)
+- [Get Text Animations](./get_text_animations.md)
 - [Save Draft](./save_draft.md)

 ---
@@ -163,6 +291,3 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos
 **Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)

 </div>
-
-### Language Switch
-[中文版](./caption_infos.zh.md) | [English](./caption_infos.md)
@@ -11,7 +11,7 @@ POST /openapi/capcut-mate/v1/caption_infos

 ## 功能描述

-根据文本和时间线生成字幕信息。该接口将文本内容和时间线配置转换为剪映草稿所需的字幕信息格式，支持关键词高亮、动画效果和转场设置。
+根据文本列表与时间线生成字幕信息 JSON 字符串，可直接作为 `add_captions` 的 `captions` 参数使用。支持字体大小、关键词高亮（颜色/描边/字号/阴影）、入场/循环/出场动画及转场配置。

 ## 更多文档

@@ -19,66 +19,112 @@ POST /openapi/capcut-mate/v1/caption_infos

 ## 请求参数

-```json
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| texts | array[string] | ✅ | - | 字幕文本列表，每一项对应一条字幕 |
+| timelines | array[object] | ✅ | - | 时间线列表，与 `texts` 按索引一一对应 |
+| timelines[].start | integer | ✅ | - | 该条字幕开始时间（微秒），须 `>= 0` |
+| timelines[].end | integer | ✅ | - | 该条字幕结束时间（微秒），须大于 `start` |
+| font_size | integer | ❌ | `null` | 写入每条字幕的普通文本字号；不传则生成结果中不含该字段 |
+| keyword_color | string | ❌ | `null` | 关键词颜色（十六进制），写入每条字幕 |
+| keyword_border_color | string | ❌ | `null` | 关键词描边颜色（十六进制），写入每条字幕 |
+| keyword_font_size | integer | ❌ | `null` | 关键词字号，写入每条字幕 |
+| keyword_has_shadow | boolean | ❌ | `null` | 是否启用关键词阴影，写入每条字幕 |
+| keyword_shadow_info | object | ❌ | `null` | 关键词阴影参数，字段同 `add_captions` 的 `shadow_info` |
+| keywords | array[string] | ❌ | `null` | 重点词列表，按索引分配到对应 `texts[i]`；不足时后续文本 `keyword` 为空字符串 |
+| in_animation | string | ❌ | `null` | 入场动画名称，如 `"向上滑动"` |
+| in_animation_duration | integer | ❌ | `null` | 入场动画时长（微秒） |
+| loop_animation | string | ❌ | `null` | 循环动画名称，如 `"弹幕滚动"` |
+| loop_animation_duration | integer | ❌ | `null` | 循环动画**单次循环**时长（微秒） |
+| out_animation | string | ❌ | `null` | 出场动画名称，如 `"向下滑动"` |
+| out_animation_duration | integer | ❌ | `null` | 出场动画时长（微秒） |
+| transition | string | ❌ | `null` | 转场名称（写入生成的字幕信息，供后续流程使用） |
+| transition_duration | integer | ❌ | `null` | 转场时长（微秒） |
+
+### keyword_shadow_info 字段说明
+
+| 字段名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| shadow_alpha | number | ❌ | `1.0` | 阴影不透明度，取值范围 `[0, 1]` |
+| shadow_color | string | ❌ | `"#000000"` | 阴影颜色（十六进制） |
+| shadow_diffuse | number | ❌ | `15.0` | 阴影扩散程度，取值范围 `[0, 100]` |
+| shadow_distance | number | ❌ | `5.0` | 阴影距离，取值范围 `[0, 100]` |
+| shadow_angle | number | ❌ | `-45.0` | 阴影角度，取值范围 `[-180, 180]` |
+
+### 说明
+
+1. `texts` 与 `timelines` 长度不一致时，按**较短长度**截断后继续生成（不会直接报错）。
+2. `keywords[i]` 会写入第 `i` 条字幕的 `keyword` 字段；若 `keywords` 比 `texts` 短，后续条目的 `keyword` 为空字符串。
+3. 可选参数仅在非 `null` 时写入生成结果。
+
+## 完整参数请求示例（含注释）
+
+下列为**全部必填 + 可选参数**示意；`//` 注释仅用于说明，不能直接作为请求体。
+
+```js
 {
-  "texts": ["欢迎观看", "这是一个示例"],
-  "timelines": [
-    {"start": 0, "end": 3000000},
-    {"start": 3000000, "end": 6000000}
+  // 【必填】字幕文本列表，每项对应一条字幕
+  "texts": [
+    "欢迎观看剪映教程",
+    "这是一个字幕示例"
  ],
-  "font_size": 24,
-  "keyword_color": "#FF0000",
-  "keyword_font_size": 28,
-  "keywords": ["示例"],
-  "in_animation": "fade_in",
-  "in_animation_duration": 500000,
-  "loop_animation": "bounce",
-  "loop_animation_duration": 1000000,
-  "out_animation": "fade_out",
-  "out_animation_duration": 500000,
-  "transition": "cross_fade",
-  "transition_duration": 300000
+
+  // 【必填】时间线列表，与 texts 按索引一一对应
+  "timelines": [
+    {
+      "start": 0,                 // 【必填】第 1 条开始时间（微秒）
+      "end": 3000000              // 【必填】第 1 条结束时间（微秒）
+    },
+    {
+      "start": 3000000,           // 【必填】第 2 条开始时间（微秒）
+      "end": 6000000              // 【必填】第 2 条结束时间（微秒）
+    }
+  ],
+
+  "font_size": 24,                // 【可选】普通文本字号
+  "keyword_color": "#FF5500",     // 【可选】关键词颜色
+  "keyword_border_color": "#000000", // 【可选】关键词描边颜色
+  "keyword_font_size": 28,        // 【可选】关键词字号
+  "keyword_has_shadow": true,     // 【可选】启用关键词阴影
+  "keyword_shadow_info": {        // 【可选】关键词阴影详细参数
+    "shadow_alpha": 0.85,         // 阴影不透明度 [0,1]
+    "shadow_color": "#000000",    // 阴影颜色
+    "shadow_diffuse": 18.0,       // 阴影扩散 [0,100]
+    "shadow_distance": 6.0,       // 阴影距离 [0,100]
+    "shadow_angle": -45.0         // 阴影角度 [-180,180]
+  },
+  "keywords": [                   // 【可选】重点词，按索引分配到 texts
+    "剪映",
+    "字幕"
+  ],
+  "in_animation": "向上滑动",      // 【可选】入场动画名称
+  "in_animation_duration": 500000, // 【可选】入场动画时长（微秒）
+  "loop_animation": "弹幕滚动",    // 【可选】循环动画名称
+  "loop_animation_duration": 1000000, // 【可选】循环单次时长（微秒）
+  "out_animation": "向下滑动",     // 【可选】出场动画名称
+  "out_animation_duration": 500000, // 【可选】出场动画时长（微秒）
+  "transition": "淡入淡出",        // 【可选】转场名称
+  "transition_duration": 300000   // 【可选】转场时长（微秒）
 }
 ```

-### 参数说明
-
-| 参数名 | 类型 |必 | | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| texts | array[string] |✅ | - | 文本内容数组 |
-| timelines | array[object] |✅ | - | 时间线配置数组 |
-| font_size | number |❌ | 24 | 字体大小 |
-| keyword_color | string |❌ | "#FF0000" | 关键词颜色 |
-| keyword_font_size | number | ❌ | 28 | 关键词字体大小 |
-| keyword_has_shadow | boolean | ❌ | null | 是否启用关键词阴影 |
-| keyword_shadow_info | object | ❌ | null | 关键词阴影参数（字段同 add_captions 的 shadow_info） |
-| keywords | array[string] | ❌ | [] | 关键词数组 |
-| in_animation | string | ❌ | None |入动画效果 |
-| in_animation_duration | number | ❌ | 500000 |入场动画时长(微秒) |
-| loop_animation | string | ❌ | None |循动画效果 |
-| loop_animation_duration | number | ❌ | 1000000 |循动画动画时长(微秒) |
-| out_animation | string | ❌ | None |出场动画效果 |
-| out_animation_duration | number | ❌ | 500000 |出场动画时长(微秒) |
-| transition | string | ❌ | None |效果 |
-| transition_duration | number | ❌ | 300000 |转时长(微秒) |
-
-##响应格式
+## 响应格式

 ### 成功响应 (200)

 ```json
 {
-  "infos": "[{\"text\":\"欢迎观看\",\"start\":0,\"end\":3000000,\"duration\":5000000,\"font_size\":24,\"keyword_color\":\"#FF0000\",\"keyword_font_size\":28,\"keywords\":[\"观看\"],\"in_animation\":\"fade_in\",\"in_animation_duration\":500000,\"loop_animation\":\"bounce\",\"loop_animation_duration\":1000000,\"out_animation\":\"fade_out\",\"out_animation_duration\":500000,\"transition\":\"cross_fade\",\"transition_duration\":300000},{\"text\":\"这是一个示例\",\"start\":3000000,\"end\":6000000,\"duration\":5000000,\"font_size\":24,\"keyword_color\":\"#FF0000\",\"keyword_font_size\":28,\"keywords\":[\"示例\"],\"in_animation\":\"fade_in\",\"in_animation_duration\":500000,\"loop_animation\":\"bounce\",\"loop_animation_duration\":1000000,\"out_animation\":\"fade_out\",\"out_animation_duration\":500000,\"transition\":\"cross_fade\",\"transition_duration\":300000}]"
+  "infos": "[{\"start\":0,\"end\":3000000,\"text\":\"欢迎观看剪映教程\",\"keyword\":\"剪映\",\"keyword_color\":\"#FF5500\",\"keyword_border_color\":\"#000000\",\"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\":\"这是一个字幕示例\",\"keyword\":\"字幕\",\"keyword_color\":\"#FF5500\",\"keyword_border_color\":\"#000000\",\"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}]"
 }
 ```

-###响应字段说明
+### 响应字段说明

 | 字段名 | 类型 | 说明 |
 |--------|------|------|
-| infos | string | 字幕信息JSON字符串 |
+| infos | string | 字幕信息 JSON 字符串，可直接作为 `add_captions.captions` 使用 |

-###错误响应 (4xx/5xx)
+### 错误响应 (4xx/5xx)

 ```json
 {
@@ -90,30 +136,119 @@ POST /openapi/capcut-mate/v1/caption_infos

 ### cURL 示例

-#### 1. 基本字幕信息生成
+#### 1. 完整参数请求（全部必填 + 可选参数）
+
+```bash
+curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos \
+  -H "Content-Type: application/json" \
+  -d '{
+    "texts": ["欢迎观看剪映教程", "这是一个字幕示例"],
+    "timelines": [
+      {"start": 0, "end": 3000000},
+      {"start": 3000000, "end": 6000000}
+    ],
+    "font_size": 24,
+    "keyword_color": "#FF5500",
+    "keyword_border_color": "#000000",
+    "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": ["剪映", "字幕"],
+    "in_animation": "向上滑动",
+    "in_animation_duration": 500000,
+    "loop_animation": "弹幕滚动",
+    "loop_animation_duration": 1000000,
+    "out_animation": "向下滑动",
+    "out_animation_duration": 500000,
+    "transition": "淡入淡出",
+    "transition_duration": 300000
+  }'
+```
+
+**上述完整请求参数含义速查：**
+
+| 参数 | 示例值 | 含义 |
+|------|--------|------|
+| texts | `["欢迎观看剪映教程", "这是一个字幕示例"]` | 【必填】两条字幕文本 |
+| timelines[0].start / end | `0` / `3000000` | 【必填】第 1 条起止时间（微秒） |
+| timelines[1].start / end | `3000000` / `6000000` | 【必填】第 2 条起止时间（微秒） |
+| font_size | `24` | 【可选】普通文本字号 |
+| keyword_color | `#FF5500` | 【可选】关键词颜色 |
+| keyword_border_color | `#000000` | 【可选】关键词描边颜色 |
+| keyword_font_size | `28` | 【可选】关键词字号 |
+| keyword_has_shadow | `true` | 【可选】启用关键词阴影 |
+| keyword_shadow_info.shadow_alpha | `0.85` | 【可选】关键词阴影不透明度 |
+| keyword_shadow_info.shadow_color | `#000000` | 【可选】关键词阴影颜色 |
+| keyword_shadow_info.shadow_diffuse | `18.0` | 【可选】关键词阴影扩散 |
+| keyword_shadow_info.shadow_distance | `6.0` | 【可选】关键词阴影距离 |
+| keyword_shadow_info.shadow_angle | `-45.0` | 【可选】关键词阴影角度 |
+| keywords | `["剪映", "字幕"]` | 【可选】按索引分配到对应文本的关键词 |
+| in_animation | `向上滑动` | 【可选】入场动画 |
+| in_animation_duration | `500000` | 【可选】入场动画时长（微秒） |
+| loop_animation | `弹幕滚动` | 【可选】循环动画 |
+| loop_animation_duration | `1000000` | 【可选】循环单次时长（微秒） |
+| out_animation | `向下滑动` | 【可选】出场动画 |
+| out_animation_duration | `500000` | 【可选】出场动画时长（微秒） |
+| transition | `淡入淡出` | 【可选】转场名称 |
+| transition_duration | `300000` | 【可选】转场时长（微秒） |
+
+#### 2. 仅必填参数

 ```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}],
-    "font_size": 28
+    "timelines": [{"start": 0, "end": 3000000}]
  }'
 ```

-#### 2.带高亮的字幕信息
+#### 3. 关键词高亮 + 关键词阴影

 ```bash
 curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["欢迎观看我们的视频", "这是一个精彩示例"],
-    "timelines": [{"start": 0, "end": 3000000}, {"start": 3000000, "end": 6000000}],
+    "timelines": [
+      {"start": 0, "end": 3000000},
+      {"start": 3000000, "end": 6000000}
+    ],
+    "font_size": 24,
    "keyword_color": "#FF5500",
-    "keywords": ["精彩", "视频"],
-    "in_animation": "fade_in",
-    "loop_animation": "bounce"
+    "keyword_border_color": "#111111",
+    "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": ["视频", "精彩"]
+  }'
+```
+
+#### 4. 配合 add_captions 使用
+
+1. 先调用 `caption_infos`，从响应中取出 `infos` 字符串。
+2. 将该字符串原样作为 `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\":\"欢迎观看剪映教程\",\"keyword\":\"剪映\",\"keyword_color\":\"#FF5500\",\"keyword_has_shadow\":true,\"font_size\":24}]",
+    "text_color": "#ffffff",
+    "alignment": 1
  }'
 ```

@@ -121,37 +256,30 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos

 | 错误码 | 错误信息 | 说明 | 解决方案 |
 |--------|----------|------|----------|
-| 400 | texts是必填项 |缺少文本内容参数 | 提供有效的文本内容数组 |
-| 400 | timelines是必填项 |缺少时间线参数 | 提供有效的时间线数组 |
-| 400 | 数组长度不匹配 | texts和timelines长度不一致 |确保两个数组长度相同 |
-| 400 | font_size必须大于0 | 字体大小参数无效 | 使用大于0的字体大小值 |
-| 500 | 字幕信息生成失败 |内部处理错误 |联技术支持 |
+| 400 | texts是必填项 | 缺少文本内容 | 提供非空 `texts` |
+| 400 | timelines是必填项 | 缺少时间线 | 提供有效 `timelines` |
+| 500 | 字幕信息生成失败 | 内部处理错误 | 联系技术支持 |

 ## 注意事项

-1. **数组匹配**: texts和timelines数组长度必须相同
-2. **时间单位**:所有时间参数使用微秒（1秒 = 1,000,000微秒）
-3. **关键词匹配**: keywords数组中的关键词将在文本中高亮显示
-4. **动画效果**:支持入场动画、循环动画、出场动画和转场效果
-5. **颜色格式**: keyword_color使用十六进制颜色格式（如"#FF0000"）
-6. **字体大小**: 字体大小以像素为单位
+1. **时间单位**：微秒（`1 秒 = 1_000_000 微秒`）
+2. **颜色格式**：十六进制，如 `#FF0000`
+3. **动画名称**：建议通过 `get_text_animations` 获取可用名称
+4. **输出用途**：返回的 `infos` 可直接作为 `add_captions` 的 `captions` 参数
+5. **关键词阴影**：本接口只负责写入字段；真正渲染由 `add_captions` 完成

-##工作流程
+## 工作流程

-1.验证必填参数（texts, timelines）
-2. 检查数组长度匹配
-3.验证时间线参数有效性
-4. 设置字体和颜色参数
-5.应用动画效果参数
-6. 为每个文本内容生成对应的字幕信息
-7. 将信息转换为JSON字符串格式
-8. 返回处理结果
+1. 校验 `texts` / `timelines`
+2. 按较短长度对齐两个数组
+3. 按索引组装每条字幕信息（含关键词与可选样式/动画）
+4. 序列化为 JSON 字符串并返回

-##相关接口
+## 相关接口

 - [创建草稿](./create_draft.md)
 - [添加字幕](./add_captions.md)
- [时间线](./timelines.md)
+- [获取文字动画](./get_text_animations.md)
 - [保存草稿](./save_draft.md)

 ---
@@ -163,6 +291,3 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/caption_infos
 **Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)

 </div>
-
-### 语言切换
-[中文版](./caption_infos.zh.md) | [English](./caption_infos.md)