Matchai Docs

Edit or stage a photo with AIComing soon

Makes an edited version of one photo: declutter, a new sky, relighting, a time of day, a season, a mood, virtual staging, a sharper upscale, or a change you…

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.
POST
/listings/{listing_id}/photo-edits

Coming soon. Makes an edited version of one photo: declutter, a new sky, relighting, a time of day, a season, a mood, virtual staging, a sharper upscale, or a change you describe. Nothing structural changes. The edit is not on the listing until you apply it. Energy is spent per photo, and refunded if the edit fails.

Spends Matchai Energy. Returns 402 without doing anything when the account does not have enough Energy, or when this connection reached the Energy limit the account holder set for it.

Scopes: listings:write

Pricing: Included with the connection, and spends Matchai Energy.

Authorization

headerAuthorizationBearer <matchai_<base62>>

A personal API key, sent as Authorization: Bearer matchai_…. Create keys in Matchai under Settings → Connectors → Advanced (for developers). A key starts with matchai_ followed by letters and digits, carries the scopes chosen when it was created, and can be revoked at any time. Keys reach only the account that created them: to serve other professionals, use Connect with Matchai.

Scope: listings:write

Path Parameters

listing_id*string

Listing id, or its slug.

Length1 <= length <= 200

Header Parameters

Idempotency-Key?string

A unique string (a UUID works). Retrying with the same key within 24 hours returns the first response instead of acting twice. Reusing a key with a different body returns 409 idempotency_key_reused.

Length1 <= length <= 255

Request Body

application/json
  1. body
media_id*string

The photo to edit.

Length1 <= length <= 64
kind*string

declutter, sky, relight, enhance, time_of_day, weather, season, mood, lively, custom (described in instruction), stage (virtual staging, with style) or upscale.

Value in"declutter""sky""relight""enhance""time_of_day""weather""season""mood""lively""custom""stage""upscale"
detail?string

time_of_day: dusk, golden_hour or night. weather: clear, overcast or after_rain. season: spring, summer, autumn or winter. mood: warm, cool or cozy_lights_on. lively: couple, family, dog or guests.

Lengthlength <= 40
instruction?string

For custom: the change, in your words. Nothing structural.

Lengthlength <= 400
style?string

For stage.

Value in"modern""scandinavian""traditional""minimal"

Response Body

The edit has started.

application/json
  1. response

An edited version of a photo. It is not on the listing until you apply it.

id*string

Edit id.

Length1 <= length <= 64
listing_id*string

Listing id.

Length1 <= length <= 64
media_id*string

The photo it was made from.

Length1 <= length <= 64
kind*string

The edit kind requested.

status*string
Value in"queued""running""succeeded""failed""applied"
preview_url?|

The edited photo, once it succeeded.

Formaturi
applied_media_id?|

The media created or replaced when it was applied.

Length1 <= length <= 64
error?|null
created_at*string

Requested.

Formatdate-time
completed_at?|

Finished.

Formatdate-time
Example Request
curl -X POST 'https://api.matchai.co/v1/listings/string/photo-edits' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "media_id": "string",  "kind": "declutter"}'
Example Response
{  "id": "string",  "listing_id": "string",  "media_id": "string",  "kind": "string",  "status": "queued",  "preview_url": "http://example.com",  "applied_media_id": "string",  "error": {    "code": "string",    "message": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z"}