mirror of https://github.com/Hommy-master/capcut-mate.git synced 2026-06-20 19:46:00 +08:00

Files

2. 删除多余文档。
3. 添加中英文切换开关。

2026-03-01 20:27:45 +08:00

6.6 KiB

Raw Blame History

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.

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	Type	Required	Default	Description
draft_url	string	✅	-	Complete URL of the target draft
effect_infos	string	✅	-	JSON string of effect information list

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

Field	Type	Description
draft_url	string	Updated draft URL
track_id	string	Effect track ID
effect_ids	array	List of added effect IDs
segment_ids	array	List of segment IDs

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

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft URL parameter	Provide a valid draft URL
400	effect_infos is required	Missing effect information parameter	Provide valid effect information JSON
400	effect_infos format error	JSON format is incorrect	Check JSON string format
400	Effect configuration validation failed	Effect parameters do not meet requirements	Check parameters for each effect
400	effect_title is required	Effect title missing	Provide title for each effect
400	start is required	Effect start time missing	Provide start time for each effect
400	end is required	Effect end time missing	Provide end time for each effect
400	Time range invalid	end must be greater than start	Ensure end time is greater than start time
400	Effect title not found	Specified effect does not exist	Check if effect title is valid
404	Draft does not exist	Specified draft URL invalid	Check if draft URL is correct
500	Effect processing failed	Internal processing error	Contact technical support

Notes

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

Workflow

Validate required parameters (draft_url, effect_infos)
Parse effect_infos JSON string
Validate parameter configuration for each effect
Obtain and decrypt draft content
Create effect track
Add effect segments to track
Apply effects to video segments
Save and encrypt draft
Return processing result

📚 Project Resources
GitHub: https://github.com/Hommy-master/capcut-mate
Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

6.6 KiB Raw Blame History