Image API

Generate, edit, and upscale images. 142 models from $0.003/image. Cost estimation before execution.

POST /v1/generations/image

Generate an image from a text prompt. Returns the image URL and exact cost.

Request body

Field	Type	Required	Description
`model`	string	Yes	Model key (e.g. `"gpt-image-1.5-t2i"`, `"z-image-turbo"`). See Model Catalog.
`prompt`	string	Yes	Text description of the image to generate.
`negative_prompt`	string	No	Elements to exclude from the image.
`aspect_ratio`	string	No	Aspect ratio: `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`. Default: `"1:1"`.
`image_size`	string	No	Explicit size: `"1024x1024"`, `"1280x720"`, etc. Overrides aspect_ratio.
`seed`	integer	No	Fixed seed for reproducible outputs.
`image`	string (URL)	No	Source image URL for image-to-image editing.
`confirm`	boolean	No	Set to `false` to get a cost estimate without generating. Default: `true`.

Response fields

Field	Type	Description
`id`	string	Unique generation ID (`gen_` prefix).
`status`	string	`"completed"` or `"failed"`.
`url`	string	CDN URL of the generated image.
`model`	string	Model key used for generation.
`modality`	string	Always `"image"`.
`cost.credits_used`	integer	Actual cost charged, in microdollars.
`cost.estimated_credits`	integer	Estimated cost, in microdollars.
`cost.currency`	string	Always `"microdollars"`.
`metadata.width`	integer	Output image width in pixels.
`metadata.height`	integer	Output image height in pixels.
`metadata.seed`	integer	Seed used (for reproducibility).

Code examples

curl

curl -X POST https://api.fairstack.ai/v1/generations/image \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5-t2i",
    "prompt": "A mountain lake at golden hour, photorealistic"
  }'

Python

from fairstack import FairStack

client = FairStack(api_key="fs_live_YOUR_KEY")

result = client.generate.image(
    model="gpt-image-1.5-t2i",
    prompt="A mountain lake at golden hour, photorealistic"
)
print(result.url)   # https://media.fairstack.ai/...
print(result.cost)  # $0.009

Node.js

import { FairStack } from "fairstack";

const client = new FairStack({ apiKey: "fs_live_YOUR_KEY" });

const result = await client.generate.image({
  model: "gpt-image-1.5-t2i",
  prompt: "A mountain lake at golden hour, photorealistic",
});
console.log(result.url);   // https://media.fairstack.ai/...
console.log(result.cost);  // { credits_used: 9000, estimated_credits: 9000, currency: "microdollars" }

Response

{
  "id": "gen_abc123",
  "status": "completed",
  "url": "https://media.fairstack.ai/image/.../output.png",
  "model": "gpt-image-1.5-t2i",
  "modality": "image",
  "cost": {
    "credits_used": 9000,
    "estimated_credits": 9000,
    "currency": "microdollars"
  },
  "metadata": {
    "width": 1024,
    "height": 1024,
    "seed": 42
  }
}

Cost units. Every value inside cost is an integer in microdollars, as flagged by currency: "microdollars". The conversion is 1 credit = 1 cent = 10,000 microdollars (1 USD = 1,000,000 microdollars). So credits_used: 30000 = $0.03 = 3 credits, and the example above (9000) = $0.009 = 0.9 credits. The field is named credits_used for backward compatibility with existing SDKs — always read it as microdollars and convert as needed.

Cost estimation

Set confirm: false to get the exact cost without generating an image or being charged. This is especially useful for AI agents that need to evaluate budget impact before executing.

curl -X POST https://api.fairstack.ai/v1/generations/image \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -d '{
    "model": "gpt-image-1.5-t2i",
    "prompt": "test",
    "confirm": false
  }'

# Response (no image generated, no charge):
# { "estimated_cost": { "micro": 9000, "display": "$0.009" } }

Image editing

Upload a source image URL and describe what to change. Models like FLUX Kontext and GPT Image 1.5 support in-context editing.

{
  "model": "flux-kontext-dev",
  "prompt": "Change the background to a tropical beach",
  "image": "https://example.com/photo.jpg"
}

Quality tiers

Tier	Example Model	Price	Best For
Budget	Z-Image Turbo	$0.003-0.004	Prototyping, bulk generation, thumbnails
Standard	FLUX.1 Pro, Seedream 4.5	$0.02-0.04	Marketing, social media, product shots
Premium	GPT Image 1.5, Imagen 4 Ultra	$0.04-0.06	Professional, print quality, hero images

Next steps

Image Guide -- quality tiers, aspect ratios, negative prompts
Image Models -- browse all 142 image models
Jobs API -- async polling for long-running generations
Model Catalog -- browse all models

Overview Video API