RandomDuck

About RandomDuck

RandomDuck is an API that returns random images and GIFs of ducks. Requests can be filtered by type (GIF or JPG), and endpoints are available to retrieve a random image as a JSON object with a URL and message, to fetch an image file directly, to list all available filenames, or to retrieve a specific image by number.

The API also provides duck images representing specific HTTP status codes, accessible via a dedicated endpoint. It supports image uploads through a separate endpoint using multipart form data, with an optional JSON response mode for status feedback during integration.

Requests are rate-limited per IP address, with a burst limit of 10 requests per second per endpoint and a global limit of 300 requests per minute; rate limit status is communicated through response headers, and a 429 status code with a Retry-After header is returned when a limit is exceeded. A legacy V1 API exists for backwards compatibility but is deprecated in favor of V2, which is used by default if no version is specified in the request URL.

Key features

• Returns a random duck image or GIF via JSON or direct file endpoints
• Lists all available image and gif filenames with counts
• Serves duck images representing specific HTTP status codes
• Supports image uploads via multipart form POST to a queue
• Provides rate-limit headers and Retry-After on 429 responses
• Offers versioned API (V2 current, V1 legacy) with a documented base URL

Frequently asked questions