Image Generation

FOTOhub provides access to 25+ image generation models from 8 providers: Google Vertex AI, OpenAI, Microsoft MAI, BytePlus, xAI, Black Forest Labs, MiniMax, and Kling. Generate photorealistic images, illustrations, concept art, and more via a single unified endpoint.

Two Billing Modes

Credit-based — Fixed cost per image regardless of resolution. Most models use this mode.
Token-based — Cost scales with output resolution (pixel count). Used by BytePlus SeedDream models.

Endpoint

POST /v1/ai/generate/image

Authentication: Bearer token (API key)
Billing: 1–8 credits per image (credit-based) or token-based for SeedDream models

Request Parameters

Parameter	Type	Required	Default	Description
`prompt`	string	Yes	—	Text description of the image to generate. Be specific — include subject, style, lighting, composition details for best results. Max 4096 characters.
`model`	string	No	`"imagen-3-fast"`	Model identifier. See the full model list below for all 25 options. We recommend `seedream-5-0-260128` for best quality.
`width`	integer	No	`1024`	Output image width in pixels. Range: 256–4096. Must be divisible by 64 for most models.
`height`	integer	No	`1024`	Output image height in pixels. Range: 256–4096. Must be divisible by 64 for most models.
`aspect_ratio`	string	No	`"1:1"`	Aspect ratio preset. Options: `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`. Overrides width/height when set.
`num_images`	integer	No	`1`	Number of images to generate per request. Range: 1–4. Credits are charged per image.
`negative_prompt`	string	No	—	Describe what to avoid in the generated image. E.g., `"blurry, low quality, distorted faces"`. Not supported by all models.
`style`	string	No	—	Style preset. Common options: `"photorealistic"`, `"cinematic"`, `"anime"`, `"digital-art"`, `"oil-painting"`.
`seed`	integer	No	random	Seed for reproducible generation. Same prompt + seed + model = same output. Range: 0–4294967295.

Resolution Tips

Use aspect_ratio instead of manual width/height for most use cases. The API automatically picks optimal dimensions for the selected model. For token-based models (BytePlus), higher resolution directly increases cost.

Response Format

Credit-Based Response (Standard Models)

json

{
  "model": "seedream-5-0-260128",
  "credits_used": 2,
  "billing": {
    "method": "credits",
    "credits_used": 2,
    "pln_charged": 0.30
  },
  "images": [
    "https://s1.fotohub.app/storage/v1/object/public/generations/img_abc123.png"
  ],
  "metadata": {
    "width": 1024,
    "height": 1024,
    "seed": 42,
    "model": "seedream-5-0-260128",
    "generation_time_ms": 3200
  }
}

Token-Based Response (BytePlus SeedDream Models)

json

{
  "model": "seedream-5-0-260128",
  "credits_used": 2,
  "billing": {
    "method": "token",
    "credits_used": 2,
    "pln_charged": 0.049,
    "cost_breakdown": {
      "output_tokens": 4096,
      "cost_usd": 0.008192,
      "cost_pln": 0.049152,
      "rate_per_1m_tokens_usd": 2.00
    }
  },
  "usage": {
    "output_tokens": 4096
  },
  "images": [
    "https://s1.fotohub.app/storage/v1/object/public/generations/img_def456.png"
  ],
  "metadata": {
    "width": 1024,
    "height": 1024,
    "seed": 8817,
    "model": "seedream-5-0-260128",
    "generation_time_ms": 2100
  }
}

Token-Based Billing (BytePlus Models)

BytePlus SeedDream models use per-token billing where cost scales with output resolution. Generating a 4K image costs 16x more than a 1K image.

Cost Scales with Resolution

Unlike credit-based models where a 4K image costs the same as a 1K image, token-based models charge proportionally to pixel count. Always check the estimated cost before generating at high resolutions.

Token Calculation Formula

