The EasyRoomAI API

Create a key in Settings → API, export it as EASYROOMAI_API_KEY, then create a task and poll it.

# 1. Create a task (returns 202 and an id)
curl https://www.easyroomai.com/api/v1/generations \
  -H "Authorization: Bearer $EASYROOMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "redesign",
    "image": {
      "url": "https://example.com/my-living-room.jpg"
    },
    "style": "japandi",
    "room_type": "living_room"
  }'

# 2. Poll until status is "succeeded" or "failed"
curl https://www.easyroomai.com/api/v1/generations/gen_… \
  -H "Authorization: Bearer $EASYROOMAI_API_KEY"

import { randomUUID } from "node:crypto";

const API = "https://www.easyroomai.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.EASYROOMAI_API_KEY}`,
  "Content-Type": "application/json",
};

async function call(path, options = {}) {
  const res = await fetch(`${API}${path}`, {
    ...options,
    headers: { ...headers, ...options.headers },
  });
  const body = await res.json();
  if (!res.ok) {
    const { code, message, request_id } = body.error;
    throw new Error(`${code}: ${message} (${request_id})`);
  }
  return body;
}

// 1. Create the task. The Idempotency-Key makes a retry safe.
const created = await call("/generations", {
  method: "POST",
  headers: { "Idempotency-Key": randomUUID() },
  body: JSON.stringify({
    "type": "redesign",
    "image": {
      "url": "https://example.com/my-living-room.jpg"
    },
    "style": "japandi",
    "room_type": "living_room"
  }),
});

// 2. Poll until it finishes.
let generation = created;
while (generation.status === "pending") {
  await new Promise((resolve) => setTimeout(resolve, 4000));
  generation = await call(`/generations/${created.id}`);
}

console.log(generation.status, generation.output?.url);

import os
import time
import uuid

import requests

API = "https://www.easyroomai.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['EASYROOMAI_API_KEY']}"}


def call(method, path, **kwargs):
    res = requests.request(method, API + path, headers={**HEADERS, **kwargs.pop("headers", {})}, **kwargs)
    body = res.json()
    if not res.ok:
        err = body["error"]
        raise RuntimeError(f"{err['code']}: {err['message']} ({err['request_id']})")
    return body


# 1. Create the task. The Idempotency-Key makes a retry safe.
created = call(
    "POST",
    "/generations",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={
      "type": "redesign",
      "image": {
        "url": "https://example.com/my-living-room.jpg"
      },
      "style": "japandi",
      "room_type": "living_room"
    },
)

# 2. Poll until it finishes.
generation = created
while generation["status"] == "pending":
    time.sleep(4)
    generation = call("GET", f"/generations/{created['id']}")

print(generation["status"], generation.get("output", {}).get("url"))

A create call returns 202 straight away with the task id. The result URL appears on the task once status is succeeded.

Base URL: https://www.easyroomai.com/api/v1. Send your key on every request:

Authorization: Bearer rai_live_…

• A key is shown once, when you create it. We store only a hash, so a lost key cannot be recovered — revoke it and create another.
• You can have up to 5 active keys, for example one per environment. Revoking a key takes effect immediately.
• Keep keys on your server. The API does not allow browser (CORS) calls, so a key in front-end code is a leaked key.
• If your Ultra subscription lapses the keys stop working (403 subscription_required) and resume when it is active again.

1. POST /generations checks your request, charges the credits and starts the task. You get 202 and an id like gen_….
2. GET /generations/{id} returns pending, then succeeded with output.url, or failed.

Most tasks finish in a minute or two; 360° panoramas can take longer. Poll every 3–5 seconds. A task that is still pending after an hour is marked failed and refunded automatically. There are no webhooks yet.

POST /generations with a JSON body. Every request has a type; the other fields depend on it (see below). Fields we do not recognise are rejected with 400 rather than ignored, so a typo never silently changes what you are charged for.

Valid style, room_type and subject ids come from GET /pricing, so you never have to hard-code them.

• Give either { "url": "https://…" } or { "base64": "…" } (plain base64 or a data: URI), never both.
• JPEG, PNG or WebP, up to 15 MB, 40 megapixels, shortest side at least 256 px. Animated images are rejected.
• URLs must be public https on port 443. We fetch them from our servers, follow at most 3 redirects, and give up after 10 seconds. Private, loopback and link-local addresses are refused.
• The request body is limited to about 22 MB, so a single image plus a mask fits as base64.

Masks

• PNG with the same aspect ratio as the image (3% tolerance). It does not have to be the same pixel size.
• Transparent pixels (alpha below 128) mark the area to change; opaque pixels stay as they are.
• A fully opaque mask selects nothing and is rejected with empty_mask.

Image failures come back as 400 invalid_image with a details.reason such as unsupported_format, too_large, too_small, too_many_pixels, animated, blocked_address, unreachable or not_equirectangular.

GET /generations/{id} returns the task. You can only read your own tasks; anything else is a 404.

{
  "id": "gen_3f2b8c1e-9d4a-4e6b-8f10-a1b2c3d4e5f6",
  "type": "redesign",
  "status": "succeeded",
  "credits_charged": 10,
  "created_at": "2026-10-09T12:00:00.000Z",
  "completed_at": "2026-10-09T12:01:05.000Z",
  "metadata": { "listing": "A-1042" },
  "output": { "url": "https://cdn.easyroomai.com/…" }
}

{
  "id": "gen_…",
  "status": "failed",
  "error": { "code": "generation_failed", "message": "The image could not be generated." },
  "refunded": true
}

GET /generations?limit=20&cursor=… lists your API tasks, newest first, as { data, has_more, next_cursor } (limit 1–50). GET /credits returns your balance.

API requests spend the same credit balance as the web tools, at API rates. Credits are charged when the task is created and returned automatically if it fails or times out.

Only the standard quality tier is available through the API. GET /pricing returns this table, the accepted options and the limits as JSON.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 or 503 includes Retry-After. Each response also has an X-Request-Id — quote it if you contact support. The platform can briefly refuse new tasks when it is at capacity (503 capacity_exceeded); you are not charged.

Send an Idempotency-Key header (1–64 characters of letters, digits, _ - : .) on create calls so a network retry never double-charges.

• Same key and same body: you get the original task back with 200 and Idempotent-Replayed: true.
• Same key, different body: 422 idempotency_key_reuse.
• Same key while the first call is still being created: 409 request_in_progress — retry shortly.
• A call that failed on our side (502) does not hold the key, so retrying with it really retries.
• Keys are remembered for 24 hours.

Every error has the same shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits.",
    "request_id": "req_9f8e7d6c5b4a3210",
    "details": { "required": 10, "available": 4 }
  }
}

• 2026-10 — v1: six generation types, polling, idempotency, credits and pricing endpoints.

Use of the API is covered by our Terms of Service (section 14, API access). Questions or a use case we should know about? Write to [email protected].