--- api_version: 2026-05 schema: async-job-v0.4 last_updated: 2026-05-03 --- # Runfra > Async batch image generation API. Submit a prompt (or a list of prompts), Runfra > generates candidates in parallel across distributed GPU workers, scores and filters > them, and returns the best result. Plain HTTP, no SDK required. Runfra is an async-job API: every request creates a `job_id`, you poll `/v1/jobs/{id}/result` until it returns 200. Typical generation time is 10–30 seconds per task. The platform supports text-to-image and (with a Bearer JWT) image-to-image with a reference upload. - **Base URL:** `https://api.runfra.com` - **API version label:** `0.4` (response shape) · `2026-05` (this docs snapshot) - **Auth:** `X-API-Key: rfa_…` (production, server-to-server) or `Authorization: Bearer ` (testing). `/v1/me/*` and image-upload routes require Bearer JWT. - **Pricing model:** credit-based — cost depends on model and resolution; refunded automatically on platform failure. ## API Reference - [Full API reference (HTML)](https://runfra.com/docs/api): Endpoints, request/response shapes, parameters, error codes. - [Full API reference (Markdown for LLMs)](https://runfra.com/llms-full.txt): Same content, plain text — preferred for AI agents. - [Health check](https://api.runfra.com/healthz): Returns `{"status":"ok"}` when the API is reachable. ## Quickstart - [Create a job (POST /v1/jobs)](https://runfra.com/docs/api#create-job): Submit a single prompt or a list of prompts. Returns `job_id` + `seeds[]`. - [Poll a job (GET /v1/jobs/{id}/result)](https://runfra.com/docs/api#polling): 202 while running, 200 when terminal. Read `best_result_url` (single-prompt) or `items[].result_url` (multi-prompt). - [Full job object (GET /v1/jobs/{id})](https://runfra.com/docs/api#result): Includes `selection_finalized`, `preview_best_url`, `task_progress`. Heavier than `/result`; use for live progress UIs. ## Models Three models are available. Pass the name (or any alias) in `model_name`. - **`stable-diffusion-xl-base-1.0`** (default) — aliases: `sdxl`, `sdxl-base`, `stable-diffusion-xl`. Photorealistic and general-purpose. Default 20 steps. **1 / 2 / 3 credits** per image at ≤512 / ≤768 / >768 px. - **`flux-schnell`** — aliases: `flux`, `flux_schnell`. Distilled flow-matching model. Default 4 steps; guidance forced to 0.0; **negative prompts silently ignored**. **2 / 3 / 4 credits** per image. - **`flux-dev`** (sold as **RunFra Pro**) — aliases: `flux_dev`. Higher-fidelity FLUX variant. Default 20 steps, guidance 3.5; **negative prompts silently ignored**. **5 / 9 / 14 credits** per image. Total job cost = `credits_per_image × effective_batch`. Single mode: `effective_batch = batch_size`. Multi mode: `effective_batch = items.length`. Cost is frozen at job creation; refunds return the exact stored amount. ## Authentication and credits - [Dashboard → API Keys](https://runfra.com/dashboard/api-keys): Create, rotate, revoke `customer`-type keys (the only self-serve type). The raw key is shown **once** — save it immediately. - [GET /v1/me/credits](https://runfra.com/docs/api): Current credit balance for a JWT-authenticated user. - [POST /v1/billing/checkout](https://runfra.com/docs/api): Stripe Checkout for credit packs — `starter` (Starter Batch: $5 / 600 cr), `creator` (Creator Batch: $12 / 1,600 cr), `studio` (Pro Batch: $24 / 3,600 cr). New accounts are seeded with **100 credits**. The number of images that grants depends on model and resolution — at SDXL 1024×1024 (3 cr/image) that is ~33 images; at FLUX Schnell 1024×1024 (4 cr/image) it is 25; at RunFra Pro 1024×1024 (14 cr/image) it is ~7. ## Pricing Runfra uses prepaid credits shared across Dashboard, API, n8n, and MCP. There is no separate API surcharge. Credit packs (one-time purchase, no subscription, credits never expire): - **Starter Batch:** $5 → 600 credits, up to ~200 SDXL 1024px images (~$0.025/image) - **Creator Batch:** $12 → 1,600 credits, up to ~533 SDXL 1024px images (~$0.0225/image) - **Pro Batch:** $24 → 3,600 credits, up to ~1,200 SDXL 1024px images (~$0.020/image) Generation cost = `image_count × model_resolution_rate` (see model rate table above). Effective per-image price depends on credit pack, model, resolution, and batch size — there is no fixed USD-per-image rate. ## Image-to-image (img2img) - **Bearer JWT only** — API keys and anonymous callers are rejected with 403. - **SDXL only** regardless of `model_name`. - **Output capped at 768×768 px** (each side 384–768, multiples of 64). - Two-step flow: upload a reference image to `POST /v1/uploads/input-image`, then submit a job with `pipeline_mode="img2img"` + `input_storage_key`. ## Limits and policies - **Rate limits:** `POST /v1/jobs` 20 req/min/identity; `GET /v1/jobs/{id}/result` 120 req/min; identity = API key → JWT sub → IP. - **Content policy:** prompts are screened at submission. Rejected requests consume **no credits**. Always blocked: CSAM, sexual violence, explicit pornographic content, graphic gore. - **Image retention:** generated files are kept for **30 days** after job creation. Job metadata (prompt, status, credits) is retained indefinitely. - **Quality filtering:** every candidate passes a heuristic + CLIP-alignment gate. Best-effort delivery (`is_best_effort: true`) returns the best available image even when no candidate passed; credits are not refunded for best-effort. ## Optional - [Pricing details](https://runfra.com/pricing): Credit packs and live model rates. - [Playground (browser)](https://runfra.com/playground): Web UI for trying prompts without writing code. - [Live health endpoint](https://api.runfra.com/healthz): JSON `{"status":"ok"}` smoke check. ## What Runfra is NOT To save AI agents from incorrect assumptions: - **Not OpenAI-compatible.** There is no `/v1/images/generations` endpoint or OpenAI-shaped response. Use `/v1/jobs` + polling. - **No custom LoRA upload.** The platform does not accept user-supplied weights. - **No fixed per-image USD price.** Cost is credits × model × resolution; do not assume a flat per-image dollar rate. - **No webhooks.** Job completion is delivered via polling (or, for signed-in users, an optional `notify_on_complete` email).