DEV Community

Hommy
Hommy

Posted on

[JCAIGC]Add keyframe animations

ADD_KEYFRAMES API Interface Documentation

πŸ“‹ Table of Contents

πŸ”§ Interface Information 

POST /openapi/capcut-mate/v1/add_keyframes
Enter fullscreen mode Exit fullscreen mode

Function Description

Add keyframe animations. This interface is used to add keyframe animations to elements in CapCut draft, supporting position, size, rotation, transparency, and other property animations. It is suitable for creating smooth animation effects, achieving complex visual transitions.

More Documentation

πŸ“– For more detailed documentation and tutorials, please visit: https://docs.jcaigc.cn

Request Parameters

Request Body (application/json)

Parameter Name Type Required Default Value Description
draft_url string βœ… - Target draft URL, format: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=xxx
keyframes array βœ… - Keyframe animation list, supports adding multiple keyframe animations at once

Keyframe Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "keyframes": [
    {
      "element_id": "element_001",
      "property": "position",
      "frames": [
        {
          "time": 0,
          "value": {"x": 0, "y": 0}
        },
        {
          "time": 2000000,
          "value": {"x": 100, "y": 50}
        },
        {
          "time": 5000000,
          "value": {"x": 200, "y": 100}
        }
      ],
      "easing": "ease_in_out"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Keyframe Parameter Description

Parameter Name Type Required Default Value Description
element_id string βœ… - Element ID, used to identify the target element
property string βœ… - Animation property type
frames array βœ… - Keyframe list, contains time point and corresponding value
easing string ❌ "linear" Animation easing function

Animation Property Types

Property Type Value Type Description Example
position object Position animation {"x": 100, "y": 200}
scale number/object Scaling animation 1.5 or {"x": 2, "y": 1.5}
rotation number Rotation animation 45 (degrees)
opacity number Transparency animation 0.8 (range 0-1)
color string Color animation "#FF0000" or "rgb(255,0,0)"

Keyframe Structure 

{
  "time": 1000000,  // Time point, unit: microseconds
  "value": 100      // Property value at this time point
}
Enter fullscreen mode Exit fullscreen mode
Parameter Name Type Description
time number Time point, unit: microseconds (ΞΌs), 1000000ΞΌs = 1 second
value various Property value at this time point, type depends on the property

Easing Function Options

Easing Function Description Application Scenario
linear Linear animation Uniform speed motion
ease_in Ease in animation Start slow, end fast
ease_out Ease out animation Start fast, end slow
ease_in_out Ease in and out animation Start and end slow, middle fast
bounce Bounce animation Bouncing effect
elastic Elastic animation Spring-like effect

Animation Property Details

Position Animation (position) 

{
  "property": "position",
  "frames": [
    {"time": 0, "value": {"x": 0, "y": 0}},
    {"time": 1000000, "value": {"x": 100, "y": 50}},
    {"time": 2000000, "value": {"x": 200, "y": 100}}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Scaling Animation (scale) 

// Uniform scaling
{
  "property": "scale",
  "frames": [
    {"time": 0, "value": 1},
    {"time": 1000000, "value": 1.5},
    {"time": 2000000, "value": 1}
  ]
}

// Non-uniform scaling
{
  "property": "scale",
  "frames": [
    {"time": 0, "value": {"x": 1, "y": 1}},
    {"time": 1000000, "value": {"x": 2, "y": 1.5}},
    {"time": 2000000, "value": {"x": 1, "y": 1}}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Rotation Animation (rotation) 

{
  "property": "rotation",
  "frames": [
    {"time": 0, "value": 0},
    {"time": 1000000, "value": 180},
    {"time": 2000000, "value": 360}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Transparency Animation (opacity) 

{
  "property": "opacity",
  "frames": [
    {"time": 0, "value": 1},
    {"time": 1000000, "value": 0.3},
    {"time": 2000000, "value": 1}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Response Format

Success Response (200) 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}
Enter fullscreen mode Exit fullscreen mode

Response Field Description

Field Name Type Description
draft_url string Draft URL after adding keyframe animations, same as the request URL
tip_url string Draft usage help document URL

Error Response (4xx/5xx) 

{
  "detail": "Error message description"
}
Enter fullscreen mode Exit fullscreen mode

Usage Examples

cURL Example

1. Add position animation 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "keyframes": [
      {
        "element_id": "text_001",
        "property": "position",
        "frames": [
          {"time": 0, "value": {"x": 0, "y": 0}},
          {"time": 2000000, "value": {"x": 100, "y": 50}},
          {"time": 5000000, "value": {"x": 200, "y": 100}}
        ],
        "easing": "ease_in_out"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple property animations 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "keyframes": [
      {
        "element_id": "image_001",
        "property": "scale",
        "frames": [
          {"time": 0, "value": 1},
          {"time": 1000000, "value": 1.5},
          {"time": 3000000, "value": 1}
        ],
        "easing": "bounce"
      },
      {
        "element_id": "image_001",
        "property": "rotation",
        "frames": [
          {"time": 0, "value": 0},
          {"time": 2000000, "value": 180},
          {"time": 4000000, "value": 360}
        ],
        "easing": "linear"
      },
      {
        "element_id": "image_001",
        "property": "opacity",
        "frames": [
          {"time": 0, "value": 1},
          {"time": 1500000, "value": 0.5},
          {"time": 3000000, "value": 1}
        ],
        "easing": "ease_in_out"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add keyframe animation function
const addKeyframes = async (draftUrl, keyframeList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_keyframes', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      keyframes: keyframeList
    })
  });
  return response.json();
};

// Usage example
(async () => {
  const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";

  const keyframeList = [
    {
      element_id: "text_001",
      property: "position",
      frames: [
        {time: 0, value: {x: 0, y: 0}},
        {time: 2000000, value: {x: 100, y: 50}},
        {time: 5000000, value: {x: 200, y: 100}}
      ],
      easing: "ease_in_out"
    },
    {
      element_id: "image_001",
      property: "scale",
      frames: [
        {time: 0, value: 1},
        {time: 1000000, value: 1.5},
        {time: 3000000, value: 1}
      ],
      easing: "bounce"
    }
  ];

  const result = await addKeyframes(draftUrl, keyframeList);
  console.log('Keyframes added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

def add_keyframes(draft_url, keyframe_list):
    """Add keyframe animations"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "keyframes": keyframe_list
        }
    )
    return response.json()

# Usage example
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"

keyframe_list = [
    {
        "element_id": "text_001",
        "property": "position",
        "frames": [
            {"time": 0, "value": {"x": 0, "y": 0}},
            {"time": 2000000, "value": {"x": 100, "y": 50}},
            {"time": 5000000, "value": {"x": 200, "y": 100}}
        ],
        "easing": "ease_in_out"
    },
    {
        "element_id": "image_001",
        "property": "scale",
        "frames": [
            {"time": 0, "value": 1},
            {"time": 1000000, "value": 1.5},
            {"time": 3000000, "value": 1}
        ],
        "easing": "bounce"
    }
]

result = add_keyframes(draft_url, keyframe_list)
print(f"Keyframes added successfully: {result['draft_url']}")
Enter fullscreen mode Exit fullscreen mode

Error Code Description

Error Code Error Message Description Solution
400 draft_url is required Missing draft URL parameter Provide a valid draft_url
400 keyframes parameter must be an array keyframes parameter format error Ensure keyframes is an array type
400 element_id cannot be empty Element ID cannot be empty Provide a valid element_id
400 Invalid property type Animation property type error Use preset property types
400 Invalid frame format Keyframe format error Ensure frames format is correct
400 Invalid time format Time parameter format error Time should be a non-negative number
400 Invalid easing function Easing function error Use preset easing functions
404 Draft does not exist Specified draft cannot be found Confirm the draft URL is correct and exists
500 Keyframe animation addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Element ID: Make sure the element_id exists and is unique, used to identify the target element
  2. Time Setting: Time is in microseconds, 1000000 microseconds = 1 second
  3. Keyframe Sequence: Keyframes should be arranged in chronological order
  4. Property Type: Use preset property types to ensure compatibility
  5. Value Range: Ensure that property values are within a reasonable range
  6. Easing Function: Choose appropriate easing functions to make animations more natural
  7. Animation Combination: Multiple properties can be animated simultaneously
  8. Network Stability: Adding keyframe animations requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and keyframes parameters
  2. Validate element_id and property types
  3. Process keyframe time and value settings
  4. Apply easing function
  5. Generate animation objects
  6. Add animations to the corresponding elements
  7. Update draft configuration file
  8. Return updated draft information

Next Steps

After adding keyframe animations, you can continue to use the following interfaces to improve the video:

  • add_videos: Add video materials
  • add_images: Add image materials
  • add_audios: Add audio materials
  • add_captions: Add subtitles
  • add_effects: Add special effects
  • save_draft: Save draft
  • gen_video: Export video

Related Interfaces

πŸ“š Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

Top comments (0)