Image generation

Generate images through two paths: the Response API with OpenAI’s image_generation hosted tool, or Chat Completions with Gemini’s native image output.

Prerequisites

An Auriko API key
Python 3.10+ with the OpenAI SDK (pip install openai) or the auriko SDK (pip install auriko)
- OR Node.js 18+ with the OpenAI SDK (npm install openai) or @auriko/sdk (npm install @auriko/sdk)
An image-capable model: gemini-2.5-flash-image, gemini-3-pro-image, or gemini-3.1-flash-image

Generate images

Create a chat completion with an image-capable model and save the generated image:

import os
import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
)

response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{
        "role": "user",
        "content": "Draw a cartoon cat wearing a top hat",
    }],
)

image = response.choices[0].message.images[0]
image_bytes = base64.b64decode(image["data"])

with open("output.png", "wb") as f:
    f.write(image_bytes)

print(f"Saved {image['mime_type']} image ({len(image_bytes)} bytes)")

import OpenAI from "openai";
import { writeFileSync } from "fs";

const client = new OpenAI({
    apiKey: process.env.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/v1",
});

const response = await client.chat.completions.create({
    model: "gemini-2.5-flash-image",
    messages: [{
        role: "user",
        content: "Draw a cartoon cat wearing a top hat",
    }],
});

const image = response.choices[0].message.images[0];
const imageBytes = Buffer.from(image.data, "base64");

writeFileSync("output.png", imageBytes);

console.log(`Saved ${image.mime_type} image (${imageBytes.length} bytes)`);

import os
import base64
from auriko import Client

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
)

response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{
        "role": "user",
        "content": "Draw a cartoon cat wearing a top hat",
    }],
)

image = response.choices[0].message.images[0]
image_bytes = base64.b64decode(image["data"])

with open("output.png", "wb") as f:
    f.write(image_bytes)

print(f"Saved {image['mime_type']} image ({len(image_bytes)} bytes)")

import { Client } from "@auriko/sdk";
import { writeFileSync } from "fs";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/v1",
});

const response = await client.chat.completions.create({
    model: "gemini-2.5-flash-image",
    messages: [{
        role: "user",
        content: "Draw a cartoon cat wearing a top hat",
    }],
});

const image = response.choices[0].message.images[0];
const imageBytes = Buffer.from(image.data, "base64");

writeFileSync("output.png", imageBytes);

console.log(`Saved ${image.mime_type} image (${imageBytes.length} bytes)`);

curl https://api.auriko.ai/v1/chat/completions \
  -H "Authorization: Bearer $AURIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "messages": [{
      "role": "user",
      "content": "Draw a cartoon cat wearing a top hat"
    }]
  }' | jq -r '.choices[0].message.images[0].data' | base64 --decode > output.png

image_tokens in usage.completion_tokens_details reports tokens consumed by generated images. The images field is absent when no images are generated. In streaming responses, images arrive complete in a single delta chunk.

Response shape

Each entry in the images array is a GeneratedImage object:

Field	Type	Description
`type`	`string`	Always `"image"`
`mime_type`	`string`	MIME type (e.g., `image/png`)
`data`	`string`	Base64-encoded image data
`thought_signature`	`string?`	Opaque model signature. Response-only

Generate images with the Response API

Use a supported main model with OpenAI’s image_generation hosted tool to generate images via the Response API. Specify the image model (e.g. gpt-image-1) on the tool definition:

import os
import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
)

response = client.responses.create(
    model="gpt-4o",
    input="Draw a cartoon cat wearing a top hat",
    tools=[{"type": "image_generation", "model": "gpt-image-1"}],
)

for item in response.output:
    if item.type == "image_generation_call":
        print(f"Status: {item.status}")
        if item.result:
            image_bytes = base64.b64decode(item.result)
            with open("output.png", "wb") as f:
                f.write(image_bytes)

import OpenAI from "openai";
import { writeFileSync } from "fs";

const client = new OpenAI({
    apiKey: process.env.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/v1",
});

const response = await client.responses.create({
    model: "gpt-4o",
    input: "Draw a cartoon cat wearing a top hat",
    tools: [{ type: "image_generation", model: "gpt-image-1" }],
});

for (const item of response.output) {
    if (item.type === "image_generation_call" && item.result) {
        const imageBytes = Buffer.from(item.result, "base64");
        writeFileSync("output.png", imageBytes);
    }
}

import os
import base64
from auriko import Client

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
)

response = client.responses.create(
    model="gpt-4o",
    input="Draw a cartoon cat wearing a top hat",
    tools=[{"type": "image_generation", "model": "gpt-image-1"}],
)

