Create custom subject

Create a Kling custom subject from images or a video; put the resulting subject ID in `subjects[].id` of a video request.

POST/v1/kling/subjects

image_refer needs one frontal image plus 1–3 supporting reference images; video_refer needs one video and can optionally bind a voice_id. The fields of the two methods cannot be mixed. Every URL must be a public absolute HTTP(S) address, following the same rules as Media locators.

Creation is an async task and is currently free. Submission returns 202 and a task id (object is kling.subject.task); poll with Get video task. When done, the result carries element_ids (an array of subject IDs) and elements (each with id, possibly with info).

The request body is a strict JSON contract: fields outside the table return 400 before the task is created. All field validation happens before submission, so an invalid request never creates a task.

Create custom subject

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Orange cat",
    "description": "Short-haired orange cat with green eyes",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/cat-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/cat-side.png",
      "https://cdn.example.com/cat-back.png"
    ]
  }'

202application/json

{
  "id": "ktEXAMPLE",
  "object": "kling.subject.task",
  "status": "queued",
  "created": 1790000000
}

Headers

Authorization:requiredstring

Bearer sk-…: an API key created in the console under API keys; its group must include the requested model

Body parametersJSON

name:requiredstring

Subject name; leading and trailing whitespace is trimmed

Length1–20 chars

description:optionalstring

Subject description

Length≤ 100 chars

reference_type:requiredstring

image_refer creates from images; video_refer creates from one video

Valuesimage_refervideo_refer

frontal_image_url:optionalstring

Frontal image URL; required for image_refer, not allowed with video_refer. Must be a publicly accessible absolute HTTP(S) address

Length≥ 1 chars

reference_image_urls:optionalarray of string

Supporting reference image URLs; required for image_refer, 1–3 of them, none may duplicate the frontal image or each other; not allowed with video_refer

Items1–3

video_url:optionalstring

Video URL; required for video_refer, not allowed with image_refer. Must be a publicly accessible absolute HTTP(S) address

Length≥ 1 chars

voice_id:optionalstring

Voice bound to the subject; video_refer only

tag_ids:optionalarray of string

Tag IDs used to categorize the subject; each must be non-empty and unique

Returns

202Accepted; returns the subject creation task

id:optionalstring

Task ID; poll it with GET /v1/video/tasks/{task_id}

object:optionalstring

Always kling.subject.task

status:optionalstring

Always queued

created:optionalinteger

Creation time, Unix seconds

Errors

400Validation failed before submission; no task is created. Messages include: request body does not match the JSON contract: …: invalid JSON, a field outside the table, or a second JSON value after the request body name is required, name cannot exceed 20 characters, description cannot exceed 100 characters reference_type must be image_refer or video_refer reference_type=image_refer does not accept video_url, voice_id is only supported with reference_type=video_refer, reference_type=video_refer does not accept image references reference_image_urls must contain 1 to 3 reference images different from the frontal image, reference_image_urls[<index>] duplicates the frontal image or another reference image <field> is required, <field>.url must be a publicly accessible absolute http(s) URL tag_ids[<index>] cannot be empty, tag_ids[<index>] is duplicated

401Missing, invalid or expired API key (missing_api_key / invalid_api_key / api_key_expired)

Headers

Body parametersJSON

Returns

Errors

Related