Media

POST /v1/products/:ref/image
POST /v1/banners/:ref/image
POST /v1/stories/:ref/image
POST /v1/logo

Attach images without multipart uploads: give the API a URL to fetch (sourceUrl) or inline base64 bytes. The server downloads/decodes, validates the actual bytes, optimizes (WebP/PNG resize) and stores the image — the same pipeline the app's own uploads use. Available on every plan with an active subscription.

:ref accepts your externalId or the opaque id (products/banners/stories; unknown ref → 404 with PRODUCT_NOT_FOUND / BANNER_NOT_FOUND / STORY_NOT_FOUND).

Request body#

Exactly one of sourceUrl or base64 (both/neither → 400 INVALID_IMAGE_SOURCE):

sourceUrl rules#

The fetch is strictly sandboxed; violations return machine codes:

• https:// only, default port, no credentials in the URL → 400 INVALID_SOURCE_URL
• The host must resolve to a public address — private/internal ranges are rejected → 403 BLOCKED_SOURCE_URL
• Redirects are re-validated per hop (max 3)
• ~10 s total fetch timeout; 15 MB hard size cap → 413 SOURCE_TOO_LARGE
• Content is checked by real file signature — JPEG, PNG, WebP or HEIC (headers/extensions are ignored; GIF not supported) → 400 INVALID_IMAGE

After acquisition, the standard per-type limits of the upload pipeline apply — the same ones the app UI enforces:

Fast lane — pre-optimized media#

Server-side processing (decode → resize → WebP re-encode) runs through a shared queue, so heavy originals wait longer. If you send an image that is already what the pipeline produces, the server stores it verbatim — skipping the decode/re-encode step and its queue entirely.

A product or banner image takes the fast path automatically when all of these hold (logo and story photos are never eligible — the logo always re-processes to generate favicons, and stories always re-encode to the portrait preset, so ?preoptimized=true is ignored for them):

• WebP format;
• ≤ 500 KB;
• within target dimensions — products ≤ 1024×1024, banners ≤ 1920×1080.

Nothing changes in your request — a qualifying image just uploads faster. Validation is unchanged: magic-byte checks, the size cap and the SSRF rules above always apply, and the dimensions are re-verified server-side (a small WebP can still be a decompression bomb), so verbatim storage is safe.

Claim the softer rate limit — ?preoptimized=true#

The fast path also has its own, more generous rate-limit bucket (mediaFast: 20/min free, 100/min paid — vs the normal media bucket's 5/30). To draw from it, add ?preoptimized=true to the product/banner image request:

POST /v1/products/:ref/image?preoptimized=true
POST /v1/banners/:ref/image?preoptimized=true

The server verifies the bytes actually qualify for the fast path. If they don't (not WebP, over 500 KB, or over target dimensions) the request is rejected with 400 PREOPTIMIZED_INVALID — the softer limit can't be spent on a heavy upload. Send such images without the flag and they go through normal processing on the regular media bucket.

Example — product image by URL#

curl -X POST https://api.duck-hub.com/v1/products/prod-margherita/image \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "sourceUrl": "https://images.example.com/margherita.jpg", "crop": "square" }'

const response = await fetch(
  'https://api.duck-hub.com/v1/products/prod-margherita/image',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer dk_live_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sourceUrl: 'https://images.example.com/margherita.jpg',
      crop: 'square',
    }),
  },
)
const { mediaUrl, mediaType } = await response.json()

Example — logo from local bytes (base64)#

BASE64=$(base64 -w0 logo.png)
curl -X POST https://api.duck-hub.com/v1/logo \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{ \"base64\": \"$BASE64\", \"crop\": \"square\" }"

import { readFile } from 'node:fs/promises'
 
const base64 = (await readFile('logo.png')).toString('base64')
const response = await fetch('https://api.duck-hub.com/v1/logo', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ base64, crop: 'square' }),
})
const { logoUrl } = await response.json() // favicons are generated too

Product/banner responses return { mediaUrl, mediaType }; uploading again replaces the previous image. The logo response returns { logoUrl } and regenerates the favicon set.

Errors#