HomeArtist Public API

1. 1

   Sign in

   Open Settings, then API.

2. 2

   Add balance

   Buy prepaid credits, or use a Luxe included allowance.

3. 3

   Create a key

   The secret is shown once. Store it in a secret manager.

4. 4

   Start a job

   POST /images/stage with the key and an Idempotency-Key.

5. 5

   Poll

   GET /jobs/{job_id} every 2 to 5 seconds until the job is completed, failed, or canceled. First-stage generation typically takes about 30 seconds.

Every request uses a bearer API key.

Authorization: Bearer hs_live_...

• Keys are scoped to one account. Revocation takes effect on the next request.
• Scopes: images:write, images:read, usage:read. New keys receive all three.
• Never put a key in browser code, a mobile app, or a public repository.

https://homeartist.ai/api/public/v1

v1 is the current contract. Additive fields may appear. Existing fields and error codes keep their meaning.

1 API unit = $0.05. Web photo credits are a separate product and are not charged here.

Luxe includes 1,000 API units per billing cycle. Unused included units do not roll over. Purchased PAYG units do not expire. Included units are consumed first, then PAYG. Failed or canceled jobs refund the original buckets.

PAYG minimum custom top-up is $5.00. Preset packs: $25 = 500 units, $50 = 1,000 units, $100 = 2,000 units.

Exceeding rate or concurrency returns 429 with Retry-After. An empty wallet returns 402 payment_required and does not call the provider.

Send an Idempotency-Key on every generation request. Max 255 characters.

Idempotency-Key: listing-8842-photo-3

• Same key, same payload: original job, no second charge.
• Same key, different payload: 409 idempotency_conflict.
• Missing header: a retry starts a second billed job.

Image jobs return 202 and a job id. Poll GET /jobs/{id} until the job is terminal. Floor plan completes inside the request (HTTP 200) with the same envelope, so a client that always polls still works.

curl -X POST https://homeartist.ai/api/public/v1/images/stage \
  -H "Authorization: Bearer hs_live_..." \
  -H "Idempotency-Key: listing-8842-photo-3" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/living-room.jpg","room_type":"living_room","style":"modern"}'

curl -X POST https://homeartist.ai/api/public/v1/images/design/automatic \
  -H "Authorization: Bearer hs_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/kitchen.jpg","room_type":"kitchen","style":"scandinavian"}'

curl -X POST https://homeartist.ai/api/public/v1/images/design/custom \
  -H "Authorization: Bearer hs_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/bathroom.jpg","room_type":"bathroom","style":"contemporary"}'

curl -X POST https://homeartist.ai/api/public/v1/images/transform \
  -H "Authorization: Bearer hs_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"operation":"natural_twilight","image_url":"https://cdn.example.com/exterior.jpg"}'

curl -X POST https://homeartist.ai/api/public/v1/images/declutter \
  -H "Authorization: Bearer hs_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/bedroom.jpg"}'

curl -X POST https://homeartist.ai/api/public/v1/images/floor-plan \
  -H "Authorization: Bearer hs_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"style":"technical","property_type":"Single-family house","total_area":2000,"area_unit":"imperial"}'

Poll every 2 to 5 seconds until status is completed, failed, or canceled. Read polls use the higher 600/minute limit.

curl https://homeartist.ai/api/public/v1/jobs/8f1c9e2a-4b31-4a0e-9a77-1c2d3e4f5a6b \
  -H "Authorization: Bearer hs_live_..."

Cancel a non-terminal job and refund reserved units:

curl -X POST https://homeartist.ai/api/public/v1/jobs/$JOB_ID/cancel \
  -H "Authorization: Bearer hs_live_..."

Cross-account ids return job_not_found. Terminal jobs return job_not_cancelable. Required scopes: images:read for GET, images:write for cancel.

Accepted job (HTTP 202):

{
  "id": "8f1c9e2a-4b31-4a0e-9a77-1c2d3e4f5a6b",
  "object": "generation_job",
  "status": "processing",
  "feature": "home_staging",
  "action": "home_staging.generate",
  "created_at": "2026-09-11T07:41:12.004Z",
  "completed_at": null,
  "result": null,
  "error": null,
  "usage": {
    "reserved_units": 16,
    "billable_units": null,
    "unit": "api_unit",
    "included_units": 16,
    "purchased_units": 0,
    "funding_source": "INCLUDED"
  },
  "request_id": "req_2f4c…"
}

Completed job (HTTP 200):

{
  "id": "8f1c9e2a-4b31-4a0e-9a77-1c2d3e4f5a6b",
  "object": "generation_job",
  "status": "completed",
  "feature": "home_staging",
  "action": "home_staging.generate",
  "created_at": "2026-09-11T07:41:12.004Z",
  "completed_at": "2026-09-11T07:41:44.118Z",
  "result": {
    "images": [
      {
        "url": "https://cdn.example.com/results/living-room.jpg",
        "width": 1536,
        "height": 1024,
        "content_type": "image/jpeg"
      }
    ]
  },
  "error": null,
  "usage": {
    "reserved_units": 16,
    "billable_units": 16,
    "unit": "api_unit",
    "included_units": 16,
    "purchased_units": 0,
    "funding_source": "INCLUDED"
  },
  "request_id": "req_2f4c…"
}

Branch on error.code, not the message.

{
  "object": "error",
  "error": {
    "code": "payment_required",
    "message": "API balance exhausted. Buy API credits to continue.",
    "request_id": "req_2f4c…"
  }
}

image_url must be a publicly reachable https URL. Private hosts, link-local addresses, http, and data URIs are rejected. Host the photo on a CDN or signed object URL we can fetch.

Scope: usage:read. Units charged: 0.

curl https://homeartist.ai/api/public/v1/usage \
  -H "Authorization: Bearer hs_live_..."

{
  "object": "usage",
  "unit": "api_unit",
  "units_used": 148,
  "included_units_remaining": 852,
  "purchased_units_remaining": 500,
  "units_remaining": 1352
}

• Store keys in a secret manager. Rotate by revoking and creating a new key.
• One key per integration. Name it after the system that holds it.
• Prefer server-to-server calls. A leaked browser key spends your wallet.
• Treat result URLs as temporary. Download and re-host them.
• Do not send user_id, webhook_url, provider, or model fields. They are ignored.

Video, Move Object, partial declutter, 360 Studio, and caller-supplied webhooks are not exposed.