Imagery

Request Wine Imagery

Request one cleaned bottle image, front label, or back label for a wine. Ready assets are returned immediately; missing assets enter the processing queue.

post/wine_labels

Request

  • Base URL: https://external-api.wine-labs.com
  • URL: https://external-api.wine-labs.com/wine_labels
  • Auth: none declared

Request body

user_idstring uuid

Account identifier. Optional when the request uses an authorized Authorization header.

querystring

Free-text wine name. At least one of query, lwin, or wl_id is required.

lwinstring

LWIN identifier. At least one of query, lwin, or wl_id is required.

wl_idstring

Wine Labs wine identifier. At least one of query, lwin, or wl_id is required.

vintagestring

Optional vintage for bottles and front labels. A four-digit year is required when vintage_treatment is exact. Ignored for back labels.

label_typestring

Asset to deliver: bottle, front_label, or back_label.

vintage_treatmentstring

For bottles and front labels, exact requires the requested year to be visible, reusable requires no visible vintage, and any accepts the best validated image. Back labels always use any regardless of the supplied treatment.

vintage_specificboolean

Legacy treatment selector used only when vintage_treatment is omitted. true maps to exact; false maps to reusable. Ignored for back labels.

client_request_idstring

Optional caller-supplied identifier, up to 200 characters, for reconciling the request with your system.

overlay.image_urlstring uri

Public HTTPS URL for your PNG or logo. Wine Labs downloads and stores a validated copy, so no upload step is required.

overlay.positionstring

Placement: top_left, top_right, center, bottom_left, bottom_right, or custom.

overlay.layerstring

foreground places the logo over the image; background places it behind a transparent bottle image.

overlay.scalenumber

Logo width as a fraction of the output width, from 0.02 to 1.

overlay.opacitynumber

Logo opacity from 0 to 1.

overlay.rotationnumber

Clockwise rotation in degrees from -180 to 180.

overlay.x / overlay.ynumber

Normalized center coordinates from 0 to 1; both are required when position is custom.

background.stylestring

Optional bottle-only studio set: luxury_studio (warm beige), limestone_studio, or rose_studio. May be combined with a foreground logo.

output_size.width / output_size.heightinteger

Exact output canvas in pixels. Each side must be 256–4096 px and the canvas at most 16 million pixels. Content is fitted without stretching; for example, { "width": 1600, "height": 1600 }.

Response

Response highlights:

  • request.status: fulfilled, processing, unavailable, failed, awaiting_credits, or cancelled.
  • request.asset_url: canonical download URL when fulfilled.
  • request.status_url: API route for refreshing this request.
  • credits: Imagery delivery credits included, used, and remaining.
  • dashboard_url: signed-in request dashboard at https://winelabs.ai/api/imagery-requests.

Notes:

  • The canonical asset_url is a time-limited signed URL with a hash-only object path, for example /winelabs/cleaned-labels/hash/bf3f78c66e58.png.
  • Refresh an expired signed URL by listing requests or fetching the request again. Do not construct delivery URLs from wine names or slugs.
  • asset_payload preserves source and processing metadata; use asset_url for delivery.
  • A standard fulfilled request uses 1 Imagery delivery credit. overlay adds 0.1 credit and background adds 0.1 credit, so using both costs 1.2 credits.
  • Back labels are charged once per wine for each user. Repeated deliveries, including different output sizes or logo options, reuse the paid wine entitlement.
  • Custom output sizes do not add to the credit cost.
  • Branded output is a request-specific derivative. The canonical Wine Labs image is never modified.
object required

Changes

No recorded changes to this operation across all 1 revision of this API.