Skip to main content
POST
Creates a property showcase image from a single property photo and a selected template. Generation runs asynchronously — the request returns a job ID immediately and the finished image is delivered to your webhook_url.
Set a webhook_url. Showcase jobs are not pollable: Get Task covers video tasks only and returns 404 TASK_NOT_FOUND for a showcase job_id. The webhook is the only way to receive output_image_url.
price and size are required for every template. All other property fields are optional, but each template only accepts the subset it renders — sending a field a template doesn’t support returns a VALIDATION_ERROR. The custom template is the exception: it reproduces a reference design you registered yourself, and that design’s stored spec decides the aspect ratio, which fields are required and how many photos the request carries. See Custom Templates.

Request Body

string
required
The showcase template to render. Determines the layout, the output aspect ratio, which optional fields it accepts, and how many supporting images it takes. price and size are always required; the remaining fields are optional and only accepted when the template renders them. Most templates require an exact number of supporting_image_urls; grid_collage is the exception and accepts a range of 0 to 3 (see the table).Templates with a 9:16 aspect ratio render a vertical (portrait) image; 16:9 templates render a horizontal (landscape) image.The last four are brand layouts. They are authored for both orientations, so they take an aspect_ratio (9:16 when omitted), and they require a brand_profile_id that supplies the colour palette. Both fields are rejected on every other template.custom is a design of your own. You register a reference image once as a custom template and pass its custom_template_id here; its stored spec fixes the aspect ratio, the fields the showcase prints and the number of photos it takes, so aspect_ratio and brand_profile_id are both rejected on custom. A third-party API key needs a Pro, Max or Enterprise plan to generate with it, and is otherwise rejected with 403 PLAN_REQUIRED.See the Showcase Templates page for a visual preview of every template.
string
Brand palette applied to a brand layout. One of remax, century21, kw, ev, era, iqi, sothebys, cbre, colliers, eastdil, zillow.Required by the four brand templates (full_bleed_panel, grid_collage, split_panel, framed_border). Omitting it there returns a VALIDATION_ERROR on the brand_profile_id path with the message "brand_profile_id is required for the <template> template".Rejected by every other template, with the message "brand_profile_id is not supported by the <template> template".The profile supplies the colour palette and renders the partner’s own logo on the showcase automatically. logo_image_url is rejected on these four templates.See the Showcase Templates page for every profile with its display name and primary colour.
string
default:"9:16"
Orientation of the rendered image: 9:16 (vertical) or 16:9 (horizontal). Accepted only by the four brand templates (full_bleed_panel, grid_collage, split_panel, framed_border), where it is optional and defaults to 9:16.Every other template renders at the fixed ratio listed in the table above and rejects the field with a VALIDATION_ERROR on the aspect_ratio path: "aspect_ratio is not supported by the <template> template".On custom, the ratio comes from the template’s stored spec.aspect_ratio and the field is rejected the same way.
string
Identifier of the custom template to reproduce, as returned when you registered the reference design.Required by template_id: "custom". Omitting it there returns a VALIDATION_ERROR on the custom_template_id path with the message "custom_template_id is required for the custom template".Rejected by every other template, with the message "custom_template_id is not supported by the <template> template".The template must be one of yours and must not be archived: an unknown id, or one belonging to another account, returns 404 NOT_FOUND, and an archived one returns 409 CUSTOM_TEMPLATE_ARCHIVED.
string
Optional override of the reference design stored on the custom template, for this generation only. Accepted only with template_id: "custom"; every other template rejects it with "reference_image_url is not supported by the <template> template".Use it when the design lives behind a URL you rotate, for example a freshly signed link to the same artwork. Validated like every other image URL (reachable, accepted format, at most 8 MB, no private network) and reported on the reference_image_url field. When omitted, the URL stored on the template is read instead.
string
Optional free-text tweak appended to the edit instruction sent to the generator, at most 250 characters, e.g. "Keep the price in the gold accent colour". Whitespace-only text is dropped.Accepted only with template_id: "custom"; every other template rejects it with "custom_instruction is not supported by the <template> template". A longer value returns "custom_instruction must be at most 250 characters".
object
required
Property data rendered onto the showcase. price and size are always required (non-empty strings) for every template. The remaining fields are optional and only accepted when the selected template_id renders them (see the table above). Omitting a required field — or sending an empty string — returns a VALIDATION_ERROR with a fields.<name> path, and sending a field the template doesn’t accept returns a VALIDATION_ERROR with the message "<field> is not a valid field for the <template> template".On custom the stored spec replaces those rules: fields accepts exactly the spec’s text_fields and every one of them is required, price and size included only when the design prints them. A field the spec does not declare returns "<field> is not a valid field for the custom template", and a declared field that is missing or empty returns "<field> is required for this custom template". When the stored spec carries spec.text_sources, each value you send replaces exactly that original text in the design, rather than being placed by the field’s role alone.
price and size are required for every template. String fields (price, size, label) must not be empty or whitespace-only. Numeric fields (bedrooms, bathrooms, parking) must be non-negative integers. Sending a field the selected template doesn’t accept is rejected.
string
default:"en"
Language used to render the showcase copy. One of en, es, de, fr, it, pt. Defaults to en when omitted. Forwarded to the generation service so the rendered text matches the requested locale.
string
required
URL of the primary property photo used as the showcase hero image. Must be a valid, publicly accessible URL.
string[]
default:"[]"
Additional property photos. Most templates require an exact number of supporting images (see the template_id table): 0 for hero_impact, info_story, full_bleed_panel, split_panel and framed_border, 3 for most of the rest, and 4 for modern. Sending the wrong number returns a VALIDATION_ERROR on the supporting_image_urls path with the message "The <template> template requires exactly N supporting images". grid_collage is the only template with a range: it accepts 0 to 3 and fills the cells it is given, returning "The grid_collage template accepts up to 3 supporting images" when it is sent more than three. Each must be a valid URL. For a template that requires 0, omit the field or pass an empty array.On custom the count is fixed by the design: exactly image_slots.length - 1 supporting images, because the first slot is filled by main_image_url. Any other number returns "This custom template requires exactly N supporting images".
string
Optional URL of a brand/agency logo to overlay on the showcase. Must be a valid URL. May be null.Rejected on the four brand templates (full_bleed_panel, grid_collage, split_panel, framed_border): the partner’s own logo is rendered automatically from the brand profile, so sending logo_image_url there returns a VALIDATION_ERROR on the logo_image_url path with the message "logo_image_url is not supported by the <template> template". On the twelve other templates it works exactly as described above.On custom the stored spec decides: a design with a logo_area requires it ("This custom template requires logo_image_url"), and a design without one rejects it ("logo_image_url is not supported by this custom template").
Accepted image formats & size. Every image URL (main_image_url, supporting_image_urls, logo_image_url) must point to a publicly reachable image in one of these formats: PNG, JPG/JPEG, GIF, WebP, BMP, TIFF, AVIF, HEIC, ICO, SVG, and must be ≤ 8 MB each. Before the job is accepted, every URL is validated for reachability, content type, actual image content (magic bytes), and SSRF safety; a failure returns one of the image error codes listed below. These image errors carry no details object — the offending field name is prefixed onto the message instead, e.g. "main_image_url: Image exceeds the 8 MB limit".
string
URL to receive a webhook notification when the job completes. Must be a valid HTTPS URL, at most 2048 characters. May be null. See Webhooks for details.
The webhook is the only way to receive the finished image. Showcase jobs are not exposed through Get Task — that endpoint covers video tasks only and returns 404 TASK_NOT_FOUND for a showcase job_id. Without a webhook_url you cannot retrieve output_image_url.
Webhook URLs must use HTTPS and cannot point to private/internal networks (SSRF protection). A non-HTTPS or private URL is rejected with VALIDATION_ERROR and the message Webhook URL must be HTTPS and cannot point to private networks.

