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

# Async generation and polling

> Wait for results with wait_seconds or by polling.

Generations are asynchronous. A generation goes through these statuses:

| Status | Meaning |
| - | - |
| `queued` | Accepted, waiting for a worker |
| `processing` | Being generated by the model |
| `completed` | Done: `url`, `download_url` and `preview_url` are available |
| `failed` | The model could not produce the media. Credits are refunded. See `failure_reason`. |

## Option 1: wait in the request

Add `wait_seconds` (0–55) to `POST /generations`, `GET /generations/{id}`, `POST /encore/creations` or `GET /encore/creations/{id}`. The API returns as soon as the job is finished, or after the delay with the current status. Ideal for images.

## Option 2: poll

```python theme={null}
import os, time, requests

HEADERS = {"Authorization": f"Bearer {os.environ['HAVINCY_API_KEY']}"}
BASE = "https://havincy.com/api/v1"

job = requests.post(f"{BASE}/generations", headers=HEADERS, json={
    "modality": "video",
    "model_id": "fal-kling-v3-pro",
    "prompt": "A paper boat sailing on a rainy street",
    "duration": 5,
}).json()
asset_id = job["assets"][0]["id"]

while True:
    gen = requests.get(f"{BASE}/generations/{asset_id}", headers=HEADERS,
                       params={"wait_seconds": 30}).json()
    if gen["status"] in ("completed", "failed"):
        break
    time.sleep(5)

print(gen["assets"][0].get("url"))
```

<Tip>Combining a short polling loop with `wait_seconds` keeps the number of requests low and your rate limit free.</Tip>

## Files

* `url`: stable link to the file (images, videos, audio, 3D).
* `download_url`: same file with a download disposition.
* `preview_url`: poster image for videos when available.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.