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

# Upload Reference Images for Prompts and Generations

> Learn how to upload PNG, JPEG, WebP, and GIF images to Prompt Bank for use as prompt images or generation inputs. Covers the two-step signed upload flow.

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

<Steps>
  <Step title="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:

    ```bash theme={null}
    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
      }'
    ```

    ```json theme={null}
    {
      "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
    }
    ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    <Note>
      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.
    </Note>

    **Attach to a prompt as `imageUrl`:**

    ```bash theme={null}
    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`:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    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
      }'
    ```
  </Step>
</Steps>

## Next steps

* Use your uploaded images as generation inputs in the [Generate Media guide](/guides/generate-media).
* Store image URLs on prompts by following the [Manage Prompts guide](/guides/manage-prompts).