{"openapi":"3.1.0","info":{"title":"HomeArtist Public API","version":"1.0.0","description":"Programmatic access to HomeArtist image generation. Any authenticated account can buy prepaid API credits; Luxe includes 1,000 units per billing cycle. Authenticate with a customer API key created in Settings → API."},"servers":[{"url":"https://dev.homeartist.ai/api/public/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer hs_live_..."}},"schemas":{"GenerationJob":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}},"Error":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}},"security":[{"bearerAuth":[]}],"paths":{"/images/stage":{"post":{"summary":"Virtually stage a room photograph","description":"Furnishes and styles a room while preserving its architecture and camera.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opaque key, unique per logical request. Replaying it returns the original job instead of starting a second generation; reusing it with a different payload returns 409 idempotency_conflict."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url"],"properties":{"image_url":{"type":"string","format":"uri","description":"Publicly reachable https URL of the source photograph."},"room_type":{"type":"string","example":"living_room"},"style":{"type":"string","example":"modern"},"prompt":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Job already terminal (idempotent replay, or a synchronously-completing action).","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job accepted and queued.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"invalid_request / invalid_source_image / unsupported_operation","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"401":{"description":"invalid_api_key / api_key_revoked / api_key_expired","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"402":{"description":"payment_required / api_usage_exhausted","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"403":{"description":"api_access_required / insufficient_scope","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"429":{"description":"rate_limit_exceeded / concurrency_limit_exceeded / usage_limit_exceeded","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"503":{"description":"provider_unavailable / service_unavailable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/images/design/automatic":{"post":{"summary":"Full-room redesign from a style","description":"Refinishes surfaces and furnishes the room completely in the requested style.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opaque key, unique per logical request. Replaying it returns the original job instead of starting a second generation; reusing it with a different payload returns 409 idempotency_conflict."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url","room_type","style"],"properties":{"image_url":{"type":"string","format":"uri","description":"Publicly reachable https URL of the source photograph."},"room_type":{"type":"string"},"style":{"type":"string"},"color_palette":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Job already terminal (idempotent replay, or a synchronously-completing action).","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job accepted and queued.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"invalid_request / invalid_source_image / unsupported_operation","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"401":{"description":"invalid_api_key / api_key_revoked / api_key_expired","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"402":{"description":"payment_required / api_usage_exhausted","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"403":{"description":"api_access_required / insufficient_scope","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"429":{"description":"rate_limit_exceeded / concurrency_limit_exceeded / usage_limit_exceeded","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"503":{"description":"provider_unavailable / service_unavailable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/images/design/custom":{"post":{"summary":"Redesign with per-surface choices","description":"Applies explicit finish, colour and note choices to named surfaces.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opaque key, unique per logical request. Replaying it returns the original job instead of starting a second generation; reusing it with a different payload returns 409 idempotency_conflict."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url","room_type","style"],"properties":{"image_url":{"type":"string","format":"uri","description":"Publicly reachable https URL of the source photograph."},"room_type":{"type":"string"},"style":{"type":"string"},"prompt":{"type":"string","maxLength":2000},"elements":{"type":"object","description":"Map of surface name to { finish, color, note }. Supported surfaces: wall, floor, ceiling, cabinet, countertop, lighting, ground, garden, fence, pool, patio, pathway.","additionalProperties":{"type":"object","properties":{"finish":{"type":"string","maxLength":64},"color":{"type":"string","maxLength":32},"note":{"type":"string","maxLength":300}}}}}}}}},"responses":{"200":{"description":"Job already terminal (idempotent replay, or a synchronously-completing action).","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job accepted and queued.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"invalid_request / invalid_source_image / unsupported_operation","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"401":{"description":"invalid_api_key / api_key_revoked / api_key_expired","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"402":{"description":"payment_required / api_usage_exhausted","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"403":{"description":"api_access_required / insufficient_scope","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"429":{"description":"rate_limit_exceeded / concurrency_limit_exceeded / usage_limit_exceeded","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"503":{"description":"provider_unavailable / service_unavailable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/images/transform":{"post":{"summary":"Apply a single-image transform","description":"Allow-listed transforms only. `operation` is a product concept, not a model id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opaque key, unique per logical request. Replaying it returns the original job instead of starting a second generation; reusing it with a different payload returns 409 idempotency_conflict."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operation","image_url"],"properties":{"operation":{"type":"string","enum":["changing_seasons","rain_to_shine","natural_twilight","virtual_twilight","add_pool_water","pool_enhancement","lawn_replacement","night_to_day","add_furniture","sketch_to_render","two_d_to_three_d"]},"image_url":{"type":"string","format":"uri","description":"Publicly reachable https URL of the source photograph."},"options":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"season":{"type":"string","enum":["spring","summer","fall","winter"]},"camera_angle":{"type":"string","enum":["isometric","topdown"]},"render_style":{"type":"string","enum":["photorealistic","watercolor","sketch","3d-render"]}}}}}}}},"responses":{"200":{"description":"Job already terminal (idempotent replay, or a synchronously-completing action).","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job accepted and queued.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"invalid_request / invalid_source_image / unsupported_operation","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"401":{"description":"invalid_api_key / api_key_revoked / api_key_expired","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"402":{"description":"payment_required / api_usage_exhausted","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"403":{"description":"api_access_required / insufficient_scope","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"429":{"description":"rate_limit_exceeded / concurrency_limit_exceeded / usage_limit_exceeded","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"503":{"description":"provider_unavailable / service_unavailable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/images/declutter":{"post":{"summary":"Remove clutter from a room photograph","description":"Full-room declutter. Mask-driven partial variants are not part of v1.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opaque key, unique per logical request. Replaying it returns the original job instead of starting a second generation; reusing it with a different payload returns 409 idempotency_conflict."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url"],"properties":{"image_url":{"type":"string","format":"uri","description":"Publicly reachable https URL of the source photograph."}}}}}},"responses":{"200":{"description":"Job already terminal (idempotent replay, or a synchronously-completing action).","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job accepted and queued.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"invalid_request / invalid_source_image / unsupported_operation","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"401":{"description":"invalid_api_key / api_key_revoked / api_key_expired","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"402":{"description":"payment_required / api_usage_exhausted","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"403":{"description":"api_access_required / insufficient_scope","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"429":{"description":"rate_limit_exceeded / concurrency_limit_exceeded / usage_limit_exceeded","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"503":{"description":"provider_unavailable / service_unavailable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/images/floor-plan":{"post":{"summary":"Generate a floor plan","description":"Text-to-image floor plan. Completes inside the request, so the returned job is already terminal.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opaque key, unique per logical request. Replaying it returns the original job instead of starting a second generation; reusing it with a different payload returns 409 idempotency_conflict."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["style","property_type","total_area","area_unit"],"properties":{"style":{"type":"string","enum":["technical","perspective","isometric"]},"property_type":{"type":"string","maxLength":120},"total_area":{"type":"integer","minimum":100,"maximum":100000},"area_unit":{"type":"string","enum":["metric","imperial"]},"floors":{"type":"integer","minimum":1,"maximum":4,"default":1},"bedrooms":{"type":"integer","minimum":0,"maximum":12},"bathrooms":{"type":"integer","minimum":0,"maximum":12},"kitchens":{"type":"integer","minimum":0,"maximum":12},"living_rooms":{"type":"integer","minimum":0,"maximum":12},"dining_rooms":{"type":"integer","minimum":0,"maximum":12},"include_garage":{"type":"boolean","default":false},"additional_details":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"Job already terminal (idempotent replay, or a synchronously-completing action).","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job accepted and queued.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"invalid_request / invalid_source_image / unsupported_operation","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"401":{"description":"invalid_api_key / api_key_revoked / api_key_expired","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"402":{"description":"payment_required / api_usage_exhausted","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"403":{"description":"api_access_required / insufficient_scope","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"429":{"description":"rate_limit_exceeded / concurrency_limit_exceeded / usage_limit_exceeded","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"503":{"description":"provider_unavailable / service_unavailable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/jobs/{job_id}":{"get":{"summary":"Fetch a job","description":"Poll until status is completed, failed or canceled. Only jobs owned by the authenticated account are visible.","security":[{"bearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Terminal job.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"202":{"description":"Job still running.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"404":{"description":"job_not_found","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/jobs/{job_id}/cancel":{"post":{"summary":"Cancel a job","description":"Stops delivery and releases the reserved units. Provider work already in flight may still finish; the result is not returned.","security":[{"bearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job canceled.","content":{"application/json":{"schema":{"type":"object","required":["id","object","status","feature","action","created_at","usage","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["generation_job"]},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"]},"feature":{"type":"string"},"action":{"type":"string","enum":["home_staging.generate","home_design.generate_automatic","home_design.generate_custom","image_transform.apply","declutter.full","floor_plan.generate"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]}}}}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"usage":{"type":"object","properties":{"reserved_units":{"type":"integer"},"billable_units":{"type":["integer","null"]},"unit":{"type":"string","enum":["api_unit"]},"included_units":{"type":"integer"},"purchased_units":{"type":"integer"},"funding_source":{"type":["string","null"]}}},"request_id":{"type":"string"}}}}}},"404":{"description":"job_not_found","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"409":{"description":"job_not_cancelable","content":{"application/json":{"schema":{"type":"object","required":["object","error"],"properties":{"object":{"type":"string","enum":["error"]},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","api_access_required","insufficient_scope","payment_required","api_usage_exhausted","insufficient_credits","usage_limit_exceeded","rate_limit_exceeded","concurrency_limit_exceeded","invalid_request","unsupported_operation","invalid_source_image","idempotency_conflict","job_not_found","job_not_cancelable","provider_unavailable","provider_rejected","generation_failed","service_unavailable","not_enabled"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}},"/usage":{"get":{"summary":"Current-period usage","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage for the current calendar month.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"unit":{"type":"string","enum":["api_unit"]},"units_used":{"type":"integer"},"included_units_remaining":{"type":"integer"},"purchased_units_remaining":{"type":"integer"},"units_remaining":{"type":"integer"},"requests":{"type":"integer"},"by_feature":{"type":"object"}}}}}}}}}}}