output_tokens = (width × height) / 256
cost_usd = (output_tokens / 1,000,000) × rate_per_1m_usd
cost_pln = cost_usd × 4.0 (USD→PLN) × 1.5 (margin)

Resolution to Token Examples

Resolution	Output Tokens	Cost (USD) @ $2/1M	Cost (PLN)
1024 × 1024	4,096	$0.0082	0.049 PLN
1536 × 1536	9,216	$0.0184	0.111 PLN
2048 × 2048	16,384	$0.0328	0.197 PLN
3072 × 3072	36,864	$0.0737	0.442 PLN
4096 × 4096	65,536	$0.1311	0.786 PLN

Token-Based Model Rates

Model	Rate (USD/1M tokens)	Credits (min)
`seedream-5-0-260128`	$2.00	2
`seedream-4-5-251128`	$2.50	3
`seedream-4-0-250828`	$2.00	2
`dola-seedream-5-0-pro-260628`	$3.50	3
`seededit-3-0-i2i-250628`	$2.50	3

All Models — Complete Pricing

Google Vertex AI (Imagen)

Model ID	Name	Price (PLN)	Credits	Notes
`imagen-3-fast`	Imagen 3 Fast	0.12	1	512px fast
`imagen-3-standard`	Imagen 3 Standard	0.24	2	1K
`imagen-4-fast`	Imagen 4 Fast	0.18	2	—
`imagen-4-standard`	Imagen 4 Standard	0.45	3	High quality
`imagen-4-ultra`	Imagen 4 Ultra	0.90	5	4K

OpenAI

Model ID	Name	Price (PLN)	Credits	Notes
`dall-e-3`	DALL-E 3	0.24	2	—
`dall-e-3-hd`	DALL-E 3 HD	0.48	4	—
`gpt-image-1`	GPT Image 1	0.60	4	—
`gpt-image-2`	GPT Image 2	1.60	10	Recommended — highest fidelity

Microsoft MAI

Model ID	Name	Price (PLN)	Credits	Notes
`mai-image-2.5`	MAI-Image 2.5	0.60	3	High quality, prompt rewriting
`mai-image-2.5-flash`	MAI-Image 2.5 Flash	0.20	1	Fast, budget-friendly

Size constraints: min 768px per dimension, max ~1024x1024 (1,056,768 total pixels). Supported aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4.

BytePlus SeedDream (Token-Based)

Model ID	Name	~PLN @1K	Credits	Notes
`seedream-4-0-250828`	SeedDream 4.0	0.18	2	token-based
`seedream-5-0-260128`	SeedDream 5.0 Lite	0.21	2	Recommended, best value
`seedream-4-5-251128`	SeedDream 4.5	0.24	3	token-based
`dola-seedream-5-0-pro-260628`	SeedDream 5.0 Pro (Dola)	0.27	3	token-based
`seededit-3-0-i2i-250628`	SeedEdit 3.0 (img2img)	0.24	3	token-based

xAI (Grok Imagine)

Model ID	Name	Price (PLN)	Credits	Notes
`grok-imagine-image`	Grok Imagine	0.12	1	1K, single-image edit
`grok-imagine-image-quality`	Grok Imagine Quality	0.36	3	2K, multi-image combine (up to 3 refs), virtual try-on

xAI Grok Image — Capabilities

Feature	`grok-imagine-image`	`grok-imagine-image-quality`
Text-to-Image	Yes	Yes
Single Image Edit	Yes	Yes
Multi-Image Combine (up to 3)	—	Yes
Virtual Try-On	—	Yes
Max Resolution	1K	2K
Max `num_images` per request	10	10
Aspect Ratios	7	7

Supported Aspect Ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9

xAI Grok Models

Grok Imagine Quality is ideal for e-commerce: multi-image product listings, virtual try-on, and high-quality edits at 2K resolution. The basic model is a fast, budget-friendly option for social media and quick prototypes at 1K.

Black Forest Labs — FLUX (via Azure AI)

