--- title: "Advanced Custom Elements - Create element" method: POST path: "/v1/ai/video/kling-advanced-custom-elements" tags: ["video", "advanced-custom-elements", "background_tasks"] deprecated: true --- # Advanced Custom Elements - Create element `POST /v1/ai/video/kling-advanced-custom-elements` ## Request - Base URL: `https://api.magnific.com` - URL: `https://api.magnific.com/v1/ai/video/kling-advanced-custom-elements` - Auth: API key in header `x-magnific-api-key` > **Deprecated.** **Deprecated.** This endpoint is deprecated. You can pass reference images directly in the `elements` array of the Kling V3 video generation endpoints (`/ai/video/kling-v3-pro`, `/ai/video/kling-v3-std`) without needing to pre-create elements. Create reusable custom elements (characters, animals, items, costumes, scenes, effects) from reference images or videos. Elements can be referenced in Kling video generation tasks for consistent identity across videos. **Features:** - Create elements from multi-angle reference images or a reference video - Supports character, animal, item, costume, scene, and effect element types - Optionally bind a voice to the element for video generation with speech - Elements can be reused across multiple video generation tasks **Reference types:** - `image_refer`: Create element from 1 frontal image + up to 3 additional reference images from different angles - `video_refer`: Create element from a single reference video (3-8 seconds, 1080P, mp4/mov) ## Request body - AdvancedCustomElementsRequest - `element_name` string, required: Name of the custom element. Must not exceed 20 characters. - `element_description` string, required: Description of the custom element. Must not exceed 100 characters. - `reference_type` 'image_refer' | 'video_refer', required: Reference method for defining the element's appearance: - `image_refer`: Multi-Image Elements. The element appearance is defined from reference images (element_image_list). Supported formats: .jpg, .jpeg, .png. Max 10MB per image. Min 300px dimensions. Aspect ratio between 1:2.5 and 2.5:1. - `video_refer`: Video Character Elements. The element appearance is defined from a reference video (element_video_list). Only .mp4/.mov formats, 1080P, 3-8 seconds duration, 16:9 or 9:16 aspect ratio, max 200MB. - `element_image_list` AdvancedCustomElementsImageList: Reference images for defining the element. Required when reference_type is `image_refer`, ignored when reference_type is `video_refer`. Provide one frontal reference image and 1 to 3 additional reference images from different angles or close-ups. - `frontal_image` string, required: Frontal reference image URL or Base64 encoding. At least one frontal reference image is required. Supported formats: .jpg, .jpeg, .png. Max file size: 10MB. Min dimensions: 300px. Aspect ratio: 1:2.5 to 2.5:1. - `refer_images` AdvancedCustomElementsReferImage[], required: 1 to 3 additional reference images from other angles or close-ups. These should differ from the frontal reference image. - `image_url` string, required: Reference image URL or Base64 encoding. Supported formats: .jpg, .jpeg, .png. Max file size: 10MB. Min dimensions: 300px. - `element_video_list` AdvancedCustomElementsVideoList: Reference video for defining the element. Required when reference_type is `video_refer`, ignored when reference_type is `image_refer`. Only one video can be uploaded. If the video contains human voice, voice tone customization will be initiated. - `refer_videos` AdvancedCustomElementsReferVideo[], required: Reference videos. Only 1 video can be uploaded. - `video_url` string, required: Reference video URL. Only .mp4/.mov formats supported. Must be 1080P with duration between 3 and 8 seconds, aspect ratio 16:9 or 9:16. Max file size: 200MB. - `element_voice_id` string: Bind the element to an existing voice from the tone library. When empty, the element is not bound to a voice. The voice ID can be obtained through the voice-related API. Only elements customized via video reference support voice binding. - `tag_list` AdvancedCustomElementsTag[]: Configure category tags for the element. One element can have multiple tags. - `tag_id` 'o_101' | 'o_102' | 'o_103' | 'o_104' | 'o_105' | 'o_106' | 'o_107' | 'o_108', required: Tag category for the element: - `o_101`: Hottest - `o_102`: Character - `o_103`: Animal - `o_104`: Item - `o_105`: Costume - `o_106`: Scene - `o_107`: Effect - `o_108`: Others - `webhook_url` string, uri: Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field. ## Response `200` OK - Task created successfully - unknown ## Other responses - `400`: Bad Request - The server could not understand the request due to invalid syntax. - `401`: Unauthorized - The client must authenticate itself to get the requested response. - `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle. - `503`: Service Unavailable --- [API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)