API Documentation

Integrate automated image generation directly into your application using our official zero-dependency Python SDK, Node.js SDK, or raw cURL / REST API calls.

🔑 Need an API Key? Register your account at imageapiai.com to generate your secret API key (sk_live_...) and start creating images immediately.

Python SDK (`imageapiai`)

Install from pypi.org/project/imageapiai:

pip install imageapiai

SDK Initialization

from imageapiai import ImageAPI

# Zero-config (loads os.environ["IMAGEAPIAI_API_KEY"])
client = ImageAPI()

# Or explicit key initialization
client = ImageAPI(api_key='sk_live_YOUR_API_KEY')

Node.js SDK (`imageapiai`)

Install from npmjs.com/package/imageapiai:

npm install imageapiai

SDK Initialization

const ImageAPI = require('imageapiai');

// Zero-config (loads process.env.IMAGEAPIAI_API_KEY)
const client = new ImageAPI();

// Or explicit key initialization
const client = new ImageAPI({
  apiKey: 'sk_live_YOUR_API_KEY'
});

💡 Explore Showcase: Check out already generated community images and prompts on our Showcase Gallery.

REST Base URL

https://imageapiai.com/v1

Authentication

Register at imageapiai.com to create your API key. Pass your key in the HTTP Authorization header using the standard Bearer token scheme:

Authorization: Bearer sk_live_YOUR_API_KEY

POST /images/generate

Generate a new AI image from scratch using prompt inputs. Deducts credits from your account balance.

Request Body (JSON / SDK Options)

Parameter	Type	Required	Description
`prompt`	String	Yes	The primary image prompt description.
`width`	Number	No	Width in pixels (Default: `512`).
`height`	Number	No	Height in pixels (Default: `512`).
`quality`	String	No	Inference quality: `low`, `medium` (default), or `high`.

Example Request

# Shorthand string generation
result = client.generate('A futuristic city skyline with flying vehicles at sunset')

# Full options call with attribute access
result = client.generate(
    prompt='A futuristic city skyline with flying vehicles at sunset',
    width=512,
    height=512,
    quality='medium'
)

print(result.data.image_url)

// Shorthand string generation
const result = await client.generate('A futuristic city skyline with flying vehicles at sunset');

// Full options call
const result = await client.generate({
  prompt: 'A futuristic city skyline with flying vehicles at sunset',
  width: 512,
  height: 512,
  quality: 'medium'
});

console.log(result.data.imageUrl); // camelCase or snake_case both work

curl -X POST "https://imageapiai.com/v1/images/generate" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline with flying vehicles at sunset",
    "width": 512,
    "height": 512,
    "quality": "medium"
  }'

Example Response (200 OK)

{
  "success": true,
  "data": {
    "image_url": "https://cdn.imageapiai.com/images/user_1/gen_a1b2c3d4e5f6.png",
    "prompt_id": "gen_a1b2c3d4e5f6",
    "original_prompt": "A futuristic city skyline with flying vehicles at sunset",
    "effective_prompt": "A futuristic city skyline with flying vehicles at sunset",
    "quality_used": "medium",
    "is_retry": false,
    "retries_remaining": 5,
    "credits_deducted": 0.498,
    "credits_remaining": 49.502
  }
}

POST /images/generate

Refine an existing image by appending additions to the original base prompt. Overwrites the existing image file in storage for 0 credits.

Free Retry Policy: Up to 5 free prompt modifications are allowed per generation. The original base prompt is permanently locked to prevent credit misuse, and additions are appended directly to it.

Request Body (JSON / SDK Options)

Parameter	Type	Required	Description
`parent_prompt_id`	String	Yes	The `prompt_id` or `generation_id` of the existing image.
`prompt_update`	String	Yes	The additions/modifications to append to the base prompt.
`width` / `height` / `quality`	Number/String	No	Optional dimensional or quality overrides.

Example Request

# Using convenience refine() method for 0 credits
result = client.refine(
    parent_prompt_id='gen_a1b2c3d4e5f6',
    prompt_update='add neon rain reflections on the streets and bright billboards',
    quality='high'
)

print(result.data.image_url)

// Using convenience refine() method for 0 credits
const result = await client.refine(
  'gen_a1b2c3d4e5f6', // parent_prompt_id
  'add neon rain reflections on the streets and bright billboards', // prompt_update
  { quality: 'high' }
);

console.log(result.data.imageUrl);

curl -X POST "https://imageapiai.com/v1/images/generate" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_prompt_id": "gen_a1b2c3d4e5f6",
    "prompt_update": "add neon rain reflections on the streets and bright billboards"
  }'

Example Response (200 OK)

{
  "success": true,
  "data": {
    "image_url": "https://cdn.imageapiai.com/images/user_1/gen_a1b2c3d4e5f6.png",
    "prompt_id": "gen_a1b2c3d4e5f6",
    "original_prompt": "A futuristic city skyline with flying vehicles at sunset",
    "effective_prompt": "A futuristic city skyline with flying vehicles at sunset, add neon rain reflections on the streets and bright billboards",
    "quality_used": "medium",
    "is_retry": true,
    "retries_remaining": 4,
    "credits_deducted": 0,
    "credits_remaining": 49.502
  }
}

GET /images/history

Retrieve a list of all past image generations associated with your account.

Example Request

history = client.get_history()
for item in history.data:
    print(f"ID: {item.generation_id} | Prompt: {item.prompt_text}")

const history = await client.getHistory();
console.log(history.data);

curl -X GET "https://imageapiai.com/v1/images/history" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "generation_id": "gen_a1b2c3d4e5f6",
      "original_prompt": "A futuristic city skyline with flying vehicles at sunset",
      "last_update_text": "add neon rain reflections on the streets",
      "prompt_text": "A futuristic city skyline with flying vehicles at sunset, add neon rain reflections on the streets",
      "r2_image_url": "https://cdn.imageapiai.com/images/user_1/gen_a1b2c3d4e5f6.png",
      "retry_number": 1
    }
  ]
}

GET /users/me

Fetch your account profile metrics, credit balance, and active subscription status.

Example Request

profile = client.get_profile()
print("Remaining Credits:", profile.data.credit_balance)

const profile = await client.getProfile();
console.log('Remaining Credits:', profile.data.creditBalance);

curl -X GET "https://imageapiai.com/v1/users/me" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "data": {
    "user_id": "user_1",
    "email": "developer@example.com",
    "credit_balance": 49.502,
    "monthly_credits": 49.502,
    "purchased_credits": 0.0,
    "subscription_status": "active"
  }
}