Image API

Generate, edit, and upscale images. 39 models. 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.
`input`	object	Yes	The fields below go inside `input`.
`input.prompt`	string	Yes	Text description of the image to generate.
`input.negative_prompt`	string	No	Elements to exclude from the image.
`input.aspect_ratio`	string	No	Aspect ratio: `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`. Default: `"1:1"`.
`input.width`, `input.height`	integer	No	Explicit size in pixels, on models that support custom sizes.
`input.seed`	integer	No	Fixed seed for reproducible outputs.
`input.image_url`	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": "z-image-turbo",
    "input": {
      "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="z-image-turbo",
    prompt="A mountain lake at golden hour, photorealistic"
)
print(result.url)   # https://media.fairstack.ai/...
print(result.cost)  # $0.0048

Node.js

import { FairStack } from "fairstack";

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

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

Response

{
  "id": "gen_abc123",
  "status": "completed",
  "url": "https://media.fairstack.ai/image/.../output.png",
  "model": "z-image-turbo",
  "modality": "image",
  "cost": {
    "credits_used": 4800,
    "estimated_credits": 4800,
    "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 USD = 1,000,000 microdollars. So credits_used: 30000 = $0.03, and the example above (4800) = $0.0048. 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": "z-image-turbo",
    "input": { "prompt": "test" },
    "confirm": false
  }'

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

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-pro",
  "input": {
    "prompt": "Change the background to a tropical beach",
    "image_url": "https://example.com/photo.jpg"
  }
}

Quality tiers

Tier	Example Model	Price	Best For
Standard	FLUX.2	$0.03/image	Marketing, social media, product shots
Premium	Nano Banana Pro	$0.1608/image	Professional, print quality, hero images
Low-cost	Z-Image Turbo	$0.0048/image	Prototyping, bulk generation, thumbnails

Next steps

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

Overview Video API