Image Generation

Generate images using Kie.ai’s Nano Banana Pro model with support for image transformation.

Create Generation Task

Initiate an image generation task.

POST /api/images/generate

curl -X POST https://production.youvebeenheard.com/api/images/generate \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=<token>" \
  -d '{
    "prompt": "Create a professional isometric infographic showing the three pillars of IT leadership...",
    "aspectRatio": "16:9",
    "resolution": "2K"
  }'

Request

prompt

string

required

Image generation prompt (detailed description of desired image)

aspectRatio

string

default:"16:9"

Image aspect ratioOptions: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, auto

resolution

string

default:"2K"

Image resolutionOptions: 1K, 2K, 4K

imageInput

string[]

default:"[]"

Input image URLs for transformation (max 8 images)Use this to modify existing images or create variations.

Response

{
  "taskId": "kie_abc123xyz"
}

taskId

string

Unique task ID for polling status

Kie.ai Request Format

The API forwards requests to Kie.ai:

{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "...",
    "image_input": [],
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png"
  }
}

Check Task Status

Poll for task completion and retrieve the generated image URL.

GET /api/images/status?taskId=<taskId>

taskId

string

required

Task ID from create task response

curl "https://production.youvebeenheard.com/api/images/status?taskId=kie_abc123xyz" \
  -H "Cookie: auth_token=<token>"

Response

{
  "taskId": "kie_abc123xyz",
  "state": "success",
  "imageUrl": "https://kie.ai/cdn/images/abc123.png",
  "costTime": 45000
}

taskId

string

Task ID

state

string

Task state: pending, processing, success, or fail

imageUrl

string | null

Generated image URL (only available when state: "success")

failMsg

string

Error message if state: "fail"

costTime

number

Generation time in milliseconds

Task States

State	Description	Action
`pending`	Task queued or waiting	Continue polling
`processing`	Image being generated	Continue polling
`success`	Image ready	Retrieve `imageUrl`
`fail`	Generation failed	Check `failMsg`

Polling Pattern

Poll the status endpoint until the task completes:

async function waitForImage(taskId, maxAttempts = 90, intervalMs = 3000) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`/api/images/status?taskId=${taskId}`)
    const result = await response.json()
    
    if (result.state === 'success') {
      return result.imageUrl
    }
    
    if (result.state === 'fail') {
      throw new Error(result.failMsg || 'Generation failed')
    }
    
    // Wait before next poll
    await new Promise(resolve => setTimeout(resolve, intervalMs))
  }
  
  throw new Error('Task timed out after 4.5 minutes')
}

// Usage
const imageUrl = await waitForImage(taskId)
console.log('Image ready:', imageUrl)

Default Configuration:

Max attempts: 90
Interval: 3 seconds
Total timeout: 4.5 minutes

Generation Time: Most images complete in 30-90 seconds. Complex infographics may take up to 2-3 minutes.

Image Transformation

Modify existing images by providing them as input:

const response = await fetch('/api/images/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Change the color scheme to dark mode with cyan and magenta accents',
    imageInput: [
      'https://kie.ai/cdn/images/original.png'
    ],
    aspectRatio: '16:9',
    resolution: '2K'
  })
})

imageInput

string[]

Array of image URLs to use as input (max 8 images)Use cases:

Recolor existing infographic
Add/remove elements
Change layout or composition
Merge multiple images

Transformation Examples

{
  "prompt": "Convert this infographic to YBH brand colors (yellow #F7B500, orange #F17529, red #EF4136) on dark background",
  "imageInput": ["https://kie.ai/cdn/images/original.png"],
  "aspectRatio": "16:9"
}

Aspect Ratios

Supported aspect ratios and common use cases:

Ratio	Dimensions	Use Case
`1:1`	Square	Instagram posts, profile images
`16:9`	Landscape	LinkedIn posts, presentations, blog headers
`9:16`	Portrait	Instagram Stories, TikTok
`4:5`	Portrait	Instagram feed posts
`21:9`	Ultrawide	Cinematic presentations
`3:2`	Photo	Standard photography format
`auto`	Dynamic	Let model decide optimal ratio

Resolutions

Resolution	Dimensions	File Size	Use Case
1K	~1024px	~200KB	Web thumbnails, previews
2K	~2048px	~500KB	Social media, web display
4K	~4096px	~2MB	Print, high-res displays

