Sofabrain API

API Documentation

Repo-owned reference for authentication, billing semantics, recipes, request bodies, response contracts, and compatibility notes across generally available and limited-preview v1 APIs. Only the endpoints listed here are part of the public v1 contract; authenticated product-internal routes are excluded.

RecipesEndpoint Reference

Production base URL

https://sofabrain.com/api/v1

13

Endpoints

4

Recipes

v1

API

Authentication

API key header

Send your key on every request. Keep keys server-side and avoid logging request headers.

x-api-key: $SOFABRAIN_API_KEY

Responses

Two compatible shapes

Legacy job routes keep their original response bodies. Media, multi-view, and tools use the stable v1 envelope.

legacyv1 envelope

Billing

Quota plus credits

Generation POSTs consume one API quota unit. Media generation also charges the endpoint-specific amount shown below. Reads, delete, and multi-view redo do not consume quota or credits.

quotacredits

Availability

Check the endpoint badge

Generally available routes can be integrated now. Limited preview routes may return 404 until SofaBrain enables the capability for the deployment.

Generally availableLimited preview

Stable media envelope

Parse one response shape

Media, multi-view, and tools responses always include these top-level fields. On failure, result is null and error contains a machine-readable code plus a message.

{
  "job_id": "job-id-or-null",
  "status": "processing | completed | failed",
  "result": {},
  "error": null,
  "credits_charged": 2,
  "timestamps": {
    "created_at": "ISO-8601-or-null",
    "updated_at": "ISO-8601-or-null",
    "completed_at": null
  }
}

credits_charged semantics

null
No media debit for this request, including status reads.
0
Free operation or a completed compensating refund.
1+
Credits retained for the generation request.

Common HTTP failures

400 invalid parameters, 401 missing key, 402 insufficient credits, 403 invalid key, plan, or quota denial, 404 missing or unavailable preview route, 429 rate limit, 500 internal failure, and 502 provider failure.

Recipes

Common API workflows

Start from these production-shaped examples, then jump into the exact endpoint reference below.

Reference

Stage one photo and poll the result

Use the compatibility endpoint when you need the broadest current production support.

POST/api/v1/jobGET/api/v1/jobs/{jobSource}
  1. 1Create a redesign job with source_url, room_type, style, and redesign_type.
  2. 2Store the returned jobId.
  3. 3Poll /api/v1/jobs/{jobSource} until status is completed or failed.
curl -X POST "https://sofabrain.com/api/v1/job" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SOFABRAIN_API_KEY" \
  -d '{
    "source_url": "https://example.com/room.jpg",
    "room_type": "Living Room",
    "style": "minimalist",
    "redesign_type": "staging",
    "environment": "interior"
  }'

Create a same-room multi-view set

Limited preview for listings photographed from multiple angles where furniture consistency matters.

POST/api/v1/multiviewGET/api/v1/multiview?render_set_id={render_set_id}POST/api/v1/multiview/redo
  1. 1Submit one anchor URL and one to three additional same-room view URLs.
  2. 2Poll the render_set_id status endpoint.
  3. 3Use redo on a sibling view when a generated angle needs another attempt.
curl -X POST "https://sofabrain.com/api/v1/multiview" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SOFABRAIN_API_KEY" \
  -d '{
    "source_url": "https://example.com/living-room-a.jpg",
    "additional_view_urls": [
      "https://example.com/living-room-b.jpg",
      "https://example.com/living-room-c.jpg"
    ],
    "room_type": "Living Room",
    "style": "modern"
  }'

Repair, then upscale an image

Chain media endpoints when you need a cleaned visual and a higher-resolution final asset.

POST/api/v1/inpaintPOST/api/v1/upscale
  1. 1Run /inpaint with a mask URL and the edit intent.
  2. 2Take the first output_urls item from the completed response.
  3. 3Send that URL to /upscale for the delivery-quality asset.
curl -X POST "https://sofabrain.com/api/v1/inpaint" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SOFABRAIN_API_KEY" \
  -d '{
    "submitted_url": "https://example.com/room.jpg",
    "mask_url": "https://example.com/mask.png",
    "inpainting_type": "general",
    "render_type": "redecorate"
  }'

Turn listing media into copy

Generate property description copy through the limited-preview tools API.

POST/api/v1/tools/property-description
  1. 1Send listing images and structured property data.
  2. 2Use the returned description directly in your listing workflow.
  3. 3Store listing_id if you need to connect the generated copy to later jobs.
