How Do I Upload Reference Images to an AI Image API?

Overview

Upload a reference image to WaveSpeedAI in three steps: POST filename and exact byte size to /api/v3/media/uploads for an upload ticket; PUT the file bytes to the returned signed upload.url with its returned headers; then pass download_url to an image-capable model route. Do not send a local filesystem path or your bearer key to the signed PUT URL.

The ticket’s signed URL is short-lived and specific to that upload; do not construct or reuse its hostname. The image-generation and editing routes have different fields, so place download_url in the selected route’s documented image parameter. Reject unsupported files and tie the source asset to the user and permission record. The current upload guide describes seven-day input retention, so the returned URL is not a permanent archive.

After upload, create the generation task once and record both the upload reference and prediction ID. If the upload succeeds but task creation fails, your app should show a recoverable state instead of silently discarding the user’s image. Review generated output for unintended exposure of private or licensed content.

Keep the original in storage you control only for as long as your product policy permits. A model input URL is a transport mechanism, not a complete consent or retention policy.

For shared products, authorize the upload against the current user before requesting a ticket and again before starting generation. Store the provider URL as a scoped job reference rather than exposing it in public logs, analytics or client-visible error messages.

Delete abandoned uploads according to the product’s documented retention schedule.

Source: WaveSpeedAI upload API; WaveSpeedAI image generation guide; WaveSpeedAI data retention policy. Source check: 2026-09-29.