4 active FLUX models routed through Azure AI. Maximum resolution: 1440px per side.

Model ID	Name	Price (PLN)	Credits	Notes
`flux-1.1-pro`	FLUX 1.1 Pro	0.24	2	high quality, creative
`flux-kontext-pro`	FLUX Kontext Pro	0.24	2	context-aware editing, style transfer
`flux-2-pro`	FLUX.2 Pro	0.24	2	balanced, versatile
`flux-2-flex`	FLUX.2 Flex	0.24	2	steps/guidance control

FLUX via Azure

All FLUX models are served via Azure AI infrastructure for reliable, low-latency inference. Maximum dimension is 1440px per side. Models previously available (Klein, Ultra, Raw, Max, Fill) have been discontinued.

MiniMax (Temporarily Unavailable)

Model ID	Name	Price (PLN)	Credits	Notes
`minimax-image-01`	MiniMax Image 01	0.021	1	budget — currently unavailable

Kling (Temporarily Unavailable)

Model ID	Name	Price (PLN)	Credits	Notes
`kling-v2-1`	Kling V2.1	0.24	2	currently unavailable
`kling-v3`	Kling V3	0.60	5	currently unavailable
`kling-v3-omni`	Kling V3 Omni	0.90	8	currently unavailable

Temporarily Unavailable

Kling and MiniMax models are temporarily unavailable due to provider issues. They will be restored when provider accounts are replenished.

Code Examples

Basic Image Generation

PythonTypeScriptcURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A serene mountain landscape at golden hour, with mist rolling through valleys",
        "model": "seedream-5-0-260128",
        "aspect_ratio": "16:9"
    }
)

data = response.json()
print(f"Image URL: {data['images'][0]}")
print(f"Credits used: {data['credits_used']}")

typescript

const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A serene mountain landscape at golden hour, with mist rolling through valleys",
    model: "seedream-5-0-260128",
    aspect_ratio: "16:9"
  })
});

const data = await response.json();
console.log("Image URL:", data.images[0]);
console.log("Credits used:", data.credits_used);

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at golden hour, with mist rolling through valleys",
    "model": "seedream-5-0-260128",
    "aspect_ratio": "16:9"
  }'

Token-Based Model (SeedDream)

PythonTypeScriptcURL

python

import requests

# SeedDream models use token-based billing — cost scales with resolution
response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Professional product photography of a luxury watch on marble surface",
        "model": "seedream-5-0-260128",
        "width": 2048,
        "height": 2048
    }
)

data = response.json()
print(f"Image URL: {data['images'][0]}")
print(f"Output tokens: {data['usage']['output_tokens']}")
print(f"Cost (PLN): {data['billing']['cost_breakdown']['cost_pln']}")
# At 2048x2048: 16,384 tokens → ~0.197 PLN

typescript

// SeedDream models use token-based billing — cost scales with resolution
const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Professional product photography of a luxury watch on marble surface",
    model: "seedream-5-0-260128",
    width: 2048,
    height: 2048
  })
});

const data = await response.json();
console.log("Image URL:", data.images[0]);
console.log("Output tokens:", data.usage.output_tokens);
console.log("Cost (PLN):", data.billing.cost_breakdown.cost_pln);
// At 2048x2048: 16,384 tokens → ~0.197 PLN

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Professional product photography of a luxury watch on marble surface",
    "model": "seedream-5-0-260128",
    "width": 2048,
    "height": 2048
  }'

High-Resolution 4K Generation

PythonTypeScriptcURL

python

import requests

# Imagen 4 Ultra and FLUX Pro Ultra support native 4K output
response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Ultra detailed architectural visualization of a modern glass house, surrounded by nature, photorealistic 8K quality",
        "model": "imagen-4-ultra",
        "width": 4096,
        "height": 2304,
        "aspect_ratio": "16:9"
    }
)

