Reference

Quickstart

Create a key, send your first job, and read the result — in four steps.

Four steps from nothing to a rendered image. The panel beside this page is the request you are about to send.

1. Get an API key

Create a key in the developer portal. Your first key comes with 50 free images, enough to build and test an integration.

The key is shown once, at creation time — Roomagen stores only a hash of it. Copy it into your secret store before closing the dialog. If you lose it, revoke it and create another.

2. Send your first job

POST /v1/jobs takes one image and one tool slug, charges immediately, and returns before generation finishes.

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: rmg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8842-image-1" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://example.com/empty-living-room.jpg",
    "options": { "style": "scandinavian", "roomType": "living-room" }
  }'

{
  "job_id": "3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f",
  "status": "processing",
  "images_charged": 1
}

Two things to get right:

• Provide exactly one of image_url or image_base64. Neither or both is invalid_image.
• virtual-staging requires options.style. A staging request without it is rejected with invalid_request. The full list of styles is on the virtual staging page.

The response status is always processing. images_charged tells you what the job cost.

3. Poll for the result

Poll GET /v1/jobs/{id} every 2–5 seconds. Jobs are typically ready in 20–60 seconds.

curl https://api.roomagen.com/api/v1/jobs/3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f \
  -H "X-Api-Key: rmg_live_YOUR_KEY"

{
  "job_id": "3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f",
  "tool": "virtual-staging",
  "status": "completed",
  "images_charged": 1,
  "result_urls": [
    "https://api.roomagen.com/api/uploads/9c2f7a10-render.jpg"
  ],
  "error": null,
  "created_at": "2026-08-24T09:14:02.114Z",
  "completed_at": "2026-08-24T09:14:39.902Z",
  "processing_ms": 37788
}

status moves through three values:

completed and failed are terminal — stop polling on either. A job that fails during generation is refunded automatically; images_charged still reports what was charged when the job was created, so treat it as the charge rather than the final balance impact.

4. Or skip polling

Set webhook_url on the job and Roomagen POSTs the finished job to you instead. Deliveries are signed, retried on failure, and delivered at least once — see Webhooks for the contract and a signature-verification snippet.

Next step

Authentication — key format, key hygiene, and what a rejected key looks like.