> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Kling 3.0 Omni API
> Multi-mode Kling video generation API with standard, pro, and 4K text, image, and reference workflows
## Overview
Kling 3.0 Omni is a multi-mode Kling video generation API on APIXO. Use it when you need one model ID for standard, pro, and 4K generation from text prompts, images, or visual references.
| Capability | Value |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model ID | `kling-3-0-omni` |
| Modes | `std-text-to-video`, `std-image-to-video`, `std-reference-to-video`, `pro-text-to-video`, `pro-image-to-video`, `pro-reference-to-video`, `4k-text-to-video`, `4k-image-to-video`, `4k-reference-to-video` |
| Prompt | Required in every mode |
| Duration | Defaults to `5`; most modes support `3-15` seconds; `pro-text-to-video` and `pro-image-to-video` support `5` or `10` |
| Aspect ratios | `16:9`, `9:16`, `1:1` for text and reference modes |
| Image inputs | Image modes require 1-2 images; reference modes support reference images by mode |
| Video inputs | `std-reference-to-video` and `pro-reference-to-video` can use the first `video_urls` item as a reference video |
| Output | Video URLs in `resultJson.resultUrls` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | -------------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/kling-3-0-omni` | Submit a generation task |
| `GET` | `/statusTask/kling-3-0-omni?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Copy-paste async quickstart
This minimal request submits a standard text-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/kling-3-0-omni" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "std-text-to-video",
"prompt": "a cinematic city skyline at sunset with a slow camera push",
"duration": 5,
"sound": false,
"aspect_ratio": "16:9"
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final result.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/kling-3-0-omni?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}",
"createTime": 1767965610929,
"completeTime": 1767965652317,
"costTime": 41388
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "INVALID_PARAMETER",
"failMsg": "One or more input parameters are invalid.",
"createTime": 1767965610929,
"completeTime": 1767965620132
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```
## Request body
### Standard text-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "std-text-to-video",
"prompt": "a cinematic city skyline at sunset",
"duration": 5,
"sound": false,
"aspect_ratio": "16:9"
}
}
```
### Pro image-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "pro-image-to-video",
"prompt": "animate the subject walking toward the camera",
"duration": 10,
"sound": true,
"image_urls": [
"https://example.com/start.png",
"https://example.com/end.png"
]
}
}
```
### Reference-to-video with a reference video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "std-reference-to-video",
"prompt": "keep the same visual style and motion mood",
"duration": 6,
"sound": true,
"aspect_ratio": "16:9",
"image_urls": [
"https://example.com/ref-1.png",
"https://example.com/ref-2.png"
],
"video_urls": [
"https://example.com/reference.mp4"
]
}
}
```
### 4K reference-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "4k-reference-to-video",
"prompt": "turn these product reference images into a polished 4K product video",
"duration": 8,
"sound": true,
"aspect_ratio": "16:9",
"image_urls": [
"https://example.com/ref-1.png",
"https://example.com/ref-2.png"
]
}
}
```
## Parameters
Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
Kling 3.0 Omni input parameters.
Generation mode. Supported values: `std-text-to-video`, `std-image-to-video`, `std-reference-to-video`, `pro-text-to-video`, `pro-image-to-video`, `pro-reference-to-video`, `4k-text-to-video`, `4k-image-to-video`, and `4k-reference-to-video`.
Text prompt describing the desired video. APIXO trims whitespace and rejects missing, non-string, or empty prompts.
Output duration in seconds. Accepts an integer or integer string. Defaults to `5`. Most modes support `3` through `15`; `pro-text-to-video` and `pro-image-to-video` only support `5` or `10`.
Whether to generate or preserve sound. Must be a JSON boolean when provided. For reference modes with `video_urls`, `sound=true` asks APIXO to keep the original sound from the reference video where supported.
Output aspect ratio for text and reference modes. Supported values: `16:9`, `9:16`, `1:1`. Image modes ignore this field.
Optional shot behavior. Supported values: `customize`, `intelligent`.
Optional prompt segments. Provide 1-6 objects. Each item must include a non-empty string `prompt` and an integer `duration`.
Image URLs. Required for image modes with 1-2 images. For `std-reference-to-video` and `pro-reference-to-video`, provide 1-7 images when no reference video is provided, or 0-4 images when `video_urls` is provided. For `4k-reference-to-video`, provide 1-7 images. All items must be non-empty strings.
Reference video URLs. Supported only by `std-reference-to-video` and `pro-reference-to-video`. When provided, APIXO uses the first non-empty URL and ignores additional URLs. `4k-reference-to-video` ignores `video_urls`.
## Mode behavior
| Mode | Required media | Duration | Notes |
| ------------------------ | ---------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| `std-text-to-video` | none | `3-15`, default `5` | Uses `aspect_ratio` and `sound`. |
| `std-image-to-video` | 1-2 `image_urls` | `3-15`, default `5` | First image is the start frame; second image is optional end frame. |
| `std-reference-to-video` | 1-7 images, or first `video_urls` item with up to 4 images | `3-15`, default `5` | Uses `aspect_ratio`; reference video pricing differs from image-only reference mode. |
| `pro-text-to-video` | none | `5` or `10`, default `5` | Uses `aspect_ratio` and `sound`. |
| `pro-image-to-video` | 1-2 `image_urls` | `5` or `10`, default `5` | First image is the start frame; second image is optional end frame. |
| `pro-reference-to-video` | 1-7 images, or first `video_urls` item with up to 4 images | `3-15`, default `5` | Uses pro reference pricing. |
| `4k-text-to-video` | none | `3-15`, default `5` | 4K per-second rate; `sound` does not change price. |
| `4k-image-to-video` | 1-2 `image_urls` | `3-15`, default `5` | 4K per-second rate. |
| `4k-reference-to-video` | 1-7 `image_urls` | `3-15`, default `5` | Ignores `video_urls`; 4K per-second rate. |
Use direct, publicly accessible media URLs. For image modes, provide exactly the images you want used as start and optional end frames.
## Response format
### Submit task response
`POST /generateTask/kling-3-0-omni` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `processing_r2`, `success`, or `failed`.
JSON string containing generated video URLs in `resultUrls`. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds when available.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/kling-3-0-omni" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "pro-image-to-video",
"prompt": "animate the product photo with a slow cinematic camera move",
"duration": 10,
"sound": true,
"image_urls": [
"https://example.com/product.png"
]
}
}'
```
The callback payload uses the same `code`, `message`, and `data` shape as the status response. See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Kling 3.0 Omni is billed per output second. Total cost is:
```text theme={null}
total cost = duration * selected mode unit price
```
| Mode group | Condition | Unit price |
| ---------------------------------------------------------------- | ------------------------------ | ------------------ |
| `std-text-to-video`, `std-image-to-video` | `sound=false` | `$0.084 / second` |
| `std-text-to-video`, `std-image-to-video` | `sound=true` | `$0.112 / second` |
| `std-reference-to-video` | no `video_urls`, `sound=false` | `$0.084 / second` |
| `std-reference-to-video` | no `video_urls`, `sound=true` | `$0.112 / second` |
| `std-reference-to-video` | with `video_urls` | `$0.126 / second` |
| `pro-text-to-video`, `pro-image-to-video` | `sound=false` | `$0.112 / second` |
| `pro-text-to-video`, `pro-image-to-video` | `sound=true` | `$0.14 / second` |
| `pro-reference-to-video` | no `video_urls`, `sound=false` | `$0.112 / second` |
| `pro-reference-to-video` | no `video_urls`, `sound=true` | `$0.1344 / second` |
| `pro-reference-to-video` | with `video_urls` | `$0.168 / second` |
| `4k-text-to-video`, `4k-image-to-video`, `4k-reference-to-video` | fixed 4K rate | `$0.42 / second` |
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Kling 3.0 Omni tasks are asynchronous. Actual latency varies by mode, prompt complexity, media inputs, duration, 4K selection, route queue load, and provider-side processing time.
| Workload | Typical generation time | Recommended first poll | Poll interval |
| ---------------------------- | ------------------------------------- | --------------------------- | ------------- |
| Standard text/image clip | 60s-120s | 60s after task creation | 5s-10s |
| Pro or reference-guided clip | 90s-180s | 60s-90s after task creation | 5s-10s |
| 4K clip | Often longer than standard generation | 90s after task creation | 10s-15s |
For production workloads, use callback mode to avoid frequent polling while video tasks run.
Result URLs are temporary. Download and store important outputs promptly after task completion.
Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/docs/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `400` | Invalid request body, missing `input`, unsupported `mode`, invalid media array, unsupported duration, or invalid optional field | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Key or route cannot access the model | Check permissions and route strategy |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error or unknown task failure | Retry with backoff |
| `502` | Upstream error | Retry with backoff |
| `504` | Upstream timeout | Retry later or use callback mode for long-running jobs |
### Validation notes
| Condition | Backend behavior |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Missing or unsupported `mode` | Request fails before task creation. |
| Missing, non-string, or empty `prompt` | Request fails before task creation. |
| Missing `duration` | Defaults to `5`. |
| `duration` outside `3-15` | Request fails before task creation. |
| `pro-text-to-video` or `pro-image-to-video` duration other than `5` or `10` | Request fails before task creation. |
| `sound` is not boolean | Request fails before task creation. |
| Unsupported `aspect_ratio` | Request fails before task creation. Use `16:9`, `9:16`, or `1:1`. |
| Image mode without `image_urls` | Request fails before task creation. |
| Image mode with more than 2 `image_urls` | Request fails before task creation. |
| Reference mode without `image_urls` or `video_urls` | Request fails before task creation, except text/image modes where references are not used. |
| Reference mode with `video_urls` and more than 4 images | Request fails before task creation. |
| `4k-reference-to-video` without `image_urls` | Request fails before task creation. |
| `shot_type` not `customize` or `intelligent` | Request fails before task creation. |
| `multi_prompt` has more than 6 items or invalid item objects | Request fails before task creation. |
### Task failure codes
`failCode` is generated from APIXO's mapped provider error. Common values include:
| Fail code | Meaning | What to do |
| ---------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `CONTENT_VIOLATION` | Prompt or input/output content was rejected by safety checks | Change the prompt or input media |
| `INVALID_PARAMETER` | A required field is missing or a value is unsupported | Check `mode`, `duration`, `sound`, `image_urls`, `video_urls`, and `aspect_ratio` |
| `INVALID_IMAGE_URL` | A reference image could not be fetched or decoded | Use a direct, publicly accessible image URL |
| `INVALID_VIDEO_URL` | A reference video could not be fetched or decoded | Use a direct, publicly accessible video URL |
| `INSUFFICIENT_BALANCE` | The account does not have enough balance for the task | Add balance before retrying |
| `UPSTREAM_ERROR` | Provider-side generation failed | Retry with backoff |
| `UNKNOWN_ERROR` | The failure could not be mapped to a more specific code | Retry later or contact support with the `taskId` |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Video Models](/docs/models/video)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Routing Strategies](/docs/concepts/routing-strategies)
* [Try Kling 3.0 Omni in the APIXO Playground](https://apixo.ai/models/kling-3-0-omni)
* [Pricing](https://apixo.ai/pricing)