data = response.json()
print(f"4K Image: {data['images'][0]}")
print(f"Credits: {data['credits_used']}")  # 5 credits for ultra

typescript

// Imagen 4 Ultra and FLUX Pro Ultra support native 4K output
const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Ultra detailed architectural visualization of a modern glass house, surrounded by nature, photorealistic 8K quality",
    model: "imagen-4-ultra",
    width: 4096,
    height: 2304,
    aspect_ratio: "16:9"
  })
});

const data = await response.json();
console.log("4K Image:", data.images[0]);
console.log("Credits:", data.credits_used); // 5 credits for ultra

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Ultra detailed architectural visualization of a modern glass house, surrounded by nature, photorealistic 8K quality",
    "model": "imagen-4-ultra",
    "width": 4096,
    "height": 2304,
    "aspect_ratio": "16:9"
  }'

Generate Multiple Variations

PythonTypeScriptcURL

python

import requests

# Generate 4 variations in a single request
response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Minimalist logo design for a tech startup, clean vector style",
        "model": "flux-2-max",
        "num_images": 4,
        "aspect_ratio": "1:1"
    }
)

data = response.json()
# Credits charged: 4 images x 4 credits = 16 credits total
for i, url in enumerate(data["images"]):
    print(f"Variation {i+1}: {url}")
print(f"Total credits: {data['credits_used']}")

typescript

// Generate 4 variations in a single request
const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Minimalist logo design for a tech startup, clean vector style",
    model: "flux-2-max",
    num_images: 4,
    aspect_ratio: "1:1"
  })
});

const data = await response.json();
// Credits charged: 4 images x 4 credits = 16 credits total
data.images.forEach((url: string, i: number) => {
  console.log(`Variation ${i + 1}: ${url}`);
});
console.log("Total credits:", data.credits_used);

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Minimalist logo design for a tech startup, clean vector style",
    "model": "flux-2-max",
    "num_images": 4,
    "aspect_ratio": "1:1"
  }'

Negative Prompt & Style Preset

PythonTypeScriptcURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Portrait of a woman in Renaissance style, oil painting, dramatic lighting, rich colors",
        "model": "flux-kontext-max",
        "negative_prompt": "blurry, low quality, distorted, deformed, watermark, text overlay, cartoon",
        "style": "oil-painting",
        "aspect_ratio": "3:4",
        "seed": 42  # Use seed for reproducible results
    }
)

data = response.json()
print(f"Image: {data['images'][0]}")
print(f"Seed used: {data['metadata']['seed']}")  # 42 — same result every time

typescript

const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Portrait of a woman in Renaissance style, oil painting, dramatic lighting, rich colors",
    model: "flux-kontext-max",
    negative_prompt: "blurry, low quality, distorted, deformed, watermark, text overlay, cartoon",
    style: "oil-painting",
    aspect_ratio: "3:4",
    seed: 42 // Use seed for reproducible results
  })
});

const data = await response.json();
console.log("Image:", data.images[0]);
console.log("Seed used:", data.metadata.seed); // 42 — same result every time

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Portrait of a woman in Renaissance style, oil painting, dramatic lighting, rich colors",
    "model": "flux-kontext-max",
    "negative_prompt": "blurry, low quality, distorted, deformed, watermark, text overlay, cartoon",
    "style": "oil-painting",
    "aspect_ratio": "3:4",
    "seed": 42
  }'

xAI Grok Imagine — Advanced Use Cases

Grok Imagine models support generation, editing, multi-image combine, and virtual try-on through a unified API.

Product Launch (Text-to-Image, 2K)

PythonTypeScriptcURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Premium product photography of a luxury perfume bottle on marble surface, "
                  "dramatic studio lighting, soft shadows, bokeh background, commercial quality",
        "model": "grok-imagine-image-quality",
        "aspect_ratio": "2:3",
        "num_images": 1
    }
)

data = response.json()
print(f"2K product shot: {data['images'][0]}")
# 3 credits, 2K resolution, portrait 2:3 aspect

