KIE.ai Image Generation

Generate images from text prompts or transform existing images using KIE.ai's GPT-Image-2 models.

Prerequisites

• KIE.ai API Key: Required for all operations. Obtain from https://kie.ai
• The API key must be stored in environment variable KIE_API_KEY or provided by the user

Quick Start

Text-to-Image

python scripts/kie_image.py --mode text2img --prompt "YOUR_PROMPT" --api-key YOUR_KEY --output ./output

Image-to-Image

python scripts/kie_image.py --mode img2img --prompt "YOUR_PROMPT" --input-urls "URL1,URL2" --api-key YOUR_KEY --output ./output

Workflow

Step 1: Determine Mode

• text2img: User provides a text prompt only → use gpt-image-2-text-to-image
• img2img: User provides source images + text prompt → use gpt-image-2-image-to-image

If the user provides reference images (uploaded files, URLs, or paths), use img2img mode.

Step 2: Prepare Parameters

| Parameter | text2img | img2img | Notes |

|-----------|----------|---------|-------|

| prompt | Required | Required | Describe the desired output image |

| input_urls | N/A | Required | 1+ image URLs (comma-separated) |

| aspect_ratio | Optional | Optional | auto, 1:1, 16:9, 9:16, 4:3, 3:4 |

| nsfw_checker | Optional | Optional | Default true; set false to disable content filter |

Prompt tips:

• Be specific and descriptive for best results
• Include style, lighting, composition details
• For img2img, describe how the output should relate to the input

Aspect ratio guidance:

• auto (default): model decides
• 1:1: square, good for portraits/icons
• 16:9: landscape, good for wide scenes
• 9:16: portrait, good for phone screens/posters
• 4:3/3:4: standard photo ratios

Step 3: Execute the Script

The Python script (scripts/kie_image.py) handles:

1. Creating the task on KIE.ai
2. Polling for completion (up to 5 minutes)
3. Downloading generated images to the output directory
4. Outputting a JSON result with file paths

API key resolution order:

1. --api-key CLI argument
2. KIE_API_KEY environment variable
3. Ask the user for their key

Step 4: Present Results

The script outputs JSON on stdout:

{
  "task_id": "task_gptimage_xxx",
  "model": "gpt-image-2-text-to-image",
  "image_urls": ["https://..."],
  "downloaded_files": ["/path/to/image.png"],
  "status": "success"
}

Show the generated image(s) to the user via open_result_view or preview_url.

Handling Source Images for img2img

When the user provides local image files for img2img mode:

• Local files must be uploaded to get public URLs first
• Use image hosting services (imgur, etc.) to get publicly accessible URLs
• The input_urls parameter requires HTTP/HTTPS URLs, not local paths

Error Handling

• Task creation fails: Check API key validity, model name, and parameter format
• Polling timeout: Task may still be processing; user can retry later with the task ID
• No image URLs in result: The API response structure may vary; inspect the full output
• Download fails: Image URLs may be temporary; download immediately after task completion

API Reference

See references/api_reference.md for detailed API documentation.