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
Authentication Header
Quick Start Guide
Step 1: Generate Your First Image
Start with a simple text-to-image generation request:Step 2: Check Task Status
Use the returned task ID to check the generation status:Response Format
Successful Response:Response Fields
Task status indicator:
0
: Generating (in progress)1
: Success (completed successfully)2
: Failed (generation failed)
Generation progress as a decimal string (0.00 to 1.00). Multiply by 100 for percentage.
Task creation timestamp in format “YYYY-MM-DD HH:mm:ss”
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:Image Editing
Edit existing images using masks and prompts:Image Variants
Generate creative variants based on input images: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
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
Image aspect ratio, required parameter:
1:1
- Square3:2
- Landscape2:3
- Portrait
Input image URL list, supports up to 5 images. Supported formats:
.jpg
, .jpeg
, .png
, .webp
, .jfif
Mask image URL to specify areas for editing. Black areas will be modified, white areas remain unchanged.
Number of image variants to generate. Options: 1, 2, or 4. Default is 1.
Prompt enhancement option. For specific scenarios like 3D image generation, enabling this can achieve more refined effects. Default is false.
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: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
Task is currently being processed. Check
progress
field for completion percentage.Task completed successfully. Generated images are available in
response.result_urls
.Image generation failed. Check
errorMessage
field for details.Best Practices
Prompt Optimization
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
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
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
Error Handling
- Monitor all task states (
successFlag
values 0, 1, 2) - Check
errorMessage
field whensuccessFlag
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@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!