[JCAIGC]Get image entrance/exit animation list

get_image_animations API Documentation

Interface Overview

Interface Name: get_image_animations

Interface URL: POST /openapi/capcut-mate/v1/get_image_animations

Function Description: Get image entrance/exit animation list, returns all supported image entrance/exit animations that meet the conditions. Supports filtering by animation type (entrance, exit, loop) and membership mode (all, VIP, free).

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
mode	integer	No	0	Animation mode: 0=all, 1=VIP, 2=free
type	string	Yes	-	Animation type: in=entrance, out=exit, loop=loop

Animation Mode Description

Mode Value	Mode Name	Description
0	All	Returns all animations (including VIP and free)
1	VIP	Returns only VIP animations
2	Free	Returns only free animations

Animation Type Description

Type Value	Type Name	Description
in	Entrance Animation	Animation effect when image appears
out	Exit Animation	Animation effect when image disappears
loop	Loop Animation	Continuous loop animation effect for image

Request Examples

Get All Entrance Animations

{
  "mode": 0,
  "type": "in"
}

Get VIP Exit Animations

{
  "mode": 1,
  "type": "out"
}

Get Free Loop Animations

{
  "mode": 2,
  "type": "loop"
}

Response Format

Success Response

{
  "effects": "[{\"resource_id\":\"7314291622525538843\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"35395178\",\"name\":\"冰雪飘动\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/459c196951cadbd024456a63db89481f\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"},{\"resource_id\":\"7397306443147252233\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"77035159\",\"name\":\"变色输入\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/c15f5c313f8170c558043abf300a0692\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"}]"
}

Animation Object Structure

Each animation object contains the following fields:

Field Name	Type	Description
resource_id	string	Animation resource ID
type	string	Animation type (in/out/loop)
category_id	string	Animation category ID
category_name	string	Animation category name
duration	integer	Animation duration (microseconds)
id	string	Animation unique identifier
name	string	Animation name
request_id	string	Request ID (usually empty)
start	integer	Animation start time
icon_url	string	Animation icon URL
material_type	string	Material type (usually "sticker")
panel	string	Panel information
path	string	Path information
platform	string	Supported platforms (usually "all")

Error Response

400 Bad Request - Parameter Validation Failed

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "type parameter must be in, out, or loop"
  }
}

500 Internal Server Error - Failed to Get Animations

{
  "error": {
    "code": "IMAGE_ANIMATION_GET_FAILED",
    "message": "Failed to get image animations",
    "details": "Failed to get animation data"
  }
}

Error Codes

Error Code	HTTP Status Code	Description	Solution
VALIDATION_ERROR	400	Request parameter validation failed	Check if type parameter is in/out/loop and mode parameter is 0/1/2
IMAGE_ANIMATION_GET_FAILED	500	Failed to get image animations	Check service status and try again later

Usage Instructions

Parameter Instructions

1. type parameter: Required parameter, can only choose one of "in", "out", "loop"
2. mode parameter: Optional parameter, default is 0 (all animations)
3. Response data: The effects field is in JSON string format and needs to be parsed before use

Animation Application Scenarios

1. Entrance Animation (in):

   • Applicable for scenes where images appear
   • Such as fade-in effects, zoom entrance, slide entrance, etc.
   • Usually lasts between 0.5-1 seconds

2. Exit Animation (out):

   • Applicable for scenes where images disappear
   • Such as fade-out effects, zoom out, rotate exit, etc.
   • Usually lasts between 0.6-0.8 seconds

3. Loop Animation (loop):

   • Applicable for images that need to continuously attract attention
   • Such as slight shaking, zoom breathing effect, etc.
   • Usually lasts between 1-1.2 seconds and can loop infinitely

Usage Recommendations

• Choose appropriate animation types based on video content style
• VIP animations usually have better effects but require membership privileges
• It is recommended to first get all animations, then filter as needed
• Can combine animation preview images (icon_url) for users to choose
• Image animations should be more natural and smooth than text animations

Example Code

JavaScript Example

// Get all entrance animations
const getImageInAnimations = async () => {
  const response = await fetch('/openapi/capcut-mate/v1/get_image_animations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 0,
      type: 'in'
    })
  });

  const result = await response.json();
  const animations = JSON.parse(result.effects);
  console.log('Image entrance animations list:', animations);
};

// Get free loop animations
const getFreeImageLoopAnimations = async () => {
  const response = await fetch('/openapi/capcut-mate/v1/get_image_animations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 2,
      type: 'loop'
    })
  });

  const result = await response.json();
  const animations = JSON.parse(result.effects);
  console.log('Free image loop animations list:', animations);
};

Python Example

import requests
import json

def get_image_animations(mode=0, animation_type='in'):
    """Get image animations list"""
    url = 'http://localhost:8000/v1/get_image_animations'
    data = {
        'mode': mode,
        'type': animation_type
    }

    response = requests.post(url, json=data)
    if response.status_code == 200:
        result = response.json()
        animations = json.loads(result['effects'])
        return animations
    else:
        print(f"Request failed: {response.status_code}")
        return []

# Usage example
in_animations = get_image_animations(mode=0, animation_type='in')
print(f"Got {len(in_animations)} image entrance animations")

vip_out_animations = get_image_animations(mode=1, animation_type='out')
print(f"Got {len(vip_out_animations)} VIP image exit animations")

Related Interfaces

• add_images - Batch add images (can use animation effects)
• add_effects - Add video effects
• get_text_animations - Get text entrance/exit animations

Technical Implementation

File Structure

src/
├── schemas/get_image_animations.py    # Request/response data models
├── service/get_image_animations.py    # Business logic implementation
└── router/v1.py                       # API route definition

Core Logic

1. Parameter Validation: Validate the validity of type and mode parameters
2. Data Filtering: Filter image animation data based on type and mode parameters
3. Data Formatting: Convert animation data to JSON string format
4. Response Return: Return API response that conforms to specifications

Data Source

Currently using mock data, in actual projects should:

• Get image animation data from database
• Or get animation resources from third-party API
• Support dynamic updates of animation resources
• Distinguish between different characteristics of image animations and text animations

---

Version Information: v1.0

Last Updated: 2024-09-24

---

📚 Project Resources

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

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