Upload Reference Images for Prompts and Generations

Uploading images to Prompt Bank gives you a stable, CDN-hosted URL that you can attach to prompts as a reference image or pass directly into a generation job as an imageInput. Whether you’re providing a style reference, a base image for image-to-image generation, or a visual for your prompt’s imageUrl field, the upload flow is the same: request a signed upload URL, push the bytes directly to storage, then use the returned permanent URL in your API calls.

Supported formats and limits

Property	Details
Formats	PNG, JPEG, WebP, GIF
Maximum file size	10,485,760 bytes (10 MB)
Signed URL expiry	7,200 seconds (2 hours) from issue time

Upload an image

Request a signed upload URL

Send a POST /api/v1/uploads/images request with the contentType and size (in bytes) of the file you want to upload. This endpoint requires the prompts:write scope. The API returns a short-lived signed URL, a token, and the permanent URL your file will live at once uploaded:

curl -X POST https://www.promptbank.club/api/v1/uploads/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "image/png",
    "size": 2048000
  }'

{
  "data": {
    "uploadUrl": "https://uploads.promptbank.club/sign/usr_01hxyz/ref-01hxyz.png?token=eyJhbGci...",
    "token": "eyJhbGci...",
    "url": "https://cdn.promptbank.club/uploads/usr_01hxyz/ref-01hxyz.png",
    "path": "usr_01hxyz/ref-01hxyz.png",
    "contentType": "image/png",
    "size": 2048000,
    "expiresIn": 7200
  },
  "error": null
}

The uploadUrl expires 7,200 seconds (2 hours) after it is issued. Complete the file upload before the expiry time. If the URL expires before you upload, request a new signed URL by calling POST /api/v1/uploads/images again.

Upload the file bytes

Send the raw file bytes to the uploadUrl using a PUT request. Set the Content-Type header to match the contentType you declared in the previous step:

curl -X PUT "https://uploads.promptbank.club/sign/usr_01hxyz/ref-01hxyz.png?token=eyJhbGci..." \
  -H "Content-Type: image/png" \
  --data-binary @/path/to/your/image.png

A 200 OK response confirms the bytes were written successfully. No Prompt Bank Authorization header is needed for this step — the signed URL carries the required authorization.

Use the permanent URL in your prompts and generations

After the upload succeeds, use the url value (not the uploadUrl) wherever Prompt Bank expects an image URL. The url is permanent and does not expire.

Always use the url field from the upload response — not the uploadUrl. The uploadUrl is a temporary signed URL used only to write your file to storage; it stops working after the 2-hour expiry window. The url is the CDN-hosted address where your file lives permanently.

Attach to a prompt as imageUrl:

curl -X PATCH https://www.promptbank.club/api/v1/prompts/1002 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.promptbank.club/uploads/usr_01hxyz/ref-01hxyz.png"
  }'

Use as a reference in referenceMediaUrls:

curl -X PATCH https://www.promptbank.club/api/v1/prompts/1002 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceMediaUrls": [
      "https://cdn.promptbank.club/uploads/usr_01hxyz/ref-01hxyz.png"
    ]
  }'

Pass as imageInput in a generation:

curl -X POST https://www.promptbank.club/api/v1/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "fal-ai/recraft/v4.1/image-to-image",
    "prompt": "Reimagine as a vintage travel poster, bold flat colors, hand-lettered typography",
    "generationType": "image",
    "imageInput": "https://cdn.promptbank.club/uploads/usr_01hxyz/ref-01hxyz.png",
    "aspectRatio": "2:3",
    "vaultId": 42
  }'

Next steps

Use your uploaded images as generation inputs in the Generate Media guide.
Store image URLs on prompts by following the Manage Prompts guide.

Get Started

Core Concepts

Guides

Upload Reference Images for Prompts and Generations

Supported formats and limits

Upload an image

Next steps

​Supported formats and limits

​Upload an image

​Next steps

Supported formats and limits

Upload an image

Next steps