4o Image API Quickstart

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.apikley.ru

Authentication Header

Authorization: Bearer APIKLEY_API_KEY

Quick Start Guide

Step 1: Generate Your First Image

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

curl -X POST "https://api.apikley.ru/api/v1/gpt4o-image/generate" \
  -H "Authorization: Bearer APIKLEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky, photorealistic style",
    "size": "1:1",
    "nVariants": 1
  }'

async function generateImage() {
  try {
    const response = await fetch('https://api.apikley.ru/api/v1/gpt4o-image/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: 'A serene mountain landscape at sunset with a lake reflecting the orange sky, photorealistic style',
        size: '1:1',
        nVariants: 1
      })
    });

    const data = await response.json();
    
    if (response.ok && data.code === 200) {
      console.log('Task submitted:', data);
      console.log('Task ID:', data.data.taskId);
      return data.data.taskId;
    } else {
      console.error('Request failed:', data.msg || 'Unknown error');
      return null;
    }
  } catch (error) {
    console.error('Error:', error.message);
    return null;
  }
}

generateImage();

import requests

def generate_image():
    url = "https://api.apikley.ru/api/v1/gpt4o-image/generate"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {
        "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky, photorealistic style",
        "size": "1:1",
        "nVariants": 1
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        result = response.json()
        
        if response.ok and result.get('code') == 200:
            print(f"Task submitted: {result}")
            print(f"Task ID: {result['data']['taskId']}")
            return result['data']['taskId']
        else:
            print(f"Request failed: {result.get('msg', 'Unknown error')}")
            return None
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

generate_image()

Step 2: Check Task Status

Use the returned task ID to check the generation status:

curl -X GET "https://api.apikley.ru/api/v1/gpt4o-image/record-info?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer APIKLEY_API_KEY"

async function checkTaskStatus(taskId) {
  try {
    const response = await fetch(`https://api.apikley.ru/api/v1/gpt4o-image/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const result = await response.json();
    
    if (response.ok && result.code === 200) {
      const taskData = result.data;
      
      switch (taskData.successFlag) {
        case 1:
          console.log('Generation completed successfully!');
          console.log('Image URLs:', taskData.response.result_urls);
          return taskData.response;
          
        case 0:
          console.log('Still generating...');
          if (taskData.progress) {
            console.log(`Progress: ${(parseFloat(taskData.progress) * 100).toFixed(1)}%`);
          }
          return taskData.response;
          
        case 2:
          console.log('Generation failed');
          if (taskData.errorMessage) {
            console.error('Error message:', taskData.errorMessage);
          }
          return taskData.response;
          
        default:
          console.log('Unknown status:', taskData.successFlag);
          if (taskData.errorMessage) {
            console.error('Error message:', taskData.errorMessage);
          }
          return taskData.response;
      }
    } else {
      console.error('Query failed:', result.msg || 'Unknown error');
      return null;
    }
  } catch (error) {
    console.error('Status check failed:', error.message);
    return null;
  }
}

import requests
import time

def check_task_status(task_id, api_key):
    url = f"https://api.apikley.ru/api/v1/gpt4o-image/record-info?taskId={task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    try:
        response = requests.get(url, headers=headers)
        result = response.json()
        
        if response.ok and result.get('code') == 200:
            task_data = result['data']
            success_flag = task_data['successFlag']
            
            if success_flag == 1:
                print("Generation completed successfully!")
                result_urls = task_data['response']['result_urls']
                for i, url in enumerate(result_urls):
                    print(f"Image {i+1}: {url}")
                return task_data
            elif success_flag == 0:
                print("Still generating...")
                if task_data.get('progress'):
                    progress = float(task_data['progress']) * 100
                    print(f"Progress: {progress:.1f}%")
                return task_data
            elif success_flag == 2:
                print("Generation failed")
                if task_data.get('errorMessage'):
                    print(f"Error message: {task_data['errorMessage']}")
                return task_data
            else:
                print(f"Unknown status: {success_flag}")
                if task_data.get('errorMessage'):
                    print(f"Error message: {task_data['errorMessage']}")
                return task_data
        else:
            print(f"Query failed: {result.get('msg', 'Unknown error')}")
            return None
    except requests.exceptions.RequestException as e:
        print(f"Status check failed: {e}")
        return None

# Poll until completion
def wait_for_completion(task_id, api_key):
    while True:
        result = check_task_status(task_id, api_key)
        if result and result.get('successFlag') in [1, 2]:  # Success or failed
            return result
        time.sleep(10)  # Wait 10 seconds before checking again

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

successFlag

integer

Task status indicator:

0: Generating (in progress)
1: Success (completed successfully)
2: Failed (generation failed)

progress

string

Generation progress as a decimal string (0.00 to 1.00). Multiply by 100 for percentage.

createTime

string

Task creation timestamp in format “YYYY-MM-DD HH:mm:ss”

completeTime

string | null

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

SquarePerfect for social media posts, avatars, product displays

3:2

LandscapeIdeal for landscape photos, desktop wallpapers, banners

2:3

PortraitGreat for portraits, mobile wallpapers, poster designs

Key Parameters

prompt

string

Text description for image generation. Provide detailed, specific descriptions for better results.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

size

string

required

Image aspect ratio, required parameter:

1:1 - Square
3:2 - Landscape
2:3 - Portrait

filesUrl

array

Input image URL list, supports up to 5 images. Supported formats: .jpg, .jpeg, .png, .webp, .jfif

maskUrl

string

Mask image URL to specify areas for editing. Black areas will be modified, white areas remain unchanged.

nVariants

integer

Number of image variants to generate. Options: 1, 2, or 4. Default is 1.

isEnhance

boolean

Prompt enhancement option. For specific scenarios like 3D image generation, enabling this can achieve more refined effects. Default is false.

enableFallback

boolean

Enable fallback mechanism. Automatically switches to backup models when the main model is unavailable. Default is false.

Complete Workflow Example

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

JavaScript
Python

class FourOImageAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.apikley.ru/api/v1/gpt4o-image';
  }
  
  async generateImage(options) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(options)
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`Generation failed: ${result.msg || 'Unknown error'}`);
    }
    
    return result.data.taskId;
  }
  
  async waitForCompletion(taskId, maxWaitTime = 300000) { // 5 minutes max
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getTaskStatus(taskId);
      
      switch (status.successFlag) {
        case 1:
          console.log('Generation completed successfully!');
          return status.response;
          
        case 0:
          console.log('Still generating...');
          if (status.progress) {
            console.log(`Progress: ${(parseFloat(status.progress) * 100).toFixed(1)}%`);
          }
          break;
          
        case 2:
          const errorMsg = status.errorMessage || 'Generation failed';
          console.error('Error message:', errorMsg);
          throw new Error(errorMsg);
          
        default:
          console.log('Unknown status:', status.successFlag);
          if (status.errorMessage) {
            console.error('Error message:', status.errorMessage);
          }
          break;
      }
      
      // Wait 10 seconds before next check
      await new Promise(resolve => setTimeout(resolve, 10000));
    }
    
    throw new Error('Generation timeout');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`Status check failed: ${result.msg || 'Unknown error'}`);
    }
    
    return result.data;
  }
  
  async getDownloadUrl(imageUrl) {
    const response = await fetch(`${this.baseUrl}/download-url`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ imageUrl })
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`Get download URL failed: ${result.msg || 'Unknown error'}`);
    }
    
    return result.data.downloadUrl;
  }
}

// Usage Example
async function main() {
  const api = new FourOImageAPI('YOUR_API_KEY');
  
  try {
    // Text-to-Image Generation
    console.log('Starting image generation...');
    const taskId = await api.generateImage({
      prompt: 'A futuristic cityscape with flying cars and neon lights, cyberpunk style',
      size: '1:1',
      nVariants: 2,
      isEnhance: true,
      enableFallback: true
    });
    
    // Wait for completion
    console.log(`Task ID: ${taskId}. Waiting for completion...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('Image generation successful!');
    result.result_urls.forEach((url, index) => {
      console.log(`Image ${index + 1}: ${url}`);
    });
    
    // Get download URL
    const downloadUrl = await api.getDownloadUrl(result.result_urls[0]);
    console.log('Download URL:', downloadUrl);
    
    // Image Editing Example
    console.log('\nStarting image editing...');
    const editTaskId = await api.generateImage({
      filesUrl: [result.result_urls[0]],
      prompt: 'Add beautiful rainbow in the sky',
      size: '3:2'
    });
    
    const editResult = await api.waitForCompletion(editTaskId);
    console.log('Image editing successful!');
    console.log('Edited image:', editResult.result_urls[0]);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

import requests
import time

class FourOImageAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.apikley.ru/api/v1/gpt4o-image'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    
    def generate_image(self, **options):
        response = requests.post(f'{self.base_url}/generate', 
                               headers=self.headers, json=options)
        result = response.json()
        
        if not response.ok or result.get('code') != 200:
            raise Exception(f"Generation failed: {result.get('msg', 'Unknown error')}")
        
        return result['data']['taskId']
    
    def wait_for_completion(self, task_id, max_wait_time=300):
        start_time = time.time()
        
        while time.time() - start_time < max_wait_time:
            status = self.get_task_status(task_id)
            
            if status['successFlag'] == 1:
                print("Generation completed successfully!")
                return status['response']
            elif status['successFlag'] == 0:
                print("Still generating...")
                if status.get('progress'):
                    progress = float(status['progress']) * 100
                    print(f"Progress: {progress:.1f}%")
            elif status['successFlag'] == 2:
                error_msg = status.get('errorMessage', 'Generation failed')
                print(f"Error message: {error_msg}")
                raise Exception(error_msg)
            else:
                print(f"Unknown status: {status['successFlag']}")
                if status.get('errorMessage'):
                    print(f"Error message: {status['errorMessage']}")
            
            time.sleep(10)  # Wait 10 seconds
        
        raise Exception('Generation timeout')
    
    def get_task_status(self, task_id):
        response = requests.get(f'{self.base_url}/record-info?taskId={task_id}',
                              headers={'Authorization': f'Bearer {self.api_key}'})
        result = response.json()
        
        if not response.ok or result.get('code') != 200:
            raise Exception(f"Status check failed: {result.get('msg', 'Unknown error')}")
        
        return result['data']
    
    def get_download_url(self, image_url):
        response = requests.post(f'{self.base_url}/download-url',
                               headers=self.headers, 
                               json={'imageUrl': image_url})
        result = response.json()
        
        if not response.ok or result.get('code') != 200:
            raise Exception(f"Get download URL failed: {result.get('msg', 'Unknown error')}")
        
        return result['data']['downloadUrl']

# Usage Example
def main():
    api = FourOImageAPI('YOUR_API_KEY')
    
    try:
        # Text-to-Image Generation
        print('Starting image generation...')
        task_id = api.generate_image(
            prompt='A futuristic cityscape with flying cars and neon lights, cyberpunk style',
            size='1:1',
            nVariants=2,
            isEnhance=True,
            enableFallback=True
        )
        
        # Wait for completion
        print(f'Task ID: {task_id}. Waiting for completion...')
        result = api.wait_for_completion(task_id)
        
        print('Image generation successful!')
        for i, url in enumerate(result['result_urls']):
            print(f'Image {i + 1}: {url}')
        
        # Get download URL
        download_url = api.get_download_url(result['result_urls'][0])
        print(f'Download URL: {download_url}')
        
        # Image Editing Example
        print('\nStarting image editing...')
        edit_task_id = api.generate_image(
            filesUrl=[result['result_urls'][0]],
            prompt='Add beautiful rainbow in the sky',
            size='3:2'
        )
        
        edit_result = api.wait_for_completion(edit_task_id)
        print('Image editing successful!')
        print(f'Edited image: {edit_result["result_urls"][0]}')
        
    except Exception as error:
        print(f'Error: {error}')

if __name__ == '__main__':
    main()

Advanced Features

Mask Editing

Use masks for precise image editing:

const editTaskId = await api.generateImage({
  filesUrl: ['https://example.com/original.jpg'],
  maskUrl: 'https://example.com/mask.png',
  prompt: 'Replace the masked area with a beautiful garden',
  size: '3:2'
});

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:

const taskId = await api.generateImage({
  prompt: 'Artistic concept design',
  size: '1:1',
  enableFallback: true,
  fallbackModel: 'FLUX_MAX' // or 'GPT_IMAGE_1'
});

Using Callbacks

Set up webhook callbacks for automatic notifications:

const taskId = await api.generateImage({
  prompt: 'Digital artwork',
  size: '1:1',
  callBackUrl: 'https://your-server.com/4o-callback'
});

// Your callback endpoint will receive:
app.post('/4o-callback', (req, res) => {
  const { code, data } = req.body;
  
  if (code === 200) {
    console.log('Images ready:', data.info.result_urls);
  } else {
    console.log('Generation failed:', req.body.msg);
  }
  
  res.status(200).json({ status: 'received' });
});

Learn More About Callbacks

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

Task Status Descriptions

successFlag: 0

In Progress

Task is currently being processed. Check progress field for completion percentage.

successFlag: 1

Success

Task completed successfully. Generated images are available in response.result_urls.

successFlag: 2

Failed

Image generation failed. Check errorMessage field for details.

Best Practices

Prompt Optimization

Use detailed, specific descriptions
Include style and technique descriptions (e.g., “photorealistic”, “impressionist”, “digital art”)
Specify color, lighting, and composition requirements
Avoid overly complex or contradictory descriptions

Image Quality

Choose appropriate aspect ratios for your use case
Consider enabling prompt enhancement for complex scenes
Use high-quality input images for editing
Ensure mask images accurately mark editing areas

Performance Optimization

Use callbacks instead of frequent polling
Enable fallback mechanism for service reliability
Set appropriate variant counts to balance quality and cost
Download images promptly to avoid 14-day expiration

Error Handling

Monitor all task states (successFlag values 0, 1, 2)
Check errorMessage field when successFlag is 2
Display progress information during generation (progress field)
Implement proper retry logic for failed requests
Verify input image accessibility before submission
Log error information for debugging and support

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@apikley.ru
Documentation: docs.apikley.ru
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!

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt

Rate limits and quotas are enforced by Apikley and may differ from upstream providers.

​4o Image API Quickstart

​Welcome to 4o Image API

Text-to-Image

Image Editing

Image Variants

Task Management

​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

1:1

3:2

2:3

​Key Parameters

​Complete Workflow Example

​Advanced Features

​Mask Editing

​Fallback Mechanism

​Using Callbacks

Learn More About Callbacks

​Task Status Descriptions

​Best Practices

​Image Storage and Downloads

​Next Steps

Generate Images

Task Details

Download URL

Callback Setup

​Support

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

Complete Workflow Example

Advanced Features

Mask Editing

Fallback Mechanism

Using Callbacks

Task Status Descriptions

Best Practices

Image Storage and Downloads

Next Steps

Support