# Kling O1 Image - Core.Today AI API

> Kling O1 performs precise image edits under strong reference control. Supply up to 10 reference images and character elements, then address them directly in the prompt as @Image1 or @Element1 to transform subjects, styles, and local details while preserving visual consistency.

- **Provider**: Kuaishou
- **Model ID**: fal-ai/kling-image/o1
- **Category**: Image Generation
- **Credits**: 66 per image, same price at either resolution
- **Speed**: Medium
- **Quality**: Ultra

## Features
- Address references directly in the prompt with @Image1 / @Element1
- Up to 10 reference images and character elements combined
- Character elements with frontal plus additional reference views
- 1K and 2K output at the same price
- Up to 9 images per request

## Use Cases
- Product placement into a new scene while keeping the label legible
- Consistent character across a series of illustrations
- Compositing multiple references into one coherent frame
- Local retouching that must preserve the rest of the image

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **prompt**: string - Text prompt, up to 2500 characters. Reference the supplied images as @Image1, @Image2, ... (1-indexed; use @Image when there is only one) and character elements as @Element1, @Element2, ...
- **image_urls**: array - Reference images, 1-indexed in the prompt as @Image1, @Image2, ... Maximum 10 including elements.

### Optional
- **elements**: array - Characters or objects to include, referenced as @Element1, @Element2, ... Each element takes a frontal_image_url plus optional reference_image_urls. Maximum 10 including reference images.
- **resolution**: string (default: 1K) - Output resolution. 1K is standard, 2K is high-res. Both cost the same.
  Options: 1K, 2K
- **num_images**: integer (default: 1) - Number of images to generate (1-9). Charged per image.
- **aspect_ratio**: string (default: auto) - Aspect ratio of the generated images. 'auto' picks one based on the input content.
  Options: auto, 21:9, 16:9, 3:2, 4:3, 1:1, 3:4, 2:3, 9:16
- **output_format**: string (default: png) - The format of the generated image.
  Options: jpeg, png, webp

## Examples

### Product placement across two references
@Image1 is the product, @Image2 is the scene. Naming both in one sentence tells the model exactly what goes where.
```json
{
  "model": "fal-ai/kling-image/o1",
  "input": {
    "prompt": "Place @Image1 on the marble counter in @Image2, matching the warm window light and keeping the product label fully legible",
    "image_urls": [
      "https://storage.googleapis.com/falserverless/example_inputs/kling-image-o1/input.png",
      "https://storage.googleapis.com/falserverless/example_inputs/kling-image-o1/input-2.png"
    ],
    "resolution": "1K",
    "aspect_ratio": "auto",
    "num_images": 1
  }
}
```

### Character element in a new scene
An element carries a frontal view plus extra angles, which holds the character steady across generations better than a single flat reference.
```json
{
  "model": "fal-ai/kling-image/o1",
  "input": {
    "prompt": "Put @Element1 in the driver's seat of the car in @Image1, keep the face and outfit identical, evening city lights outside",
    "image_urls": [
      "https://storage.googleapis.com/falserverless/example_inputs/kling-image-o1/input.png"
    ],
    "elements": [
      {
        "frontal_image_url": "https://storage.googleapis.com/falserverless/example_inputs/kling-image-o1/element-1-front.png",
        "reference_image_urls": [
          "https://storage.googleapis.com/falserverless/example_inputs/kling-image-o1/element-1-reference.png"
        ]
      }
    ],
    "resolution": "2K",
    "num_images": 1
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- Always name your references explicitly: @Image1, @Image2, @Element1. A prompt that just says 'the product' leaves the model to guess which input you meant.
- 2K costs the same as 1K, so there is no price reason to stay at 1K when you want the detail.
- For a recurring character, use elements rather than plain reference images — the frontal plus extra views hold identity far better.
- Reference images and elements share one budget of 10 items total, not 10 each.
- num_images is charged per image, so a 9-image request costs nine times a single one.

## Documentation
https://fal.ai/models/fal-ai/kling-image/o1