typescript

const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Premium product photography of a luxury perfume bottle on marble surface, " +
            "dramatic studio lighting, soft shadows, bokeh background, commercial quality",
    model: "grok-imagine-image-quality",
    aspect_ratio: "2:3",
    num_images: 1
  })
});

const data = await response.json();
console.log("2K product shot:", data.images[0]);

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Premium product photography of a luxury perfume bottle on marble surface, dramatic studio lighting, soft shadows, bokeh background, commercial quality",
    "model": "grok-imagine-image-quality",
    "aspect_ratio": "2:3",
    "num_images": 1
  }'

PythoncURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Trendy flat-lay coffee shop photo, latte art, notebook and laptop, "
                  "warm tones, Instagram aesthetic, overhead shot",
        "model": "grok-imagine-image",
        "aspect_ratio": "1:1",
        "num_images": 4
    }
)

data = response.json()
# 4 variations at 1 credit each = 4 credits total
for i, url in enumerate(data["images"]):
    print(f"Variation {i+1}: {url}")

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Trendy flat-lay coffee shop photo, latte art, notebook and laptop, warm tones, Instagram aesthetic",
    "model": "grok-imagine-image",
    "aspect_ratio": "1:1",
    "num_images": 4
  }'

Product Display Edit (Single Reference Image)

Edit an existing product photo — change background, lighting, or context while preserving the product.

PythonTypeScriptcURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Place this product in a modern minimalist kitchen, marble countertop, "
                  "soft natural window light, lifestyle photography",
        "model": "grok-imagine-image-quality",
        "aspect_ratio": "3:4",
        "image_url": "https://your-storage.com/product-photo.jpg"
    }
)

data = response.json()
print(f"Edited product: {data['images'][0]}")
# 3 credits — single image edit mode

typescript

const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Place this product in a modern minimalist kitchen, marble countertop, " +
            "soft natural window light, lifestyle photography",
    model: "grok-imagine-image-quality",
    aspect_ratio: "3:4",
    image_url: "https://your-storage.com/product-photo.jpg"
  })
});

const data = await response.json();
console.log("Edited product:", data.images[0]);

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Place this product in a modern minimalist kitchen, marble countertop, soft natural window light",
    "model": "grok-imagine-image-quality",
    "aspect_ratio": "3:4",
    "image_url": "https://your-storage.com/product-photo.jpg"
  }'

Combined Product Listing (Multi-Image, up to 3 References)

Combine multiple product images into a single cohesive composition. Only available with grok-imagine-image-quality.

PythonTypeScriptcURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Arrange all products in an elegant flat-lay composition, "
                  "clean white background, consistent lighting, e-commerce catalog style",
        "model": "grok-imagine-image-quality",
        "aspect_ratio": "1:1",
        "image_urls": [
            "https://your-storage.com/product-1.jpg",
            "https://your-storage.com/product-2.jpg",
            "https://your-storage.com/product-3.jpg"
        ]
    }
)

data = response.json()
print(f"Combined listing: {data['images'][0]}")
# 3 credits — multi-image combine mode (max 3 reference images)

typescript

const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Arrange all products in an elegant flat-lay composition, " +
            "clean white background, consistent lighting, e-commerce catalog style",
    model: "grok-imagine-image-quality",
    aspect_ratio: "1:1",
    image_urls: [
      "https://your-storage.com/product-1.jpg",
      "https://your-storage.com/product-2.jpg",
      "https://your-storage.com/product-3.jpg"
    ]
  })
});

const data = await response.json();
console.log("Combined listing:", data.images[0]);

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Arrange all products in an elegant flat-lay composition, clean white background, consistent lighting",
    "model": "grok-imagine-image-quality",
    "aspect_ratio": "1:1",
    "image_urls": [
      "https://your-storage.com/product-1.jpg",
      "https://your-storage.com/product-2.jpg",
      "https://your-storage.com/product-3.jpg"
    ]
  }'

