# Kling 3.0 (Text to Video)

Kling 3.0 text-to-video at 720p, 1080p, or 4K, with optional native audio and multi-shot output.

- Model ID: `kling/kling-3.0-text-to-video`
- Provider: Kling (Kuaishou)
- Modality: text → video
- Type: Text to Video
- Status: stable
- Delivery: async
- Max resolution: 4k
- Output format: mp4
- Aspect ratios: 16:9, 9:16, 1:1

## Authentication

Send your API key in the `X-API-Key` header.

## Endpoint

```
POST https://api.dev.pika.art/v1/media/kling/kling-3.0/text-to-video
```

## Reference uploads

To use a local file (image, audio, or video) as a model input, first request a presigned upload URL: `POST /v1/media/uploads` with the `X-API-Key` header and a JSON body `{ "content_type": "image/png", "size_bytes": 12345 }`, where `size_bytes` is the file's exact byte length. The response returns `upload_url` (temporary, valid for 5 minutes), `headers`, and `url` (the permanent Pika URL). PUT the file bytes to `upload_url` sending the returned `headers` verbatim — both `Content-Type` and `Content-Length` are signed, and storage returns a bare 403 if either is missing or differs. Then pass `url` into fields such as `image`, `image_url`, `end_image_url`, `image_urls`, `first_frame_image`, or `mask_image_url`.

## Generate

`POST /v1/media/kling/kling-3.0/text-to-video`

```bash
curl -X POST https://api.dev.pika.art/v1/media/kling/kling-3.0/text-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Whimsical surreal establishing scene of a lush green hillside garden beside a turquoise swimming pool, populated by enormous fantastical toadstool mushrooms with vivid magenta-red caps flecked with white spots and pale stems, towering over the landscape. Two elegantly dressed women in soft pastel floral summer dresses stand small at the pool edge with their backs turned, one in blue, one in butter-yellow with a woven straw tote, gazing up at the giant mushrooms; their reflections and a mushroom mirror in the still water. Dense mossy foliage and dark forest behind. Bright dreamy daylight, saturated pigmented reds and greens, warm analog film grade, lifted milky blacks, fine 35mm grain and halation, premium retro-futurist creative-studio look. 16:9 widescreen composition. No text, no logos, no wordmarks, no watermarks.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": "off"
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | yes | - | Text prompt describing the video. |
| `duration` | integer | no | 5 | Video length in seconds. |
| `resolution` | enum | no | 720p | Output resolution. |
| `aspect_ratio` | enum | no | 16:9 | Output aspect ratio. |
| `audio` | enum | no | off | Whether to generate native audio. |
| `multi_shot` | boolean | no | - | Allow multi-shot output from a shot-scripted prompt. |

Returns a job object, not the final output — normally with status `queued`. Store the `id` and poll until a terminal state. A rejected submit (insufficient balance, rate limit, unpriceable input) still returns the job object, with status `failed` and `error` set. An `Idempotency-Key` replay returns the existing job in its current state — including `failed`, so retry a failure with a fresh key, never the same one.

### Response

**200 OK · queued**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "queued"
}
```

## Poll status

`GET /v1/media/jobs/{request_id}`

```bash
curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
  -H "X-API-Key: YOUR_API_KEY"
```

Poll the job by id until it reaches a terminal state: `completed` or `failed`.

### The job object

- `id` (string): Unique identifier for the job.
- `status` (enum): One of `queued`, `running`, `completed`, `failed`.
- `output` (object): Present once the job completes.
  - `media_type` (enum): `video`.
  - `output.video.url` (string): URL of the generated video.
- `error` (object): Present if the job failed. `error.code` is the stable machine-readable value to branch on (e.g. `invalid_input`, `content_moderation`, `insufficient_balance`, `rate_limited`, `provider_error`, `timed_out`); `error.message` is diagnostic text and varies.

### Response

**200 OK · running**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "running"
}
```

**200 OK · completed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "completed",
  "output": {
    "media_type": "video",
    "video": {
      "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4",
      "content_type": "video/mp4"
    }
  }
}
```

**200 OK · failed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "failed",
  "error": {
    "code": "provider_error",
    "message": "upstream generation failed"
  }
}
```

## Get result

`GET /v1/media/jobs/{request_id}/content`

```bash
curl https://api.dev.pika.art/v1/media/jobs/{request_id}/content \
  -H "X-API-Key: YOUR_API_KEY"
```

Once the job completes, fetch a download URL for the generated media.

### Response

**200 OK · content URL**

```json
{
  "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4"
}
```

## Errors

Errors use conventional HTTP status codes and always return JSON, in one of two shapes. Request-level errors (auth, unknown path, schema validation, idempotency conflict) are `{"message": "..."}`. Submit rejections that occur after the job row is created (insufficient balance, rate limit, unpriceable input, dispatch unavailable) return the full failed job envelope — branch on `error.code`, and retry with a fresh `Idempotency-Key`, since a failed job replays on its key.

- 401 Unauthorized — The API key is missing or invalid. Body: `{"message":"Invalid API key"}`
- 403 Forbidden — An inactive key is rejected with a `{"message"}` body. A submit that the org balance or postpaid cycle limit cannot cover is rejected after the job row exists and returns the failed job envelope. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}}`
- 404 Not Found — No job with that id exists in your org, or the media path names an unknown vendor/model/function. Body: `{"message":"media job not found"}`
- 409 Conflict — The result was requested before the job completed, or an Idempotency-Key header was reused with a different body. Body: `{"message":"media job is not ready"}`
- 422 Unprocessable Entity — The request body failed validation: an invalid enum value, a missing required field, a wrong type, or malformed JSON. The JSON message names the offending field. A schema-valid parameter combination that cannot be priced instead fails after job creation and returns the failed job envelope with error code `invalid_input`. Body: `{"message":"duration: Input should be less than or equal to 15"}`
- 429 Too Many Requests — Org limit reached: requests per minute or day, or concurrent jobs. Returned as the failed job envelope; check the Retry-After header and retry with a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}}`
- 503 Service Unavailable — The model rail or a backend dependency is temporarily unavailable. Returned as the failed job envelope; retry with backoff and a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}}`

## Pricing

- 720p · no audio: $0.068 per second
- 1080p · no audio: $0.09 per second
- 720p · with audio: $0.101 per second
- 1080p · with audio: $0.135 per second
- 4k: $0.336 per second

Only successful generations are charged.

---

Model page: https://dev.pika.art/models/kling/kling-3.0/text-to-video
API index: https://dev.pika.art/llms.txt