Reference

Async tasks

Generations run on a queue. Your code submits once, polls status until completion, then fetches the result. The SDKs fold all three calls into a single await; cURL makes them explicit.

Lifecycle

A request moves through four possible states. Terminal states are COMPLETED and FAILED. Everything else is transient and safe to poll through.

submit  ->  IN_QUEUE  ->  IN_PROGRESS  ->  COMPLETED  (fetch result)
                                       ->  FAILED     (read logs)

The three calls

The SDKs wrap these three HTTP calls into one convenience method. Use the explicit form when you need to submit now and collect later (e.g. from a different process).

BASH

1# 1. Submit. Store request_id from the response.
2curl -X POST "https://queue.fal.run/fal-ai/happyhorse/v1/text-to-video" \
3  -H "Authorization: Key $FAL_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{"prompt":"Documentary style interview at night. A barista in a rain jacket leans agains...","duration":"5s","resolution":"720p","aspect_ratio":"16:9","generate_audio":true,"language":"en"}'
6
7# 2. Poll status until COMPLETED.
8curl "https://queue.fal.run/fal-ai/happyhorse/v1/text-to-video/requests/<request_id>/status?logs=1" \
9  -H "Authorization: Key $FAL_KEY"
10
11# 3. Fetch the result.
12curl "https://queue.fal.run/fal-ai/happyhorse/v1/text-to-video/requests/<request_id>" \
13  -H "Authorization: Key $FAL_KEY"

Polling hygiene

Poll at 1 to 2 second intervals; faster is rude, slower is impatient to your users.
Cap total wait time per job; surface a friendly timeout at the UI layer.
Cancel in-flight polls when a user abandons the request.
Do not poll if you already registered a webhook; see the next page.