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

# Generate Image

> Queue an image generation job

Generates an image from a text prompt. **This endpoint is always async** — it returns a `job_id` immediately and the actual generation happens on a background queue. Poll [`GET /jobs/:id`](/api-reference/jobs/get) until `status` is `completed`, then read `result.url`.

The completed image is automatically uploaded to R2 storage and saved to the team's asset library.

## Authentication

<ParamField header="Authorization" type="string">
  Bearer token. `Bearer <api-key-or-jwt>`.
</ParamField>

## Body

<ParamField body="prompt" type="string" required>
  Text description of the image to generate.
</ParamField>

<ParamField body="model" type="string" default="fal:flux-schnell">
  Model identifier in `provider:model` format. Use `GET /models` to list options.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Aspect ratio for the generated image, e.g. `"9:16"`, `"1:1"`, `"16:9"`.
</ParamField>

<ParamField body="reference_image_url" type="string">
  URL of a reference image for image-to-image generation.
</ParamField>

<ParamField body="reference_strength" type="number">
  How closely to follow the reference image (0-1). Only used when `reference_image_url` is provided.
</ParamField>

<ParamField body="influencerId" type="string">
  If provided, the completed image is automatically appended to this influencer's image array. Survives the user navigating away mid-generation.
</ParamField>

## Polling pattern

```bash theme={null}
# 1. Submit
curl -X POST https://api.supapost.so/generate/image \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "sunset over tokyo", "aspect_ratio": "9:16"}'
# → 202 { "job_id": "0b1e...", "status": "pending" }

# 2. Poll every 1-2 seconds
curl https://api.supapost.so/jobs/0b1e... \
  -H "Authorization: Bearer $KEY"
# → { "status": "processing", ... }
# → { "status": "completed", "result": { "url": "https://cdn.supapost.so/...jpg" } }
```

<ResponseExample>
  ```json 202 theme={null}
  {
    "job_id": "0b1e9a5f-1234-4d8c-b2a0-...",
    "status": "pending"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "message": "prompt is required"
  }
  ```

  ```json 429 theme={null}
  {
    "success": false,
    "message": "Rate limit exceeded for expensive endpoints. Retry in 60s."
  }
  ```
</ResponseExample>