---
title: "Run Kling O3 (kling-o3)"
method: POST
path: "/models/kling-o3"
tags: ["Run a model"]
---

# Run Kling O3 (kling-o3)

`POST /models/kling-o3`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/models/kling-o3`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Clips up to 15 seconds with native audio.

Submits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` — each item in its `outputs[]` follows the `OutputItem` schema — or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.

## Headers

- `Idempotency-Key` string

## Request body

- SubmitBodyKlingO3
  - `input` union, required: Model-specific inputs for `kling-o3`.
    - object
      - `num_outputs` 1: Number of outputs generated per job. Only 1 is supported.
      - `prompt` string: Generation prompt. At most 2500 characters.
      - `multi_prompt` object[]: Multi-shot storyboard; each shot carries its own prompt and duration. Shot durations must sum to at most 15000 ms, and the storyboard replaces `prompt` — supply one or the other, never both. A shot's prompt has no length limit, unlike the single `prompt` field. 1 to 6 items.
        - `prompt` string, required: The prompt for this shot.
        - `duration_ms` 1000 | 2000 | 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000: Duration of this shot in milliseconds.
      - `shot_type` 'customize' | 'intelligent': How a multi-shot storyboard is cut. 'customize' honours each shot's declared duration; 'intelligent' lets the model determine the shot structure. Ignored unless `multi_prompt` is supplied.
      - `generate_audio` boolean: Whether to generate native audio for the video.
      - `aspect_ratio` '16:9' | '9:16' | '1:1', required: Output aspect ratio.
      - `resolution` '1080p' | '4K', required: Output resolution.
      - `duration_ms` 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000, required: Duration in ms.
      - `start_image` union, required: Start frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `end_image` union: End frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `images` union[]: Reference images. 1 to 3 images, each with an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - union
          - object: A file uploaded via POST /v3/files, referenced by the returned url.
            - `source` 'url', required
            - `url` string, uri, required: A URL returned by POST /v3/files.
          - object: An existing asset you own, referenced by its id.
            - `source` 'asset', required
            - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `quality` 'pro': Quality level to generate at. `standard` — the 720p tier. `pro` — the high-resolution tier, at 1080p and 4K.
    - object
      - `num_outputs` 1: Number of outputs generated per job. Only 1 is supported.
      - `prompt` string: Generation prompt. At most 2500 characters.
      - `multi_prompt` object[]: Multi-shot storyboard; each shot carries its own prompt and duration. Shot durations must sum to at most 15000 ms, and the storyboard replaces `prompt` — supply one or the other, never both. A shot's prompt has no length limit, unlike the single `prompt` field. 1 to 6 items.
        - `prompt` string, required: The prompt for this shot.
        - `duration_ms` 1000 | 2000 | 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000: Duration of this shot in milliseconds.
      - `shot_type` 'customize' | 'intelligent': How a multi-shot storyboard is cut. 'customize' honours each shot's declared duration; 'intelligent' lets the model determine the shot structure. Ignored unless `multi_prompt` is supplied.
      - `generate_audio` boolean: Whether to generate native audio for the video.
      - `aspect_ratio` '16:9' | '9:16' | '1:1', required: Output aspect ratio.
      - `resolution` '1080p' | '4K', required: Output resolution.
      - `duration_ms` 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000, required: Duration in ms.
      - `start_image` union: Start frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `end_image` union: End frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `images` union[], required: Reference images. 1 to 3 images, each with an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - union
          - object: A file uploaded via POST /v3/files, referenced by the returned url.
            - `source` 'url', required
            - `url` string, uri, required: A URL returned by POST /v3/files.
          - object: An existing asset you own, referenced by its id.
            - `source` 'asset', required
            - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `quality` 'pro': Quality level to generate at. `standard` — the 720p tier. `pro` — the high-resolution tier, at 1080p and 4K.
    - object
      - `num_outputs` 1: Number of outputs generated per job. Only 1 is supported.
      - `prompt` string: Generation prompt. At most 2500 characters.
      - `multi_prompt` object[]: Multi-shot storyboard; each shot carries its own prompt and duration. Shot durations must sum to at most 15000 ms, and the storyboard replaces `prompt` — supply one or the other, never both. A shot's prompt has no length limit, unlike the single `prompt` field. 1 to 6 items.
        - `prompt` string, required: The prompt for this shot.
        - `duration_ms` 1000 | 2000 | 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000: Duration of this shot in milliseconds.
      - `shot_type` 'customize' | 'intelligent': How a multi-shot storyboard is cut. 'customize' honours each shot's declared duration; 'intelligent' lets the model determine the shot structure. Ignored unless `multi_prompt` is supplied.
      - `generate_audio` boolean: Whether to generate native audio for the video.
      - `aspect_ratio` '16:9' | '9:16' | '1:1', required: Output aspect ratio.
      - `resolution` '720p': Output resolution.
      - `duration_ms` 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000, required: Duration in ms.
      - `start_image` union, required: Start frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `end_image` union: End frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `images` union[]: Reference images. 1 to 3 images, each with an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - union
          - object: A file uploaded via POST /v3/files, referenced by the returned url.
            - `source` 'url', required
            - `url` string, uri, required: A URL returned by POST /v3/files.
          - object: An existing asset you own, referenced by its id.
            - `source` 'asset', required
            - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `quality` 'standard': Quality level to generate at. `standard` — the 720p tier. `pro` — the high-resolution tier, at 1080p and 4K.
    - object
      - `num_outputs` 1: Number of outputs generated per job. Only 1 is supported.
      - `prompt` string: Generation prompt. At most 2500 characters.
      - `multi_prompt` object[]: Multi-shot storyboard; each shot carries its own prompt and duration. Shot durations must sum to at most 15000 ms, and the storyboard replaces `prompt` — supply one or the other, never both. A shot's prompt has no length limit, unlike the single `prompt` field. 1 to 6 items.
        - `prompt` string, required: The prompt for this shot.
        - `duration_ms` 1000 | 2000 | 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000: Duration of this shot in milliseconds.
      - `shot_type` 'customize' | 'intelligent': How a multi-shot storyboard is cut. 'customize' honours each shot's declared duration; 'intelligent' lets the model determine the shot structure. Ignored unless `multi_prompt` is supplied.
      - `generate_audio` boolean: Whether to generate native audio for the video.
      - `aspect_ratio` '16:9' | '9:16' | '1:1', required: Output aspect ratio.
      - `resolution` '720p': Output resolution.
      - `duration_ms` 3000 | 4000 | 5000 | 6000 | 7000 | 8000 | 9000 | 10000 | 11000 | 12000 | 13000 | 14000 | 15000, required: Duration in ms.
      - `start_image` union: Start frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `end_image` union: End frame. With an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - object: A file uploaded via POST /v3/files, referenced by the returned url.
          - `source` 'url', required
          - `url` string, uri, required: A URL returned by POST /v3/files.
        - object: An existing asset you own, referenced by its id.
          - `source` 'asset', required
          - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `images` union[], required: Reference images. 1 to 3 images, each with an aspect ratio from 0.4 to 2.5 and at most 10.4 MB.
        - union
          - object: A file uploaded via POST /v3/files, referenced by the returned url.
            - `source` 'url', required
            - `url` string, uri, required: A URL returned by POST /v3/files.
          - object: An existing asset you own, referenced by its id.
            - `source` 'asset', required
            - `asset_id` string, required: The asset's id (`asset_<uuid>`), as issued by the server — a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.
      - `quality` 'standard': Quality level to generate at. `standard` — the 720p tier. `pro` — the high-resolution tier, at 1080p and 4K.
  - `webhook` string, uri, nullable: URL to receive a signed completion webhook.

## Response `202`

Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.

- SubmitResponse
  - `job_id` string, required: This job's id — server-issued, and opaque.
  - `model` string, required: The resolved model id this job runs on.
  - `status` 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED', required: The four states a job can be in.
  - `status_url` string, required: Path of this job's status monitor: poll GET /v3/jobs/{job_id}/status for status, progress, and the estimated completion time.
  - `result_url` string, required: Path of the job resource itself: GET /v3/jobs/{job_id} returns the result envelope, including the outputs once it completes. Also the value of this response's `Location` header.
  - `estimated_completion_at` string, date-time, nullable: ISO-8601 instant this job is estimated to finish, as of this response. Null when no estimate is available yet, and when the job has already finished. The estimate can change while the job runs: poll `GET /v3/jobs/{job_id}/status` for the current one.

## Other responses

- `400`: Invalid or failed-validation request.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `402`: The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.
- `403`: Insufficient scope or plan.
- `404`: Resource not found.
- `422`: Moderation refused the request's content.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-10-16** `06692d16e78a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hedra-labs/apis/hedra-api/changes/models/kling-o3/post.md)

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)