/api/v1/images/generations

Generate images from a text prompt. The request follows OpenAI's images.generate, so the OpenAI SDKs work with the Railwail base URL. Each image is its own run, billed at the model's price.

URL

https://railwail.com/api/v1/images/generations

Key scope

images

Returns

200 with URLs · 202 if slow

Default model

flux-1-schnell

Request body#

JSON. Unknown fields are rejected with 400 validation_failed; for example aspect_ratio and seed cannot be sent here. Only prompt (and model) work for every model; the rest is used where the model has that input.

Examples#

Key in RAILWAIL_API_KEY, with the images scope (not on by default).

curl https://railwail.com/api/v1/images/generations \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-schnell",
    "prompt": "A beautiful sunset over Tokyo, cinematic"
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RAILWAIL_API_KEY"],
    base_url="https://railwail.com/api/v1",
)

image = client.images.generate(
    model="flux-1-schnell",
    prompt="A beautiful sunset over Tokyo, cinematic",
)
print(image.data[0].url)  # None if the run was still processing (HTTP 202)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.RAILWAIL_API_KEY,
  baseURL: "https://railwail.com/api/v1",
});

const image = await client.images.generate({
  model: "flux-1-schnell",
  prompt: "A beautiful sunset over Tokyo, cinematic",
});
console.log(image.data[0].url); // null if the run was still processing (HTTP 202)

import railwail from "railwail";

const rw = railwail(process.env.RAILWAIL_API_KEY);

const res = await rw.image("flux-1-schnell", "A beautiful sunset over Tokyo, cinematic");
console.log(res.data[0].url);

Response#

200: finished

Shape of the answer; values are placeholders.

{
  "created": <unix seconds>,
  "data": [
    {
      "url": "https://…/out-0.webp",
      "revised_prompt": "<your prompt, unchanged>",
      "job_id": "<uuid>",
      "status": "completed"
    }
  ]
}

202: still processing

Runs that take longer than about 85 seconds return HTTP 202 with status: "processing", url: null, a poll URL and a Location header. Fetch the result with GET /api/v1/jobs/{job_id}. The OpenAI SDKs do not raise on 202; they return url: null, so check for it.

Several images in one request

With n above 1, all images of the request are reserved and charged together: if the balance, the spend limit or the key's credit limit does not cover all of them, none runs and nothing is charged. If some images then fail at the provider, the answer is still 200 (or 202) with the delivered images in data and the failed ones in errors, each with its job_id and code generation_failed; failed images are refunded.

Models you can call here#

Live from the catalog: image models that run through this endpoint with a text prompt, with the price as charged. Models that need an input image (editing, upscaling, background removal) run from their model pages.

Errors#

All codes: Error codes. Rate-limit headers come with the 200 and error answers, not with a 202.