4o Image API Quickstart

description: Get started with the 4o Image API to generate high-quality AI images in minutes

Welcome to 4o Image API

The 4o Image API, powered by the advanced GPT-4o model, provides high-quality AI image generation services. Whether you need text-to-image generation, image editing, or image variants, our API meets all your creative needs.

Text-to-Image

Generate high-quality images from text descriptions

Image Editing

Edit existing images using masks and prompts

Image Variants

Generate multiple creative variants from input images

Task Management

Track and monitor your image generation tasks

Authentication

All API requests require authentication using a Bearer token. Get your API key from the API Key Management Page.

Keep your API key secure and never share it publicly. If compromised, reset it immediately.

API Base URL

https://api.kie.ai

Authentication Header

Quick Start Guide

Step 1: Generate Your First Image

Start with a simple text-to-image generation request:

cURL

Node.js

Python

Step 2: Check Task Status

Use the returned task ID to check the generation status:

cURL

Node.js

Python

Response Format

Successful Response:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_4o_abc123"
  }
}

Task Status Response (Generating):

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_4o_abc123",
    "paramJson": "{\"prompt\":\"A serene mountain landscape\",\"size\":\"1:1\"}",
    "completeTime": null,
    "response": null,
    "successFlag": 0,
    "errorCode": null,
    "errorMessage": null,
    "createTime": "2024-01-15 10:30:00",
    "progress": "0.50"
  }
}

Task Status Response (Success):

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_4o_abc123",
    "paramJson": "{\"prompt\":\"A serene mountain landscape\",\"size\":\"1:1\"}",
    "completeTime": "2024-01-15 10:35:00",
    "response": {
      "result_urls": [
        "https://example.com/generated-image.png"
      ]
    },
    "successFlag": 1,
    "errorCode": null,
    "errorMessage": null,
    "createTime": "2024-01-15 10:30:00",
    "progress": "1.00"
  }
}

Task Status Response (Failed):

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_4o_abc123",
    "paramJson": "{\"prompt\":\"A serene mountain landscape\",\"size\":\"1:1\"}",
    "completeTime": "2024-01-15 10:35:00",
    "response": {
      "result_urls": []
    },
    "successFlag": 2,
    "errorCode": 400,
    "errorMessage": "Generation failed, please try again or contact support",
    "createTime": "2024-01-15 10:30:00",
    "progress": "0.00"
  }
}

Response Fields

Parameter	Type	Required	Description
`successFlag`	integer	Yes	Task status indicator: 0 (Generating), 1 (Success), 2 (Failed)
`progress`	string	No	Generation progress as a decimal string (0.00 to 1.00)
`createTime`	string	Yes	Task creation timestamp in format "YYYY-MM-DD HH:mm:ss"
`completeTime`	string	No	Task completion timestamp in format "YYYY-MM-DD HH:mm:ss". Null if not yet completed

Core Features

Text-to-Image

Generate high-quality images from text descriptions:

{
  "prompt": "A cute orange cat sitting on a rainbow, cartoon style, bright colors",
  "size": "1:1",
  "nVariants": 2,
  "isEnhance": false
}

Image Editing

Edit existing images using masks and prompts:

{
  "filesUrl": ["https://example.com/original-image.jpg"],
  "maskUrl": "https://example.com/mask-image.png",
  "prompt": "Replace the sky with a starry night sky",
  "size": "3:2"
}

Image Variants

Generate creative variants based on input images:

{
  "filesUrl": ["https://example.com/base-image.jpg"],
  "prompt": "Keep main elements, change to watercolor painting style",
  "size": "2:3",
  "nVariants": 4
}

Image Size Support

Three standard image ratios are supported:

1:1

Square

Perfect for social media posts, avatars, product displays

3:2

Landscape

Ideal for landscape photos, desktop wallpapers, banners

2:3

Portrait

Great for portraits, mobile wallpapers, poster designs

Key Parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description for image generation
`size`	string	Yes	Image aspect ratio: "1:1", "3:2", or "2:3"
`filesUrl`	array	No	Input image URL list, supports up to 5 images
`maskUrl`	string	No	Mask image URL to specify areas for editing
`nVariants`	integer	No	Number of image variants to generate (1, 2, or 4)
`isEnhance`	boolean	No	Prompt enhancement option (default: false)
`enableFallback`	boolean	No	Enable fallback mechanism (default: false)

Prompt Tips

Describe main objects and scenes

Specify artistic styles (e.g., "photorealistic", "cartoon", "watercolor")

Add color and lighting descriptions

Include mood and atmosphere elements

Complete Workflow Example

Here's a complete example for image generation and editing:

JavaScript

Python

Advanced Features

Mask Editing

Use masks for precise image editing:

Black areas in the mask image will be edited, white areas remain unchanged. The mask must match the original image dimensions.

Fallback Mechanism

Enable fallback mechanism for service reliability:

Using Callbacks

Set up webhook callbacks for automatic notifications:

Learn More About Callbacks

Set up webhook callbacks to receive automatic notifications when your images are ready.

Task Status Descriptions

Status	Description
`successFlag: 0`	Task is currently being processed
`successFlag: 1`	Task completed successfully
`successFlag: 2`	Image generation failed

Best Practices

Prompt Optimization

Image Quality

Performance Optimization

Error Handling

Image Storage and Downloads

Generated images are stored for 14 days before automatic deletion. Download URLs are valid for 20 minutes.

Image URLs remain accessible for 14 days after generation

Use download URL API to solve cross-domain download issues

Download URLs expire after 20 minutes

Recommended to download and store important images locally

Next Steps

Generate Images

Complete API reference for image generation

Task Details

Query and monitor task status

Download URL

Get direct download URLs

Callback Setup

Set up automatic notification callbacks

Support

Need help

Our technical support team is here to assist you.

Email: support@kie.ai

Documentation: docs.kie.ai

API Status: Check our status page for real-time API health

Ready to start creating amazing AI images? Get your API key and begin creating today!

4o Image API Quickstart

Welcome to 4o Image API#

Authentication#

API Base URL#

Authentication Header#

Quick Start Guide#

Step 1: Generate Your First Image#

Step 2: Check Task Status#

Response Format#

Response Fields#

Core Features#

Text-to-Image#

Image Editing#

Image Variants#

Image Size Support#

Key Parameters#

Prompt Tips#

Complete Workflow Example#

Advanced Features#

Mask Editing#

Fallback Mechanism#

Using Callbacks#

Task Status Descriptions#

Best Practices#

Image Storage and Downloads#

Next Steps#

Support#

Welcome to 4o Image API

Authentication

API Base URL

Authentication Header

Quick Start Guide

Step 1: Generate Your First Image

Step 2: Check Task Status

Response Format

Response Fields

Core Features

Text-to-Image

Image Editing

Image Variants

Image Size Support

Key Parameters

Prompt Tips

Complete Workflow Example

Advanced Features

Mask Editing

Fallback Mechanism

Using Callbacks

Task Status Descriptions

Best Practices

Image Storage and Downloads

Next Steps

Support