ADD_EFFECTS API Documentation #

🌐 Language Switch #

中文版 | English

Interface Information #

POST /openapi/capcut-mate/v1/add_effects

Function Description #

Add video effects to existing drafts. This interface is used to add effect materials to Jianying drafts within specified time periods, supporting multiple effect types such as border effects, filter effects, and dynamic effects. Effects can be used to enhance the visual impact of videos.

More Documentation #

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

Request Parameters #

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "effect_infos": "[{\"effect_title\": \"Recording Border III\", \"start\": 0, \"end\": 5000000}, {\"effect_title\": \"Vintage Filter\", \"start\": 2000000, \"end\": 7000000}]"
}

Parameter Description #

Parameter Details #

effect_infos Array Structure #

effect_infos is a JSON string containing an array of effect objects, each with the following fields:

[
  {
    "effect_title": "Recording Border III",  // Effect name/title, required parameter
    "start": 0,                              // Effect start time (microseconds), required parameter
    "end": 5000000                           // Effect end time (microseconds), required parameter
  }
]

Field Description:

• effect_title: Effect name, must be an existing effect name in the system
• start: Effect start time in microseconds
• end: Effect end time in microseconds

Time Parameters #

• start: Start time of the effect on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
• end: End time of the effect on the timeline, unit microseconds
• Duration: Effect duration = end - start

Response Format #

Success Response (200) #

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "effect-track-uuid",
  "effect_ids": ["effect1-uuid", "effect2-uuid"],
  "segment_ids": ["segment1-uuid", "segment2-uuid"]
}

Response Field Description #

Error Response (4xx/5xx) #

{
  "detail": "Error message description"
}

Usage Examples #

cURL Examples #

1. Basic Effect Addition #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "effect_infos": "[{\"effect_title\":\"Vignette\",\"start\":0,\"end\":10000000}]"
  }'

2. Multiple Effects #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "effect_infos": "[{\"effect_title\":\"Border Effect\",\"start\":0,\"end\":5000000},{\"effect_title\":\"Color Filter\",\"start\":3000000,\"end\":8000000}]"
  }'

3. Sequential Effects #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "effect_infos": "[{\"effect_title\":\"Fade In\",\"start\":0,\"end\":1000000},{\"effect_title\":\"Main Effect\",\"start\":1000000,\"end\":9000000},{\"effect_title\":\"Fade Out\",\"start\":9000000,\"end\":10000000}]"
  }'

Error Code Description #

Notes #

1. JSON Format: effect_infos must be a valid JSON string
2. Time Unit: All time parameters use microseconds (1 second = 1,000,000 microseconds)
3. Effect Names: Effect titles must match exactly with system effect names
4. Time Overlap: Multiple effects can be applied to the same time period
5. Effect Priority: Effects are applied in the order they appear in the array
6. Performance: Complex effects may affect video processing performance
7. Supported Effects: System currently supports transition effects like "Fade In", "Fade Out", color filters, etc.
8. Preview Limitation: Effects may not be visible in preview but will be applied during final video generation

Workflow #

1. Validate required parameters (draft_url, effect_infos)
2. Parse effect_infos JSON string
3. Validate parameter configuration for each effect
4. Obtain and decrypt draft content
5. Create effect track
6. Add effect segments to track
7. Apply effects to video segments
8. Save and encrypt draft
9. Return processing result

Related Interfaces #

• Create Draft
• Add Videos
• Add Images
• Save Draft
• Generate Video