简创AIGC官方文档

主题切换

返回顶部
当前页导航

CAPTION_INFOS API Documentation

🌐 Language Switch

中文版 | English

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.

More Documentation

📖 For more detailed documentation and tutorials, please visit: https://docs.jcaigc.cn

Request Parameters

ParameterTypeRequiredDefaultDescription
textsarray[string]✅-Caption text list; one item per caption
timelinesarray[object]✅-Timeline list, index-aligned with texts
timelines[].startinteger✅-Caption start time (µs), must be >= 0
timelines[].endinteger✅-Caption end time (µs), must be greater than start
font_sizeinteger❌nullNormal text size written into each caption; omitted from output if not provided
keyword_colorstring❌nullKeyword color (hex), written into each caption
keyword_border_colorstring❌nullKeyword stroke color (hex), written into each caption
keyword_fontstring❌nullKeyword font name, written into each caption
keyword_font_sizeinteger❌nullKeyword font size, written into each caption
keyword_has_shadowboolean❌nullWhether to enable keyword shadow, written into each caption
keyword_shadow_infoobject❌nullKeyword shadow params (same fields as add_captions.shadow_info)
keywordsarray[string]❌nullKeyword list assigned by index to texts[i]; missing indexes get empty keyword
in_animationstring❌nullIntro animation name, e.g. "向上滑动"
in_animation_durationinteger❌nullIntro duration (µs)
loop_animationstring❌nullLoop animation name, e.g. "弹幕滚动"
loop_animation_durationinteger❌nullSingle-loop duration (µs)
out_animationstring❌nullOutro animation name, e.g. "向下滑动"
out_animation_durationinteger❌nullOutro duration (µs)
transitionstring❌nullTransition name written into generated infos
transition_durationinteger❌nullTransition duration (µs)

keyword_shadow_info Fields

FieldTypeRequiredDefaultDescription
shadow_alphanumber❌1.0Shadow opacity [0, 1]
shadow_colorstring❌"#000000"Shadow color (hex)
shadow_diffusenumber❌15.0Diffuse amount [0, 100]
shadow_distancenumber❌5.0Distance [0, 100]
shadow_anglenumber❌-45.0Angle [-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
{
  "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

FieldTypeDescription
infosstringCaption info JSON string; usable as add_captions.captions

Error Response (4xx/5xx)

json
{
  "detail": "Error message description"
}

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:

ParameterExampleMeaning
texts["Welcome to the CapCut tutorial", "This is a caption example"][Required] Two caption texts
timelines[0].start / end0 / 3000000[Required] First caption time range (µs)
timelines[1].start / end3000000 / 6000000[Required] Second caption time range (µs)
font_size24[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_size28[Optional] Keyword font size
keyword_has_shadowtrue[Optional] Enable keyword shadow
keyword_shadow_info.shadow_alpha0.85[Optional] Keyword shadow opacity
keyword_shadow_info.shadow_color#000000[Optional] Keyword shadow color
keyword_shadow_info.shadow_diffuse18.0[Optional] Keyword shadow diffuse
keyword_shadow_info.shadow_distance6.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_duration500000[Optional] Intro duration (µs)
loop_animation弹幕滚动[Optional] Loop animation
loop_animation_duration1000000[Optional] Single-loop duration (µs)
out_animation向下滑动[Optional] Outro animation
out_animation_duration500000[Optional] Outro duration (µs)
transition淡入淡出[Optional] Transition name
transition_duration300000[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 CodeError MessageDescriptionSolution
400texts is requiredMissing textsProvide non-empty texts
400timelines is requiredMissing timelinesProvide valid timelines
500Caption information generation failedInternal errorContact 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

版权所有 © 2025 简创AIGC