Response

string
required
Unique identifier for the showcase job. Use this to check status or correlate the webhook.
string
required
Initial job status. Always pending for new jobs.
string
required
Human-readable confirmation that the request was accepted for async processing.
string
required
Unique identifier for this request, useful for support and debugging.

Example: brand layout

A brand layout adds two fields to the same body: the brand_profile_id that supplies the palette and an optional aspect_ratio. split_panel renders the property data in a solid brand block beside or above the photo and takes no supporting images. There is no logo_image_url in this example: the partner logo is rendered automatically from the brand profile, and sending one is rejected.

Example: custom template

A custom showcase names the design instead of a layout: template_id: "custom" plus the custom_template_id you got when you registered the reference image. The body below targets a design whose spec holds three image slots (so two supporting images), a logo area and the text fields price, size and bedrooms. There is no aspect_ratio: the design’s own ratio is used. See Custom Templates.

Webhook Payload

If you provide a webhook_url, VibePeak sends a POST request when the job finishes, carrying X-VibePeak-Event, X-VibePeak-Signature and X-VibePeak-Timestamp headers. Delivery is attempted up to 3 times with exponential backoff; a 4xx response from your endpoint stops the retries. See Webhooks for signature verification.

Completed

Failed

On failure error is always the fixed string above — the underlying provider message is never exposed. Use request_id from the create call when contacting support.

Error Codes

Error shape. VALIDATION_ERROR responses carry a details object of the form { "field": "<dotted.path>", "issues": [{ "path": "<dotted.path>", "message": "..." }] } — field is the first failing path and issues lists every failure. All other error codes (including the image codes above) return no details.
See Error Handling for more details.

Credits

This endpoint charges 2 credits per request for accounts without an annual plan. Accounts on an annual plan are not charged (0 credits). Credits are charged upon successful job creation and are not refunded if generation fails.
Test mode is not supported on this endpoint. Unlike the video endpoints, a vpk_test_ key is not sandboxed here — the request runs the real generation pipeline and charges credits. Use it only when you intend to generate a real image. See Test Mode.

Next Steps

After creating a job:
  1. Wait for the webhook: your webhook_url receives a showcase.completed or showcase.failed notification. Verify the X-VibePeak-Signature header as described in Webhooks.
  2. Download the image: read output_image_url from the showcase.completed payload.
There is no polling endpoint for showcase jobs. Get Task serves video tasks only and returns 404 TASK_NOT_FOUND for a showcase job_id. If you do not set a webhook_url, the generated image cannot be retrieved.