curl -X POST "https://sofabrain.com/api/v1/tools/property-description" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SOFABRAIN_API_KEY" \
  -d '{
    "images": ["data:image/jpeg;base64,..."],
    "property_data": {
      "address": "123 Main St",
      "property_type": "house",
      "price": 500000
    }
  }'

Webhook contract preview

Signed customer callbacks are not generally enabled

The repository defines a preview contract with `api_version: v1`, `job.completed` and `job.failed` events, and HMAC signatures in `X-SofaBrain-Signature`. Registration and delivery are not generally available yet; coordinate an integration with SofaBrain before depending on callbacks. The signature input is `timestamp.payload`, with the timestamp in `X-SofaBrain-Timestamp`.

Reference

Endpoint Reference

V1 endpoints exposed by this repository. Availability badges distinguish generally available contracts from limited previews that require enablement.

Design jobs

Create, list, and poll the compatibility-preserved redesign API.

POSTGenerally available/api/v1/job

Create design transformation

Create an async redesign, staging, declutter, render, or redecorate job from a source image.

Billing

Consumes one API quota unit. This legacy endpoint does not use the media credit envelope.

Authentication
x-api-key
Contract
Legacy-compatible response shape

Compatibility notes

  • The endpoint works with or without a trailing slash.
  • intensity is optional and defaults to 0.6.
  • Display labels such as Staging, Furniture Staging, and Empty Room are normalized into API values.
  • redesign_type also accepts color_change. environment accepts interior, exterior, or commercial.
  • fast is optional. true requests one output; the default output count depends on the API rate-limit plan.

Request

{
  "source_url": "https://example.com/room.jpg",
  "room_type": "Living Room",
  "style": "minimalist",
  "redesign_type": "color_change",
  "intensity": 0.6,
  "color": "Earthy Neutrals",
  "environment": "interior",
  "inspiration_image": "https://example.com/inspiration.jpg",
  "mask_prompt": "walls and cabinetry",
  "fast": false
}

Response

{
  "jobId": "job_6789abcd"
}
GETGenerally available/api/v1/jobs

List jobs

Retrieve redesign jobs grouped by job source for the API key owner.

Billing

Read-only. No credit or quota charge.

Authentication
x-api-key
Contract
Legacy-compatible response shape

Response

{
  "data": [
    {
      "id": "job_6789abcd",
      "style": "minimalist",
      "room_type": "Living Room",
      "intensity": 0.6,
      "color": "Earthy Neutrals",
      "output_urls": [
        "https://cdn.example/render-1.jpg"
      ]
    }
  ]
}
GETGenerally available/api/v1/jobs/{jobSource}

Get redesign job status

Poll a legacy redesign job until the grouped job source is completed or failed.

Billing

Read-only. No credit or quota charge.

Authentication
x-api-key
Contract
Legacy-compatible response shape

Compatibility notes

  • processing responses contain only status. Completed and partially_completed responses include data.
  • Legacy failures use a simple error body and may return HTTP 400.

Response

{
  "status": "completed",
  "data": {
    "id": "job_6789abcd",
    "style": "minimalist",
    "room_type": "Living Room",
    "intensity": 0.6,
    "color": "Earthy Neutrals",
    "output_urls": [
      "https://cdn.example/render-1.jpg"
    ]
  }
}

Multi-view

Create consistent same-room staging sets and redo sibling angles.

POSTLimited preview/api/v1/multiview

Create multi-view staging set

Stage one anchor view, then generate up to three matched sibling angles of the same room.

Billing

Requires Premium or Business access. Consumes one API quota unit and 1 credit for the anchor. Each sibling charges 6 credits when fan-out starts.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Compatibility notes

  • Limited preview: the route returns 404 unless multi-view API access is enabled for the deployment. Contact SofaBrain before integrating it.
  • Worst-case four-view set pricing is 19 credits: 1 anchor plus three siblings at 6 credits each.
  • If your balance is exhausted mid-fan-out, remaining sibling views are skipped and not charged.

Request

{
  "source_url": "https://example.com/room-anchor.jpg",
  "additional_view_urls": [
    "https://example.com/room-angle-2.jpg",
    "https://example.com/room-angle-3.jpg"
  ],
  "room_type": "Living Room",
  "style": "modern",
  "intensity": 0.6,
  "color": "Recommended"
}

Response