Default: 2K provides good balance between quality and file size for most social media use cases.

Error Responses

Status	Error	Description
`400`	Prompt is required	Missing or empty prompt
`400`	taskId is required	Missing taskId in status check
`400`	Kie.ai error	Upstream API error (check message)
`500`	Kie.ai API key not configured	Missing KIEAI_API_KEY
`500`	Failed to start image generation	Request processing error
`500`	Failed to check task status	Status check error

Prompt Engineering

Effective prompts for infographics:

Good Prompt Structure

[Style] + [Subject] + [Layout] + [Color] + [Details] + [Constraints]

Example:

Create a professional isometric 3D infographic showing the three pillars of 
IT leadership (Technical Expertise, Business Acumen, People Skills) arranged 
in a pyramid structure. Use corporate colors (navy, teal, orange) on a dark 
background. Include the title "The Three Pillars of IT Leadership" at the 
top and "Episode 385" in the corner. Make it bold, clean, and suitable for 
LinkedIn. 16:9 aspect ratio.

Style Keywords

Visual style: isometric 3D, flat design, minimalist, cinematic, data visualization
Mood: professional, bold, modern, tech-forward, premium
Composition: centered, asymmetric, grid layout, hero image

Brand Consistency

For YBH-branded images:

const brandPrompt = `
  Create a ${visualStyle} infographic with:
  
  Colors:
  - Primary: Yellow (#F7B500), Orange (#F17529), Red (#EF4136)
  - Background: Dark navy (#1A1A2E)
  - Text: White (#FFFFFF)
  
  Typography:
  - Title: Fonseca Bold, 48pt
  - Body: Montserrat Regular, 16pt
  
  Include:
  - Episode number in corner
  - YBH branding subtle but present
  - Bold, premium, industrial aesthetic
`

Service Integration

For service-level usage, see:

Kie.ai Service Reference - TypeScript functions and polling utilities

Rate Limits & Costs

Kie.ai Costs: Image generation incurs costs per request:

2K resolution: ~$0.10-0.15 per image
4K resolution: ~$0.20-0.30 per image
Transformation: Same cost as generation

Monitor usage via Kie.ai dashboard.

No Built-in Limits: The API does not enforce rate limits. Implement client-side throttling to control costs.

Common Issues

Task Times Out

If a task exceeds 4.5 minutes:

Check Kie.ai dashboard for task status
Increase maxAttempts or intervalMs in polling
Simplify the prompt (complex requests take longer)

Image URL is Null

If state: "success" but imageUrl is null:

Check Kie.ai API response structure
Wait a few seconds and poll again
Contact Kie.ai support if persistent

Generation Fails

Common failure reasons:

Prompt violates content policy
Input image URLs are inaccessible
Kie.ai service outage

Check failMsg for details.

Endpoints

Services

Image Generation

Image Generation

Create Generation Task

Request

Response

Kie.ai Request Format

Check Task Status

Response

Task States

Polling Pattern

Image Transformation

Transformation Examples

Aspect Ratios

Resolutions

Error Responses

Prompt Engineering

Good Prompt Structure

Style Keywords

Brand Consistency

Service Integration

Rate Limits & Costs

Common Issues

Task Times Out

Image URL is Null

Generation Fails

Build docs developers (and LLMs) love

Endpoints

Services

​Image Generation

​Create Generation Task

​Request

​Response

​Kie.ai Request Format

​Check Task Status

​Response

​Task States

​Polling Pattern

​Image Transformation

​Transformation Examples

​Aspect Ratios

​Resolutions

​Error Responses

​Prompt Engineering

​Good Prompt Structure

​Style Keywords

​Brand Consistency

​Service Integration

​Rate Limits & Costs

​Common Issues

​Task Times Out

​Image URL is Null

​Generation Fails

Build docs developers (and LLMs) love

Image Generation

Create Generation Task

Request

Response

Kie.ai Request Format

Check Task Status

Response

Task States

Polling Pattern

Image Transformation

Transformation Examples

Aspect Ratios

Resolutions

Error Responses

Prompt Engineering

Good Prompt Structure

Style Keywords

Brand Consistency

Service Integration

Rate Limits & Costs

Common Issues

Task Times Out

Image URL is Null

Generation Fails