Images

Takes a model and a prompt and returns base64 images. The format is OpenRouter's Images API, not OpenAI's images/generations. Send the key as Authorization: Bearer sk-df-... or x-api-key.

Find image models at /models?type=image.

Example

curl https://deference.si/v1/images \
  -H "Authorization: Bearer $DEFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/recraft-v4.1-flash",
    "prompt": "A lighthouse on a cliff at dawn, flat illustration",
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 --decode > lighthouse.png

import base64
import os
import requests

response = requests.post(
    "https://deference.si/v1/images",
    headers={"Authorization": f"Bearer {os.environ['DEFERENCE_API_KEY']}"},
    json={
        "model": "recraft/recraft-v4.1-flash",
        "prompt": "A lighthouse on a cliff at dawn, flat illustration",
        "n": 1,
    },
    timeout=180,
)
response.raise_for_status()
for index, image in enumerate(response.json()["data"]):
    with open(f"image-{index}.png", "wb") as file:
        file.write(base64.b64decode(image["b64_json"]))

import { writeFile } from "node:fs/promises";

const response = await fetch("https://deference.si/v1/images", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DEFERENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "recraft/recraft-v4.1-flash",
    prompt: "A lighthouse on a cliff at dawn, flat illustration",
    n: 1,
  }),
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) throw new Error(await response.text());

const { data } = await response.json();
for (const [index, image] of data.entries()) {
  await writeFile(`image-${index}.png`, Buffer.from(image.b64_json, "base64"));
}

Request body

modelstringRequired

An image model id.

promptstringRequired

What to draw.

ninteger

How many images, a whole number from 1 to 10. Defaults to 1. Any other value returns 400 invalid_parameter.

aspect_ratiostring

For example 16:9. Accepted values depend on the model.

resolutionstring

For example 1K or 2K, on models that offer sizes.

sizestring

Pixel size, such as 1024x1024, on models that take one.

qualitystring

Quality level, on models that offer it.

output_formatstring

png, jpeg or webp, on models that offer a choice.

input_referencesarray

Reference images, on models that accept them.

streamboolean

Return server-sent events. Only OpenAI image models stream.

Other fields pass through to the provider, and fields a model does not support are ignored. models, route, provider and plugins that add a fee return 400 unsupported_parameter. Deference replaces user with an account tag.

Response

{
  "created": 1760000000,
  "data": [{ "b64_json": "iVBORw0KGgo...", "media_type": "image/png" }],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "cost": 0.007
  }
}

b64_json is shortened here. media_type tells you the file type to save. usage.cost is the provider's cost in dollars, before Deference's platform fee. What you are charged is in Activity, and on non-streamed responses in x-deference-cost, in micro-dollars (1,000,000 is $1).

Streaming

On models that stream, stream: true returns image_generation.partial_image events as the image forms, then image_generation.completed with the final image and usage, then [DONE]. An error event can replace either.

Billing

• Each requested image holds at least $0.20, or more when the model's image price is higher. If the hold does not fit, the request returns 402: ask for fewer images or add credit.
• A success is charged the provider's cost plus the 5% platform fee, and the charge is final at once. A success that reports no cost is charged the whole hold.
• A failed generation is charged only what the provider reports for it, usually nothing. A timeout is charged the whole hold, because the provider may still have generated the image.
• Free credit never pays for images. An account with only free credit gets 402 free_credit_not_eligible.

Limits

Generation can take over a minute, so set a client timeout of at least 180 seconds.

Also from chat

Some chat models, such as Gemini and GPT image models, generate images inside a chat reply. Send modalities: ["image", "text"] to Chat completions. Image-only models, such as Recraft and FLUX, need this endpoint.