{
  "job_id": "anchor-source-1",
  "status": "processing",
  "result": {
    "render_set_id": "00000000-0000-4000-8000-000000000111",
    "anchor": {
      "view_index": 0,
      "job_id": "anchor-source-1",
      "status": "processing"
    },
    "pending_views": [
      {
        "view_index": 1,
        "source_url": "https://example.com/room-angle-2.jpg"
      },
      {
        "view_index": 2,
        "source_url": "https://example.com/room-angle-3.jpg"
      }
    ],
    "total_views": 3,
    "status_endpoint": "/api/v1/multiview?render_set_id=00000000-0000-4000-8000-000000000111",
    "credits": {
      "anchor_charged": 1,
      "sibling_cost_each": 6,
      "siblings_pending": 2
    }
  },
  "error": null,
  "credits_charged": 1,
  "timestamps": {
    "created_at": "2026-07-02T19:00:00.000Z",
    "updated_at": "2026-07-02T19:00:00.000Z",
    "completed_at": null
  }
}
GETLimited preview/api/v1/multiview?render_set_id={render_set_id}

Get multi-view staging status

Poll a multi-view render set until the anchor and generated sibling rows are terminal.

Billing

Read-only. No credit or quota charge.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Compatibility notes

  • Sibling output_url values remain null until the quality gate records a passing sibling_gate verdict.
  • A sibling failure is reported in result.failed; the envelope status only becomes failed when the anchor fails.

Response

{
  "job_id": "anchor-row-1",
  "status": "completed",
  "result": {
    "render_set_id": "00000000-0000-4000-8000-000000000111",
    "views": [
      {
        "view_index": 0,
        "is_anchor_view": true,
        "status": "completed",
        "output_url": "https://cdn.example/anchor.jpg",
        "error": null
      },
      {
        "view_index": 1,
        "is_anchor_view": false,
        "status": "completed",
        "output_url": "https://cdn.example/angle-2.jpg",
        "error": null
      }
    ],
    "total": 2,
    "completed": 2,
    "failed": 0
  },
  "error": null,
  "credits_charged": null,
  "timestamps": {
    "created_at": "2026-07-02T19:00:00.000Z",
    "updated_at": "2026-07-02T19:00:00.000Z",
    "completed_at": "2026-07-02T19:00:00.000Z"
  }
}
POSTLimited preview/api/v1/multiview/redo

Redo multi-view sibling angle

Re-run one matched sibling angle on the same job row without another credit charge.

Billing

Free redo. No credit charge; capped at four total attempts per sibling row.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Request

{
  "render_set_id": "00000000-0000-4000-8000-000000000111",
  "view_index": 1
}

Response

{
  "job_id": "sibling-row-1",
  "status": "processing",
  "result": {
    "render_set_id": "00000000-0000-4000-8000-000000000111",
    "view_index": 1,
    "job_id": "sibling-row-1"
  },
  "error": null,
  "credits_charged": 0,
  "timestamps": {
    "created_at": "2026-07-02T19:00:00.000Z",
    "updated_at": "2026-07-02T19:00:00.000Z",
    "completed_at": null
  }
}

Media tools

Run masked edits, upscales, and image-to-video jobs.

POSTGenerally available/api/v1/inpaint

Inpaint image

Apply mask-based edits to part of an image.

Billing

Consumes one API quota unit and 1 media credit.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Compatibility notes

  • submitted_url and mask_url must be public http(s) URLs.
  • intensity is optional and defaults to 0.5; accepted values are 0.1 through 1.0.

Request

{
  "submitted_url": "https://example.com/original.jpg",
  "mask_url": "https://example.com/mask.png",
  "render_type": "redecorate",
  "style": "modern",
  "room_type": "Living Room",
  "inpainting_type": "general",
  "intensity": 0.5
}

Response

{
  "job_id": "inpaint-job-1",
  "status": "completed",
  "result": {
    "provider": "fal",
    "output_urls": [
      "https://cdn.example/inpainted.jpg"
    ],
    "provider_status_url": "https://provider.example/inpaint/status/inpaint-job-1",
    "metadata": {
      "render_type": "redecorate",
      "inpainting_type": "general",
      "brush_type": "create"
    }
  },
  "error": null,
  "credits_charged": 1,
  "timestamps": {
    "created_at": "2026-02-18T12:00:00.000Z",
    "updated_at": "2026-02-18T12:00:00.000Z",
    "completed_at": "2026-02-18T12:00:00.000Z"
  }
}
POSTGenerally available/api/v1/upscale

Upscale image

Upscale an existing image and store the resulting URL.

Billing