Multi-Image Limits

Maximum 3 reference images per request
Only available with grok-imagine-image-quality model
All images must be publicly accessible URLs or FOTOhub storage URLs
Higher resolution images produce better combine results

Virtual Try-On (2 References — Person + Garment)

Show a person wearing a specific garment or accessory. Provide the person photo and the product image.

PythonTypeScriptcURL

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/generate/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Virtual try-on: person wearing the garment from second image, "
                  "natural fit, correct proportions, photorealistic, keep person's face and body",
        "model": "grok-imagine-image-quality",
        "aspect_ratio": "3:4",
        "image_urls": [
            "https://your-storage.com/model-photo.jpg",     # Person
            "https://your-storage.com/dress-product.jpg"    # Garment
        ]
    }
)

data = response.json()
print(f"Try-on result: {data['images'][0]}")
# 3 credits — virtual try-on mode via multi-image

typescript

const response = await fetch("https://apis.fotohub.app/v1/ai/generate/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fh_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Virtual try-on: person wearing the garment from second image, " +
            "natural fit, correct proportions, photorealistic",
    model: "grok-imagine-image-quality",
    aspect_ratio: "3:4",
    image_urls: [
      "https://your-storage.com/model-photo.jpg",
      "https://your-storage.com/dress-product.jpg"
    ]
  })
});

const data = await response.json();
console.log("Try-on result:", data.images[0]);

bash

curl -X POST https://apis.fotohub.app/v1/ai/generate/image \
  -H "Authorization: Bearer fh_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Virtual try-on: person wearing the garment from second image, natural fit, photorealistic",
    "model": "grok-imagine-image-quality",
    "aspect_ratio": "3:4",
    "image_urls": [
      "https://your-storage.com/model-photo.jpg",
      "https://your-storage.com/dress-product.jpg"
    ]
  }'

Virtual Try-On Best Practices

Person image first — full-body or half-body shot, clear pose, neutral background
Garment image second — flat-lay or mannequin shot showing full garment
Use 3:4 or 2:3 aspect ratio for best full-body results
Include "keep person's face" in prompt to preserve identity
Works with clothing, accessories, eyewear, hats, shoes

Image Editing

Modify existing images with AI-powered editing operations including inpainting, outpainting, background replacement, object removal, and upscaling.

Endpoint

POST /v1/ai/edit/image

Billing: 2 credits per edit (fixed, regardless of mode or resolution)

Parameters

Parameter	Type	Required	Description
`image_url`	string	Yes	URL of the source image. Must be publicly accessible or a FOTOhub storage URL.
`prompt`	string	Yes	Description of the desired edit.
`mode`	string	Yes	`"inpaint"`, `"outpaint"`, `"bgswap"`, `"remove"`, or `"upscale"`
`mask_url`	string	No	Mask image URL (white = edit area). Required for `"inpaint"` mode.

Editing Examples

Background SwapInpaintUpscale

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/edit/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "image_url": "https://s1.fotohub.app/storage/v1/object/public/uploads/photo.jpg",
        "prompt": "Professional studio background with soft gradient lighting",
        "mode": "bgswap"
    }
)

data = response.json()
print(f"Edited image: {data['images'][0]}")

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/edit/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "image_url": "https://s1.fotohub.app/storage/v1/object/public/uploads/room.jpg",
        "prompt": "A modern minimalist sofa with clean lines",
        "mode": "inpaint",
        "mask_url": "https://s1.fotohub.app/storage/v1/object/public/uploads/room_mask.png"
    }
)

data = response.json()
print(f"Edited image: {data['images'][0]}")

python

import requests

response = requests.post(
    "https://apis.fotohub.app/v1/ai/edit/image",
    headers={
        "Authorization": "Bearer fh_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "image_url": "https://s1.fotohub.app/storage/v1/object/public/uploads/low_res.jpg",
        "prompt": "Enhance resolution, preserve details, sharpen edges",
        "mode": "upscale"
    }
)

