llms.txt
Compare with other sites' llms.txt files →---
api_version: 2026-05
schema: async-job-v0.4
last_updated: 2026-10-19
---
# Runfra
> Runfra Studio turns one product photo into a full pack of marketplace-ready listing
> assets — hero images, lifestyle shots, white-background cutouts and listing copy with
> SEO — for Shopee, Amazon and Etsy sellers. Studio is built on Runfra, the team's own
> AI task-routing API for image and vision generation: submit a task (a prompt, a list
> of prompts, or an image for vision / img2img) and Runfra routes it to the right model
> and the cheapest capable backend, 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 <supabase_jwt>` (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.
## Runfra Studio
Runfra Studio is a guided e-commerce workflow layer built on top of the Runfra API:
- **Runfra API** — async image generation engine for submitting prompts and receiving generated images.
- **Runfra Studio** — a no-code product for online sellers. Upload one product photo and Studio returns a full pack of marketplace-ready assets: hero images, lifestyle/scene shots, white-background cutouts, and listing copy with SEO — built for Shopee, Amazon, and Etsy sellers. Built on the same API.
- [Runfra Studio](https://studio.runfra.com): AI product photography and listing assets for e-commerce sellers.
- [Etsy Listing Image Generator](https://runfra.com/etsy-digital-art-generator): Studio landing page for Etsy sellers — product and listing imagery.
- [Studio app](https://runfra.com/studio): Launch the workflow.
## 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).