> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Download image bytes

> Retrieve an image for ingestion into your own storage.

Send a public HTTPS image URL to `POST /v1/images/download` to retrieve the image
for your own storage. You can use URLs from any source; no prior product or brand
research request is required. Authenticate with your Upriver API key.

Successful responses contain binary image bytes. Read the response body as bytes,
rather than parsing it as JSON. Error responses contain a JSON `detail` field.

```bash theme={null}
curl --fail-with-body 'https://api.upriver.ai/v1/images/download' \
  -H "X-API-Key: $UPRIVER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/product.png"}' \
  --dump-header response-headers.txt \
  --output image.bin
```

Use the response's `Content-Type` to determine the actual format; the source URL's
extension may differ. Supported formats are JPEG, PNG, WebP, GIF, and AVIF.
Responses are attachments with `Cache-Control: no-store`. No hosted image copy is
created. Each request attempts retrieval from the supplied URL; the endpoint does
not guarantee access to every protected source or preserve the image for later.

## Use with product research

Request `image_url` in the `include` fields of `POST /v1/brand/products`, then send
selected image URLs to this endpoint when you need help retrieving them. Store
successful downloads in your own storage and use your own URLs for later display.
Research responses continue to include original image URLs.

## Limits and errors

Downloads are limited to 10 MiB, 16 million decoded pixels in total, and 32 frames.
Only public HTTPS URLs on the standard HTTPS port are accepted. URLs requiring
login credentials are unsupported.

Each account can make 30 attempts per minute and 1,000 per day, subject to shared
service capacity. Failed attempts can count toward these limits. Downloads do not
consume product-research credits. A `429`
response includes `Retry-After`; a `503` indicates temporary unavailability.
Oversized images return `413`. Missing sources may return `404`; upstream failures,
challenge pages, and invalid images return `502`. Upstream timeouts return `504`.