Kling 4.0 · Reference to Video

Generate video from reference images, videos, named subjects and voice samples with Kling 4.0. Submit an asynchronous generation, then query its status to retrieve the finished video.

Developer API pricing

Provider: SeeAPI

USD estimate: $0.0037 / credit · Estimated equivalent, not an additional charge.

720p: 38.1 credits/sec (≈ $0.14/sec, no video) | 22.7 credits/sec (≈ $0.085/sec, with video)

1080p: 56.8 credits/sec (≈ $0.21/sec, no video) | 34.1 credits/sec (≈ $0.13/sec, with video)

Note: Without input video: no-video unit price × output duration. With input video: with-video unit price × [output duration + max(total input video duration, output duration)]. If the input is shorter than the output, billable duration is twice the output duration; otherwise, it is input plus output duration. Total input video duration includes reference videos and subject videos.

Request

POST/v1/generations

AuthorizationSend your API key in the Authorization header using the Bearer scheme.Authorization: Bearer ****************

Header Params

stringrequired

A unique identifier for this generation request, used to make retries safe.

Required; maximum 255 characters.
Reuse the same key only with the same request body; use a new key for a new generation.

max length: 255

Example:: order-20260818-001

Body Params

application/json

stringrequired

Selects the Kling 4.0 model.

Use kling-4-0.

Allowed:kling-4-0

Default:: kling-4-0
Example:: kling-4-0

stringrequired

Selects generation guided by reference media, named subjects or voices.

Use reference-to-video.

Allowed:reference-to-video

Default:: reference-to-video
Example:: reference-to-video

stringoptional

Selects a public provider for this endpoint.

Optional; omit to use the default provider, seeapi.

Allowed:seeapi

Default:: seeapi
Example:: seeapi

objectrequired

Contains the generation prompt, output settings and reference media.

Provide at least one of reference_images, reference_video_urls, elements or voices.
Use publicly accessible HTTPS media URLs. File extensions must match the actual media format.

Provider parameters

SeeAPIseeapiDefault Provider

array <uri>optional

Images that guide the visual appearance, composition or scene. Refer to them in the prompt as @image_1, @image_2 and so on, following array order.

Up to 10 images. JPEG or PNG only, at most 10 MB each.
Each side must be 300–65536 pixels; width-to-height ratio from 0.4 to 2.5.
Ordinary images, ordinary videos, subjects and standalone voices together count toward the 15-reference limit.

max items: 10

array <uri>optional

Videos that guide motion or scene content. Refer to them as @video_1, @video_2 and so on, following array order.

MP4 or MOV, at most 100 MB per file; each video must be 2–30 seconds.
At most 5 input videos in total, including subject videos; their combined duration must not exceed 30 seconds.
Supply the video URL, not a thumbnail or poster image.

max items: 5

array <object>optional

Named subjects that preserve the identity of a person, animal, object or other visual element. Reference a subject in the prompt with @ followed by its name.

Up to 7 subjects, of which at most 3 may use video.
Each subject needs 2–4 images or one video; do not provide both for the same subject.
Subjects also count toward the combined 15-reference limit.

max items: 7

Example:: [{"name":"subject_1","image_urls":["https://client.example.com/front.png","https://client.example.com/side.png"]}]

stringrequired

The name used to refer to this subject in the prompt, for example @hero.

1–20 Chinese characters, letters, digits or underscores.
Names must be unique across subjects and voices, ignoring case. Reserved reference names are unavailable.

min length: 1max length: 20

Example:: subject_1

array <uri>optional

Multiple views of the same subject; the first image is the primary view.

Provide 2–4 JPEG or PNG images.
Required when video_url is absent; mutually exclusive with video_url.

min items: 2max items: 4

Example:: ["https://client.example.com/front.png","https://client.example.com/side.png"]

string <uri>optional

A continuous single-shot video of a character to use as the named subject.

MP4, at most 5 MB; duration 3–8 seconds.
Width and height must both be at least 700 pixels. Avoid cuts or transitions.
Mutually exclusive with image_urls; video subjects support character only.
Subject videos count toward the combined 5-video and 30-second input limits.

stringoptional

Describes the subject category to help interpret the supplied visual material.

Allowed values: character, animal, prop, costume, scene, effect, others.
Video subjects must use character. A bound voice is supported only for a character.

Allowed:characteranimalpropcostumesceneeffectothers

stringoptional

A short description that clarifies the subject and its distinguishing traits.

Maximum 100 characters.

max length: 100

string <uri>optional

A speech sample that binds a voice to this character.

Character subjects only. MP3 or WAV, 5–30 seconds, at most 20 MB.
Use clear speech without long pauses. The sample is used in full, without automatic trimming.
A bound voice cannot be referenced separately and does not consume a standalone voice slot.

array <object>optional

Named speech samples that can be referenced independently in the prompt.

Up to 3 standalone voices; these also count toward the combined 15-reference limit.

