Authentication

Create a key in the app under Account → API keys. The key is shown once and stored only as a hash, so keep it somewhere safe — if you lose it, revoke it and create another. Send it as a bearer token, and never from a browser or anywhere a customer could read it.

Authorization: Bearer ark_your_key_here

Start a render

POST /api/v1/renders — image inputs are passed as a public imageUrl we download; JPG, PNG, or WebP up to 10MB. Tools that need a second file — inpainting, AI eraser and style transfer — and video and 3D are not in v1.

curl https://www.archifyai.com/api/v1/renders \
  -H "Authorization: Bearer ark_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "exterior",
    "prompt": "Warm limestone facade, bronze window frames, evening light.",
    "imageUrl": "https://example.com/house.jpg",
    "options": { "structure_lock": "on" }
  }'

# 202 Accepted
{ "ok": true, "id": "abc123", "status": "processing", "tool": "exterior" }

Check a render

GET /api/v1/renders/{id} — poll every few seconds. Most image runs finish in well under a minute.

curl https://www.archifyai.com/api/v1/renders/abc123 \
  -H "Authorization: Bearer ark_your_key_here"

{ "ok": true, "id": "abc123", "status": "succeeded",
  "tool": "exterior", "outputs": ["https://.../0.png"] }

Errors and credits

• Every error returns { "ok": false, "error": { "code", "message" } }.
• 402 insufficient_credits — top up in the app. 403 plan_required — the API needs a Studio or multi-seat plan. 401 unauthorized — missing, malformed, or revoked key.
• Credits are reserved when a run starts and refunded automatically if it fails or returns nothing.
• Rate limits: 30 render submissions and 240 status checks per minute, per key. Exceeding one returns 429 rate_limited with a Retry-After header.
• API runs appear in your normal History alongside everything made in the app.