Kling video and image API

HopBase exposes Kling through Tencent Cloud VOD's AIGC gateway. It is an asynchronous API: submit a task, then poll the HopBase task ID. Use a key that has the Kling VOD account enabled and confirm the exact model IDs with GET /v1/models before sending paid work.

Tencent VOD account

The Kling account must be configured with the Tencent Cloud VOD SecretId, SecretKey, and the VOD application's numeric SubAppId. region is optional for VOD and can normally be left blank. Keep these credentials in the HopBase account configuration; never put them in client requests, examples, or source control. Clients still use HopBase's https://api.hop-base.com/v1 base URL, not a Tencent VOD or TokenHub endpoint.

Endpoints

All requests use Authorization: Bearer sk-your-key and Content-Type: application/json. The body is decoded strictly. Unknown fields, a second JSON value, top-level image_url/video_url, and unverified nested fields are rejected before Tencent is called.

Model matrix

Kling image IDs are kling-image-v3, kling-image-v3-omni, kling-image-o1, kling-image-v2-1, kling-image-v2-1-i2i, kling-image-v2-1-multi-ref, and kling-image-expand. They use the image endpoint, accept n from 1 to 9, and are billed per output image. Use the model catalog for the exact quality tiers available to the current key.

Request contract

Media locators

Each images[] or videos[] item must contain exactly one of:

{ "url": "https://cdn.example.com/file.png" }

or

{ "file_id": "vod-file-id" }

url must be an absolute, publicly reachable http:// or https:// URL. Empty strings, relative paths, file://, ftp://, private / loopback / link-local addresses, URLs with embedded credentials, and both fields together are rejected synchronously at submission. The same rule applies to the image endpoint, face detection, and the avatar extra.sound_file.

Ordinary video generation

Use images[] for frames or image references and videos[] for one reference/edit video. Do not use OpenAI's image_url or video_url fields at the top level.

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> and <<<element_2>>> rotate slowly on a clean studio table",
  "duration": 5,
  "resolution": "1080p",
  "audio": false,
  "images": [
    { "url": "https://cdn.example.com/first.png", "usage": "first_frame" },
    { "file_id": "vod-last-frame", "usage": "last_frame" },
    { "url": "https://cdn.example.com/reference-a.png", "usage": "reference" },
    { "file_id": "vod-reference-b", "usage": "reference" }
  ],
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ],
  "subjects": [
    { "id": "subject-92951593344", "name": "cat" },
    { "id": "subject-92951593345", "name": "dog" }
  ]
}

For ordinary generation, images[].usage is required and is one of first_frame, last_frame, or reference. There can be at most one first frame and one last frame; a last frame requires a first frame. When more than two reference images are present, a last frame is not supported. With kling-v2-1, providing both first and last frames restricts resolution to 1080p. There is at most one videos[] item, and its reference_type is required. A feature video is accepted only by kling-v3-omni and kling-o1. A base video is accepted only by kling-v1-6; it must be the only media input and cannot be combined with images or subjects.

Tencent's coupling limits also apply: with a reference video, reference image count plus subject count is at most 4; without a reference video it is at most 7. Empty prompts are allowed only when a media input supplies the request. Omitted duration, resolution, and audio normalize to 5 seconds, 720P, and silent output.

Subjects and shots

subjects[] uses fixed Tencent subject IDs. Every item requires a non-empty id; name is optional. Subjects are supported by kling-v3-turbo, kling-v3, and kling-v3-omni only. For kling-v3, Tencent VOD also requires at least one images[] item with usage: "reference" whenever subjects are present. Items are positional: subjects[0] is <<<element_1>>>, subjects[1] is <<<element_2>>>, and so on. Every supplied subject must be referenced in the prompt, and a prompt must not reference <<<element_N>>> unless that subject exists.

Shots are supported by kling-v3 and kling-v3-omni only:

{
  "model": "kling-v3-omni",
  "prompt": "A short product story in two shots",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "The box opens", "duration": 2 },
      { "index": 2, "prompt": "The product is revealed", "duration": 3 }
    ]
  }
}

mode is intelligence or customize. Intelligence mode must omit segments; customize mode requires them. Custom segments are numbered consecutively from 1, have non-empty prompts of at most 512 characters, last at least one second, and their durations must sum exactly to the request duration. Use structured shots; raw extra.multi_shot, extra.shot_type, and extra.multi_prompt are rejected.

Motion control

Motion-control tasks require exactly one video followed by exactly one person image. The scene determines their meaning, so do not send usage on the image or reference_type on the video. videos[].keep_original_sound is a boolean and is mapped to Tencent's keep_original_sound flag. The only additional parameter currently verified is extra.character_orientation (image or video). Motion-control duration comes from the input video and must be omitted; the output is temporary.

{
  "model": "kling-v3-motion-control",
  "prompt": "Follow the dancer's movement",
  "resolution": "1080p",
  "images": [{ "file_id": "vod-person-image" }],
  "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
  "extra": { "character_orientation": "video" }
}

Avatar and lip sync

Avatar (kling-avatar) requires 1-5 person images, no videos, and exactly one of extra.sound_file (an HTTP(S) audio URL) or extra.audio_id. The duration is derived from the audio input; omit duration.

Lip sync (kling-lip-sync) accepts no images or videos. First call face detection with one or more media locators:

curl https://api.hop-base.com/v1/kling/faces \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"file_id":"vod-source-video"}]}'

Then submit one face_choose item for the returned session:

{
  "model": "kling-lip-sync",
  "extra": {
    "session_id": "face-session-id",
    "face_choose": [
      { "face_id": "face-1", "sound_file": "https://cdn.example.com/voice.mp3" }
    ]
  }
}

face_choose must contain exactly one item with a non-empty face_id and sound_file. The source audio/video determines duration. Lip-sync billing is per second with a five-second minimum, so a four-second result is billed as five seconds. Raw extra.voice_list and voice_ids are intentionally unavailable until Tencent confirms a matching SKU.

Submit and poll

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"A red ball rolls across a white table","duration":5,"resolution":"720p"}'

The 202 response contains an ID such as kt57x<upstream-task-id>. Poll it without a billing header:

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-your-key"

Statuses are queued, processing, completed, and failed. Completed outputs are HopBase relay URLs; the source is not stored permanently by the plugin. The relay validates the task's file token before fetching Tencent's URL. Billing is produced once by the internal pinned poller only after a successful Tencent FINISH response with ErrCode=0, a valid output, and a billable duration. FINISH with a non-zero ErrCode or ErrCodeExt is a failure and is never charged.

Pricing units and buckets

The model catalog publishes price.unit: video is second, images are image, and face detection is call. Video baseline prices are Tencent's CNY price divided by the site's fixed 6.8 CNY/USD rate; Core applies the group multiplier separately.

Missing or unconfirmed buckets are unavailable rather than silently mapped to a nearby price. In particular, kling-v3-omni 4K silent feature-video pricing is withheld pending a second Tencent confirmation. Caller-selected voices are also withheld: do not send voice_ids or extra.voice_list.