max items: 3

Example:: [{"name":"voice_1","audio_url":"https://client.example.com/voice.wav"}]

stringrequired

The name used to reference this voice in the prompt, for example @narrator.

1–20 Chinese characters, letters, digits or underscores.
Unique across subjects and voices, ignoring case; reserved reference names are unavailable.

min length: 1max length: 20

Example:: voice_1

string <uri>required

An HTTPS URL to the speech sample for this voice.

MP3 or WAV, 5–30 seconds, at most 20 MB.
Use clear speech without long pauses. Samples are used in full, without automatic trimming.

Example:: https://client.example.com/voice.wav

booleanoptional

Controls whether to preserve original sound from ordinary reference videos.

Default: false.
Available when reference_video_urls is supplied.

Default:: false

stringrequired

Describe the scene, action, camera movement and any dialogue. Use @ references to identify the supplied media, subjects and voices.

Required; maximum 8000 characters.
Every @ reference must match a supplied item. Subject and voice references use their configured names.

max length: 8000

Example:: @subject_1 walks through a sunlit garden, turns toward the camera and smiles. Smooth tracking shot, natural movement.

numberoptional

The requested output video length, in seconds.

Integer from 3 to 30; default 5.
This is the output length, not the duration of the reference media.

min: 3max: 30

Default:: 5

stringoptional

The output video resolution.

Choose 720p or 1080p; default 720p.

Allowed:720p1080p

Default:: 720p

stringoptional

The output video aspect ratio.

Choose auto, 16:9, 9:16, 1:1 or 21:9; default auto.

Allowed:auto16:99:161:121:9

Default:: auto

string <uri>optional

Your HTTPS endpoint for receiving the terminal generation webhook.

Optional. Maximum 2048 characters.
Verify webhook signatures before trusting the event; see the Callbacks section.

max length: 2048

Example:: https://client.example.com/webhooks/seeapi

Responses

202The request has been accepted and generation is processing.

Bodyapplication/json

Query the generation identifier to retrieve the final status and video assets, or wait for your terminal webhook.

objectrequired

The accepted generation and its current processing status.

stringrequired

The generation identifier. Save it to query status and retrieve the result.

Example:: task_xxx

stringrequired

The model used for this generation.

Example:: kling-4-0

stringrequired

The endpoint used for this generation.

Example:: reference-to-video

stringrequired

The selected public provider.

Allowed:seeapi

seeapi: SeeAPI

Example:: seeapi

stringrequired

The current generation state. Processing does not mean the video is ready.

Allowed:processing

Example:: processing

numberrequired

The estimated charge in public credits for this request.

Example:: 190.5

numberrequired

Credits consumed by this generation so far.

Example:: 0

numberrequired

Credits refunded for this generation so far.

Example:: 0

string <date-time>required

The time the generation was created, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

string <date-time>required

The time the generation was last updated, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this is a replay of an earlier request with the same idempotency key.

Example:: false

200An existing generation request is returned for an idempotent retry.

Bodyapplication/json

This response does not create a second generation. Continue querying the returned generation identifier.

objectrequired

The accepted generation and its current processing status.

stringrequired

The generation identifier. Save it to query status and retrieve the result.

Example:: task_xxx

stringrequired

The model used for this generation.

Example:: kling-4-0

stringrequired

The endpoint used for this generation.

Example:: reference-to-video

stringrequired

The selected public provider.

Allowed:seeapi

seeapi: SeeAPI

Example:: seeapi

stringrequired

The current generation state. Processing does not mean the video is ready.

Allowed:processing

Example:: processing

numberrequired

The estimated charge in public credits for this request.

Example:: 190.5

numberrequired

Credits consumed by this generation so far.

Example:: 0

numberrequired

Credits refunded for this generation so far.

Example:: 0

string <date-time>required

The time the generation was created, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

string <date-time>required

The time the generation was last updated, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this is a replay of an earlier request with the same idempotency key.

Example:: false

400

Invalid JSON, parameters, Schema, or API Policy

401

Invalid API Key or authentication failed

402

Insufficient credits

403

The current request is not allowed

404

Model, Endpoint, or task not found

409

Idempotency conflict or the same request is still being created

413

Request body is too large

429

Too many requests

503

Service temporarily unavailable

Related Resources

Market Overview

Explore all available models

Credits & Billing

View credit balance, plans, and billing activity

Usage

Review API usage and credit consumption

Query Task Status

After submitting a task, use the unified query endpoint to check progress and retrieve results:

Get Task DetailsLearn how to query task status and retrieve generation results

Submit requests from your server using a Bearer API key. Store the generation identifier and use Get Task Details to check progress and retrieve the result. Acceptance does not mean the video is complete.

Callbacks

Manage the secret used to verify generation webhook signatures. Callback URLs are supplied when you create each generation.

Webhook flow

Callback URL per generation.

Webhook signing key

Code Examples

Request