Consumes one API quota unit and 2 media credits.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Compatibility notes

  • image_url must be a public http(s) URL.

Request

{
  "image_url": "https://example.com/render.jpg"
}

Response

{
  "job_id": "upscale-job-1",
  "status": "completed",
  "result": {
    "provider": "fal",
    "input_url": "https://example.com/render.jpg",
    "output_urls": [
      "https://cdn.example/upscaled.jpg"
    ],
    "provider_output_urls": [
      "https://provider.example/upscaled.jpg"
    ],
    "provider_status_url": "https://provider.example/upscale/status/upscale-job-1"
  },
  "error": null,
  "credits_charged": 2,
  "timestamps": {
    "created_at": "2026-02-18T12:00:00.000Z",
    "updated_at": "2026-02-18T12:00:00.000Z",
    "completed_at": "2026-02-18T12:00:00.000Z"
  }
}
POSTGenerally available/api/v1/video

Create video

Start a 5-second image-to-video generation job.

Billing

Consumes one API quota unit and 27 media credits.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Compatibility notes

  • Duration must be 5 seconds for the current production endpoint.
  • Supported modes are before_after, flyover, zoom_in, pan, and reveal. before_after also requires tail_image_url.
  • Video is a Premium and Business feature. Confirm plan eligibility before depending on this route.

Request

{
  "mode": "flyover",
  "image_url": "https://example.com/render.jpg",
  "duration": 5
}

Response

{
  "job_id": "video-job-1",
  "status": "processing",
  "result": {
    "provider": "fal",
    "mode": "flyover",
    "duration": 5,
    "provider_status_url": "fal-video://video-job-1",
    "status_endpoint": "/api/v1/video?job_id=video-job-1"
  },
  "error": null,
  "credits_charged": 27,
  "timestamps": {
    "created_at": "2026-02-18T12:00:00.000Z",
    "updated_at": "2026-02-18T12:00:00.000Z",
    "completed_at": null
  }
}
GETGenerally available/api/v1/video?job_id={job_id}

Get video status

Poll a video job until it completes or fails.

Billing

Read-only. No credit or quota charge.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Response

{
  "job_id": "video-job-1",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.example/video.mp4",
    "duration": 5,
    "progress": 100
  },
  "error": null,
  "credits_charged": null,
  "timestamps": {
    "created_at": "2026-02-18T12:00:00.000Z",
    "updated_at": "2026-02-18T12:00:00.000Z",
    "completed_at": "2026-02-18T12:00:00.000Z"
  }
}

Account

Read account state and delete legacy job groups.

GETGenerally available/api/v1/me

Get account info

Return account and API usage information for the API key owner.

Billing

Read-only. No credit or quota charge.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Response

{
  "api_monthly_quota": 1000,
  "api_total_completed": 42,
  "api_completed_month": 7
}
POSTGenerally available/api/v1/delete

Delete job by source

Delete all jobs under a legacy job source ID for the API key owner.

Billing

Administrative write. No media credit charge.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Request

{
  "jobId": "job_6789abcd"
}

Response

{
  "message": "Job Deleted"
}

AI tools

Generate listing copy from images and property details.

POSTLimited preview/api/v1/tools/property-description

Generate property description

Analyze listing images and produce real-estate description copy with optional structured image analysis.

Billing

Limited preview. Consumes one API quota unit and 1 media credit.

Authentication
x-api-key
Contract
Stable v1 envelope when work is media-backed

Compatibility notes

  • Limited preview: the route returns 404 unless tools API access is enabled for the deployment. Contact SofaBrain before integrating it.
  • images must contain base64 image strings or data URLs; remote image URLs are not fetched by this endpoint.

Request

{
  "images": [
    "data:image/jpeg;base64,..."
  ],
  "property_data": {
    "address": "123 Main St",
    "property_type": "house",
    "listing_status": "for-sale",
    "listing_type": "new",
    "price": 500000
  },
  "generation_settings": {
    "tone": "professional",
    "length": "medium",
    "language": "English"
  }
}

Response

{
  "job_id": "job-1",
  "status": "completed",
  "result": {
    "description": "Bright listing copy.",
    "image_analysis": [],
    "listing_id": "listing-1"
  },
  "error": null,
  "credits_charged": 1,
  "timestamps": {
    "created_at": "2026-07-02T20:00:00.000Z",
    "updated_at": "2026-07-02T20:00:00.000Z",
    "completed_at": "2026-07-02T20:00:00.000Z"
  }
}