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.

Request Body

string
required
The showcase template to render. Determines the layout, the output aspect ratio, which optional fields it accepts, and exactly how many supporting images it requires. price and size are always required; the remaining fields are optional and only accepted when the template renders them. Each template requires an exact number of supporting_image_urls (see the table).Templates with a 9:16 aspect ratio render a vertical (portrait) image; 16:9 templates render a horizontal (landscape) image.See the Showcase Templates page for a visual preview of every template.
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".
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. Each template requires an exact number of supporting images (see the template_id table): 0 for hero_impact and info_story, 3 for most templates, and 4 for modern. Sending the wrong number returns a VALIDATION_ERROR on the supporting_image_urls path. Each must be a valid URL. For a template that requires 0, omit the field or pass an empty array.
string
Optional URL of a brand/agency logo to overlay on the showcase. Must be a valid URL. May be null.
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.

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.