for item in response.output:
    if item.type == "image_generation_call":
        if item.result:
            image_bytes = base64.b64decode(item.result)
            with open("output.png", "wb") as f:
                f.write(image_bytes)

import { Client } from "@auriko/sdk";
import { writeFileSync } from "fs";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/v1",
});

const response = await client.responses.create({
    model: "gpt-4o",
    input: "Draw a cartoon cat wearing a top hat",
    tools: [{ type: "image_generation", model: "gpt-image-1" }],
});

for (const item of response.output) {
    if (item.type === "image_generation_call" && item.result) {
        const imageBytes = Buffer.from(item.result, "base64");
        writeFileSync("output.png", imageBytes);
    }
}

curl https://api.auriko.ai/v1/responses \
  -H "Authorization: Bearer $AURIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Draw a cartoon cat wearing a top hat",
    "tools": [{"type": "image_generation", "model": "gpt-image-1"}]
  }'

Specify the image model (e.g. gpt-image-1) on the image_generation tool definition, not as the top-level model. The top-level model must be a supported chat model (e.g. gpt-4o) that orchestrates the tool call. gpt-image-* models are only available through the Response API.

Edit images

Send an existing image alongside a text prompt to edit it. Only gpt-image-* models support editing. Content parts must be nested inside a user message:

response = client.responses.create(
    model="gpt-4o",
    input=[
        {"role": "user", "content": [
            {"type": "input_image", "image_url": "https://example.com/photo.png"},
            {"type": "input_text", "text": "Add sunglasses to the cat"},
        ]},
    ],
    tools=[{"type": "image_generation", "model": "gpt-image-1"}],
)

const response = await client.responses.create({
    model: "gpt-4o",
    input: [
        { role: "user", content: [
            { type: "input_image", image_url: "https://example.com/photo.png" },
            { type: "input_text", text: "Add sunglasses to the cat" },
        ]},
    ],
    tools: [{ type: "image_generation", model: "gpt-image-1" }],
});

curl https://api.auriko.ai/v1/responses \
  -H "Authorization: Bearer $AURIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [
      {"role": "user", "content": [
        {"type": "input_image", "image_url": "https://example.com/photo.png"},
        {"type": "input_text", "text": "Add sunglasses to the cat"}
      ]}
    ],
    "tools": [{"type": "image_generation", "model": "gpt-image-1"}]
  }'

Failed calls

An image_generation_call output item progresses through statuses: in_progress → generating → completed or failed. A failed call has status: "failed" and result: null:

{
  "type": "image_generation_call",
  "id": "ig_abc123",
  "status": "failed",
  "result": null
}

Understanding tool_usage

OpenAI Response API responses include a tool_usage field with per-tool consumption metrics:

Key	Fields	Description
`image_gen`	`input_tokens`, `output_tokens`, `total_tokens`, `input_tokens_details.text_tokens`, `input_tokens_details.image_tokens`, `output_tokens_details.image_tokens`	Token counts for image generation (details are nested objects)
`web_search`	`num_requests`	Number of web search requests made

The tool type in requests is image_generation, but the tool_usage response key is image_gen. Both names are OpenAI conventions.

tool_usage is only present on OpenAI Response API responses. Gemini image generation via Chat Completions reports token counts in usage.completion_tokens_details.image_tokens instead.

Supported models

API format	Main model	Image model (on tool)
Response API	`gpt-4o`, `gpt-4.1`, etc.	`gpt-image-1`, `gpt-image-1.5-2025-12-16`, `gpt-image-1-mini`
Chat Completions	`gemini-2.5-flash-image`, `gemini-3-pro-image`, `gemini-3.1-flash-image`	N/A (model handles image generation natively)

Billing

Image generation through hosted tools is billed at provider pass-through rates based on token consumption. The hosted tool cost appears:

In the dashboard request detail as Tool Cost
In the API response at routing_metadata.cost.hosted_tool_usd
In the SDK as response.routing_metadata.cost.hosted_tool_usd

Vision — analyze images in chat completions
Streaming — stream image responses chunk-by-chunk
Extensions and thinking — pass provider-specific parameters
Response API overview — feature support and format differences

Get Started

Guides

Response API

Frameworks

Integrations

Specifications

Platform

Changelog

Image generation

Prerequisites

Generate images

Response shape

Generate images with the Response API

Edit images

Failed calls

Understanding tool_usage

Supported models

Billing

​Prerequisites

​Generate images

​Response shape

​Generate images with the Response API

​Edit images

​Failed calls

​Understanding tool_usage

​Supported models

​Billing

​Related

Prerequisites

Generate images

Response shape

Generate images with the Response API

Edit images

Failed calls

Understanding tool_usage

Supported models

Billing

Related