ADD_KEYFRAMES API Documentation #

🌐 Language Switch #

中文版 | English

Interface Information #

POST /openapi/capcut-mate/v1/add_keyframes

Function Description #

Add keyframe animations to existing drafts. This interface is used to create property animations for position, scale, rotation, and other properties in Jianying drafts. Keyframes allow precise control over how properties change over time.

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",
  "keyframes": "[{\"property\":\"position.x\",\"time\":0,\"value\":0},{\"property\":\"position.x\",\"time\":1000000,\"value\":100}]"
}

Parameter Description #

Parameter Details #

keyframes Array Structure #

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

[
  {
    "property": "position.x",  // Property name, required
    "time": 0,                 // Keyframe time (microseconds), required
    "value": 0                 // Property value, required
  }
]

Supported Properties:

• position.x - Horizontal position
• position.y - Vertical position
• scale.x - Horizontal scale
• scale.y - Vertical scale
• rotation.z - Rotation angle
• opacity - Transparency

Response Format #

Success Response (200) #

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "keyframes_added": 5,
  "affected_segments": ["segment1-uuid", "segment2-uuid"]
}

Response Field Description #

Error Response (4xx/5xx) #

{
  "detail": "Error message description"
}

Usage Examples #

cURL Examples #

1. Basic Position Animation #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "keyframes": "[{\"property\":\"position.x\",\"time\":0,\"value\":0},{\"property\":\"position.x\",\"time\":1000000,\"value\":100}]"
  }'

2. Scale Animation #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "keyframes": "[{\"property\":\"scale.x\",\"time\":0,\"value\":1.0},{\"property\":\"scale.x\",\"time\":2000000,\"value\":1.5}]"
  }'

3. Rotation Animation #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "keyframes": "[{\"property\":\"rotation.z\",\"time\":0,\"value\":0},{\"property\":\"rotation.z\",\"time\":3000000,\"value\":360}]"
  }'

Error Code Description #

Notes #

1. JSON Format: keyframes must be a valid JSON string
2. Time Unit: Time values use microseconds (1 second = 1,000,000 microseconds)
3. Property Names: Must use exact property names as specified
4. Value Ranges: Different properties have different valid value ranges
5. Interpolation: Keyframes are automatically interpolated between key times

Workflow #

1. Validate required parameters (draft_url, keyframes)
2. Parse keyframes JSON string
3. Validate property names and values
4. Obtain and decrypt draft content
5. Apply keyframe animations to segments
6. Save and encrypt draft
7. Return processing result

Related Interfaces #

• Create Draft
• Add Videos
• Add Images
• Save Draft