Create element

January 12, 2026 (March 6, 2026)

Table of contents

  1. Request Headers
  2. Request Body
    1. Secondary Images (IMAGE only)
    2. Auto-Generate Views (IMAGE only)
  3. Responses
  4. Model
  5. Usage After Creation
  6. Examples
  7. Try It

This endpoint creates one or more elements from a cover image or video. Elements are saved character/object references that can be reused across multiple generations in POST /images/omni and POST /videos/omni using the @element_N syntax.

There are two element types:

  • IMAGE elements: Created from a coverImage, with optional multi-angle views
  • VIDEO elements: Created from a video URL (mp4, minimum 3 seconds, auto-trimmed to 8s), with optional voice assignment. VIDEO elements can only be used in v3 video generation via POST /videos/omni.
Feature IMAGE VIDEO
Input coverImage video (mp4, min 3s, auto-trimmed to 8s)
voice support ✅ (character tag only) ✅ (character tag only)
Auto voice extraction ❌ ✅ (character tag, 5-60s video)
Custom voice from URL ✅ (mp4, 5-60s) ✅ (mp4, 5-60s)
extraImage1/2/3 ✅ ❌
generateViews ✅ ❌
Used in O1 omni ✅ ❌
Used in v3 omni ✅ ✅

The generateViews option (IMAGE only) uses AI to create multiple variations of your element with different angles, which can produce up to 3 separate elements from a single image. You can review the results and delete ones you don’t like using DELETE /elements/elementId.

https://api.useapi.net/v1/kling/elements

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
Request Body 
{
  "email": "[email protected]",
  "name": "MyCharacter",
  "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
  "tag": "character"
}

  • email is optional when only one account configured. However, if you have multiple accounts configured, this parameter becomes required.

  • name is required, the base name for the element. Maximum length: 15 characters. A 5-character random suffix is automatically appended (e.g., “MyChar” becomes “MyChar ABC12”).

  • coverImage is required for IMAGE elements, the URL of the primary image. You can upload images using POST /assets and use the returned URL here. Cannot be used together with video.

  • video is required for VIDEO elements, the URL of a video (mp4 format, minimum 3 seconds). You can upload videos using POST /assets and use the returned URL here. The video is preprocessed to extract a cover frame and normalized video. Videos longer than 8 seconds are automatically trimmed. Minimum 700px shortest edge. Cannot be used together with coverImage.

  • voice is optional (character tag required), the voice to assign to the element. Accepts an official voice name/ID from GET /elements/voices, or a video URL (mp4, 5-60 seconds) to extract a custom voice from. For VIDEO elements without an explicit voice, voice extraction is automatically attempted from the video (requires 5-60 seconds with audio; silently skipped if video is too short). Voice is only supported for elements with the character tag.

  • description is optional, a text description of the element. Maximum length: 100 characters. If not provided, a description is automatically generated from the image using AI.

  • tag is optional, the category tag for the element. Use GET /elements/tags to get available tags. Accepts either id or tagKey (e.g., “1” or “character”). If not provided, the tag is automatically detected from the image using AI.

Secondary Images (IMAGE only)

You can optionally provide additional angle/view images:

  • extraImage1 is optional, URL of first additional view.
  • extraImage2 is optional, URL of second additional view.
  • extraImage3 is optional, URL of third additional view.

Maximum 3 secondary images allowed. Cannot be used together with generateViews or video.

Auto-Generate Views (IMAGE only)
  • generateViews is optional, set to true to have AI generate 3 multi-angle variations. When enabled, the system generates different views of your element automatically. This can create up to 3 separate elements, one for each variation group. Cannot be used together with extraImage1/2/3 or video. This call can take up to 60 seconds to complete since generation takes time.
Responses

  • 200 OK

    Standard response (without generateViews):

    {
  "elements": [
    {
      "id": "u_123456789012345",
      "name": "MyCharacter ABC12",
      "userId": 12345678,
      "description": "AI-generated description of the character",
      "cover": {
        "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
        "width": 768,
        "height": 1365,
        "resourceKey": "cover",
        "cover": true,
        "slotKey": ""
      },
      "resources": [
        {
          "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
          "width": 768,
          "height": 1365,
          "resourceKey": "cover",
          "cover": true,
          "slotKey": ""
        }
      ],
      "tagList": [],
      "createTime": 1736640000000,
      "updateTime": 1736640000000,
      "favored": false,
      "official": false
    }
  ],
  "count": 1
}

    Response with generateViews (creates up to 3 separate elements, each with 4 views):

    {
  "elements": [
    {
      "id": "u_123456789012345",
      "name": "MyCharacter ABC12",
      "userId": 12345678,
      "description": "AI-generated description",
      "cover": {
        "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg",
        "resourceKey": "cover",
        "cover": true,
        "slotKey": ""
      },
      "resources": [
        { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" },
        { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" },
        { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" },
        { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" }
      ],
      "tagList": []
    },
    {
      "id": "u_234567890123456",
      "name": "MyCharacter DEF34",
      "description": "AI-generated description",
      "resources": [
        { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" },
        { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" },
        { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" },
        { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" }
      ],
      "tagList": []
    }
  ],
  "count": 2
}

  • 400 Bad Request

    {
  "error": "<error message>"
}

  • 401 Unauthorized

    {
  "error": "Unauthorized",
  "code": 401
}
Model 
{ // TypeScript, all fields are optional
  elements: {
    id: string
    name: string
    userId: number
    type: 'IMAGE' | 'VIDEO'
    description: string
    cover: {
      resource: string
      width: number
      height: number
      resourceKey: 'cover' | 'secondary' | 'video'
      cover: boolean
      slotKey: string
    }
    resources: {
      resource: string
      width: number
      height: number
      resourceKey: 'cover' | 'secondary' | 'video'
      cover: boolean
      slotKey: string
      voice: {
        id: number
        name: string
        official: boolean
        resource: object
      }
    }[]
    tagList: object[]
    voice: {
      id: number
      name: string
      official: boolean
      resource: object
    }
    currentVersion: number
    createTime: number
    updateTime: number
    favored: boolean
    official: boolean
  }[]
  count: number
}
Usage After Creation

Once created, you can use element IDs in POST /images/omni, POST /videos/omni, and POST /videos/motion-create:

{
  "prompt": "Character @element_1 walking through a beautiful garden",
  "element_1": "u_123456789012345"
}
Examples 
  • curl -X POST "https://api.useapi.net/v1/kling/elements" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "[email protected]",
     "name": "FashionLady",
     "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
     "tag": "character"
   }'

  • const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/elements";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    name: "FashionLady",
    coverImage: "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
    tag: "character"
  })
});
const result = await response.json();
console.log("response", {response, result});

  • import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/elements"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "name": "FashionLady",
    "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg",
    "tag": "character"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
Try It