const response = await fetch("https://api.seeapi.com/v1/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Idempotency-Key": "order-20260818-001",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "kling-4-0",
  "endpoint": "reference-to-video",
  "provider": "seeapi",
  "input": {
    "elements": [
      {
        "name": "subject_1",
        "image_urls": [
          "https://client.example.com/front.png",
          "https://client.example.com/side.png"
        ],
        "tag": "character"
      }
    ],
    "voices": [
      {
        "name": "voice_1",
        "audio_url": "https://client.example.com/voice.wav"
      }
    ],
    "keep_original_sound": false,
    "prompt": "@subject_1 walks through a sunlit garden, turns toward the camera and smiles. Smooth tracking shot, natural movement.",
    "duration_seconds": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  },
  "callback_url": "https://client.example.com/webhooks/seeapi"
})
});

const result = await response.json();

ResponseHTTP 202

{
  "generation": {
    "id": "task_xxx",
    "model": "kling-4-0",
    "endpoint": "reference-to-video",
    "provider": "seeapi",
    "status": "processing",
    "estimated_credits": 190.5,
    "consumed_credits": 0,
    "refunded_credits": 0,
    "created_at": "2026-08-18T10:00:00Z",
    "updated_at": "2026-08-18T10:00:00Z"
  },
  "idempotent": false
}

const response = await fetch("https://api.seeapi.com/v1/generations", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "order-20260818-001", "Content-Type": "application/json" }, body: JSON.stringify({ "model": "kling-4-0", "endpoint": "reference-to-video", "provider": "seeapi", "input": { "elements": [ { "name": "subject_1", "image_urls": [ "https://client.example.com/front.png", "https://client.example.com/side.png" ], "tag": "character" } ], "voices": [ { "name": "voice_1", "audio_url": "https://client.example.com/voice.wav" } ], "keep_original_sound": false, "prompt": "@subject_1 walks through a sunlit garden, turns toward the camera and smiles. Smooth tracking shot, natural movement.", "duration_seconds": 5, "resolution": "720p", "aspect_ratio": "auto" }, "callback_url": "https://client.example.com/webhooks/seeapi" }) }); const result = await response.json();

{ "generation": { "id": "task_xxx", "model": "kling-4-0", "endpoint": "reference-to-video", "provider": "seeapi", "status": "processing", "estimated_credits": 190.5, "consumed_credits": 0, "refunded_credits": 0, "created_at": "2026-08-18T10:00:00Z", "updated_at": "2026-08-18T10:00:00Z" }, "idempotent": false }

Responses

202The request has been accepted and generation is processing.

Bodyapplication/json

Query the generation identifier to retrieve the final status and video assets, or wait for your terminal webhook.

objectrequired

The accepted generation and its current processing status.

stringrequired

The generation identifier. Save it to query status and retrieve the result.

Example:: task_xxx

stringrequired

The model used for this generation.

Example:: kling-4-0

stringrequired

The endpoint used for this generation.

Example:: reference-to-video

stringrequired

The selected public provider.

Allowed:seeapi

seeapi: SeeAPI

Example:: seeapi

stringrequired

The current generation state. Processing does not mean the video is ready.

Allowed:processing

Example:: processing

numberrequired

The estimated charge in public credits for this request.

Example:: 190.5

numberrequired

Credits consumed by this generation so far.

Example:: 0

numberrequired

Credits refunded for this generation so far.

Example:: 0

string <date-time>required

The time the generation was created, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

string <date-time>required

The time the generation was last updated, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this is a replay of an earlier request with the same idempotency key.

Example:: false

200An existing generation request is returned for an idempotent retry.

Bodyapplication/json

This response does not create a second generation. Continue querying the returned generation identifier.

objectrequired

The accepted generation and its current processing status.

stringrequired

The generation identifier. Save it to query status and retrieve the result.

Example:: task_xxx

stringrequired

The model used for this generation.

Example:: kling-4-0

stringrequired

The endpoint used for this generation.

Example:: reference-to-video

stringrequired

The selected public provider.

Allowed:seeapi

seeapi: SeeAPI

Example:: seeapi

stringrequired

The current generation state. Processing does not mean the video is ready.

Allowed:processing

Example:: processing

numberrequired

The estimated charge in public credits for this request.

Example:: 190.5

numberrequired

Credits consumed by this generation so far.

Example:: 0

numberrequired

Credits refunded for this generation so far.

Example:: 0

string <date-time>required

The time the generation was created, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

string <date-time>required

The time the generation was last updated, in ISO 8601 format.

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this is a replay of an earlier request with the same idempotency key.

Example:: false

400

Invalid JSON, parameters, Schema, or API Policy

401

Invalid API Key or authentication failed

402

Insufficient credits

403

The current request is not allowed

404

Model, Endpoint, or task not found

409

Idempotency conflict or the same request is still being created

413

Request body is too large

429

Too many requests

503

Service temporarily unavailable