data = response.json()
print(f"Upscaled image: {data['images'][0]}")

Error Responses

Status	Code	Description
400	`invalid_model`	The specified model does not exist or is not available for image generation.
400	`invalid_dimensions`	Width or height is out of range (256–4096) or not divisible by 64.
400	`invalid_prompt`	Prompt is empty, exceeds maximum length (4096 chars), or contains blocked content.
401	`unauthorized`	Missing or invalid API key. Ensure the Authorization header uses format: `Bearer fh_live_*`
402	`insufficient_credits`	Account does not have enough credits. Purchase more or upgrade your plan.
429	`rate_limit_exceeded`	Too many requests. Default: 20 req/min for image generation. Check `Retry-After` header.
500	`generation_failed`	Upstream provider error. No credits are charged on failure.

Error Response Example

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Required: 3, available: 1. Please top up your account.",
    "status": 402,
    "details": {
      "required_credits": 3,
      "available_credits": 1,
      "model": "imagen-4-standard"
    }
  }
}

No Charge on Failure

If a generation fails due to a provider error (500), your credits are not deducted. You will only be charged for successful generations that return image URLs.

Image Generation ​

Endpoint ​

Request Parameters ​

Response Format ​

Credit-Based Response (Standard Models) ​

Token-Based Response (BytePlus SeedDream Models) ​

Token-Based Billing (BytePlus Models) ​

Token Calculation Formula ​

Resolution to Token Examples ​

Token-Based Model Rates ​

All Models — Complete Pricing ​

Google Vertex AI (Imagen) ​

OpenAI ​

Microsoft MAI ​

BytePlus SeedDream (Token-Based) ​

xAI (Grok Imagine) ​

xAI Grok Image — Capabilities ​

Black Forest Labs — FLUX (via Azure AI) ​

MiniMax (Temporarily Unavailable) ​

Kling (Temporarily Unavailable) ​

Code Examples ​

Basic Image Generation ​

Token-Based Model (SeedDream) ​

High-Resolution 4K Generation ​

Generate Multiple Variations ​

Negative Prompt & Style Preset ​

xAI Grok Imagine — Advanced Use Cases ​

Product Launch (Text-to-Image, 2K) ​

Social Media Post (Text-to-Image, 1K) ​

Product Display Edit (Single Reference Image) ​

Combined Product Listing (Multi-Image, up to 3 References) ​

Virtual Try-On (2 References — Person + Garment) ​

Image Editing ​

Endpoint ​

Parameters ​

Editing Examples ​

Error Responses ​

Error Response Example ​

Image Generation

Endpoint

Request Parameters

Response Format

Credit-Based Response (Standard Models)

Token-Based Response (BytePlus SeedDream Models)

Token-Based Billing (BytePlus Models)

Token Calculation Formula

Resolution to Token Examples

Token-Based Model Rates

All Models — Complete Pricing

Google Vertex AI (Imagen)

OpenAI

Microsoft MAI

BytePlus SeedDream (Token-Based)

xAI (Grok Imagine)

xAI Grok Image — Capabilities

Black Forest Labs — FLUX (via Azure AI)

MiniMax (Temporarily Unavailable)

Kling (Temporarily Unavailable)

Code Examples

Basic Image Generation

Token-Based Model (SeedDream)

High-Resolution 4K Generation

Generate Multiple Variations

Negative Prompt & Style Preset

xAI Grok Imagine — Advanced Use Cases

Product Launch (Text-to-Image, 2K)

Social Media Post (Text-to-Image, 1K)

Product Display Edit (Single Reference Image)

Combined Product Listing (Multi-Image, up to 3 References)

Virtual Try-On (2 References — Person + Garment)

Image Editing

Endpoint

Parameters

Editing Examples

Error Responses

Error Response Example