---
title: "Request Wine Imagery"
method: POST
path: "/wine_labels"
tags: ["Imagery"]
---

# Request Wine Imagery

`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 one cleaned bottle image, front label, or back label for a wine. Ready assets are returned immediately; missing assets enter the processing queue.

## Request body

- object
  - `user_id` string, uuid: Account identifier. Optional when the request uses an authorized `Authorization` header.
  - `query` string: Free-text wine name. At least one of `query`, `lwin`, or `wl_id` is required.
  - `lwin` string: LWIN identifier. At least one of `query`, `lwin`, or `wl_id` is required.
  - `wl_id` string: Wine Labs wine identifier. At least one of `query`, `lwin`, or `wl_id` is required.
  - `vintage` string: Optional vintage for bottles and front labels. A four-digit year is required when `vintage_treatment` is `exact`. Ignored for back labels.
  - `label_type` string: Asset to deliver: `bottle`, `front_label`, or `back_label`.
  - `vintage_treatment` string: 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_specific` boolean: Legacy treatment selector used only when `vintage_treatment` is omitted. `true` maps to `exact`; `false` maps to `reusable`. Ignored for back labels.
  - `client_request_id` string: Optional caller-supplied identifier, up to 200 characters, for reconciling the request with your system.
  - `overlay.image_url` string, uri: Public HTTPS URL for your PNG or logo. Wine Labs downloads and stores a validated copy, so no upload step is required.
  - `overlay.position` string: Placement: `top_left`, `top_right`, `center`, `bottom_left`, `bottom_right`, or `custom`.
  - `overlay.layer` string: `foreground` places the logo over the image; `background` places it behind a transparent bottle image.
  - `overlay.scale` number: Logo width as a fraction of the output width, from `0.02` to `1`.
  - `overlay.opacity` number: Logo opacity from `0` to `1`.
  - `overlay.rotation` number: Clockwise rotation in degrees from `-180` to `180`.
  - `overlay.x / overlay.y` number: Normalized center coordinates from `0` to `1`; both are required when `position` is `custom`.
  - `background.style` string: 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.height` integer: 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 `200`

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

---

[API](https://skmtc.dev/winelabs/apis/wine-labs-api.md) · [All operations](https://skmtc.dev/winelabs/apis/wine-labs-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winelabs/apis/wine-labs-api/revisions/f8898ca9974e?raw)