Guide

Introduction

What the Roomagen API does, how it is authenticated, and what it costs.

Submit one image to one tool, get a rendered image back. There is one endpoint to learn, one unit of billing, and one error shape.

At a glance

What you can call

Five tools are available at launch: virtual staging, virtual renovation, image enhancement, day to dusk, and item removal. Each costs one image per render.

GET /v1/tools is the authoritative list — a slug that is not in it is rejected with invalid_tool. See Tools for the options each one accepts.

How a job works

POST /v1/jobs accepts the image and returns immediately with status: processing — generation runs in the background. You get the result in one of two ways:

• Poll GET /v1/jobs/{id} every 2–5 seconds. Jobs are typically ready in 20–60 seconds.
• Webhook — set webhook_url on the job and Roomagen POSTs the finished job to you.

result_urls is empty until status is completed. Download and store those images; they are served from Roomagen storage and are subject to your account's gallery retention.

Authentication

Every request carries X-Api-Key: rmg_live_…. Keys are issued in the portal and shown once, at creation time. See Authentication.

Errors

Every non-2xx response is { "error": { "code", "message", "doc_url" } }. Branch on code — messages are human-facing and may change without notice. See Errors & limits.

Billing

Cost is quoted in images, not credits: one image is the unit of work and of billing. POST /v1/jobs charges immediately and returns images_charged. A job that fails during generation is refunded automatically. See Pricing & credits.

Next step

Quickstart — create a key and render your first image.