Tokenify

Video with the fal.ai queue API

Their queue protocol, served on our models. The base URL is the one line you change, and everything else on this page is a difference worth knowing before you hit it.

The one line

Change the host. The paths underneath it are theirs, unchanged.

# before
https://queue.fal.run

# after
https://api.tokenify.dev/fal

Your key goes in the header their client already sends — Authorization: Key tk-live-… — and Authorization: Bearer tk-live-… works too, so code that normalised to Bearer does not need changing back.

Their own SDKs cannot be pointed at a different host. The JavaScript client's proxyUrl is not a base URL: it sends every request to that one URL and names the real fal endpoint in an x-fal-target-url header. The Python client documents no proxy or base-url setting at all. So this works for anything speaking the REST protocol directly — curl, your own HTTP client, a generated client you can re-base — and not for @fal-ai/client or fal_client as shipped.

What is identical

The queue protocol, which is the part your code is built around.

Behaviour
POST /{owner}/{app}Submit. Returns request_id, status, queue_position and the three URLs.
GET …/requests/{id}/status202 while IN_QUEUE or IN_PROGRESS, 200 once COMPLETED.
GET …/requests/{id}The result: video as a File object with a url.

status_url, response_url and cancel_url come back on the submit and on every status, and they point at us. Use them rather than building your own, which is their advice too.

And COMPLETED still does not mean it worked. A failed job is COMPLETED with error and error_type set, exactly as on their queue, so the branch you already wrote for that is the right one. If you never wrote it, write it: the result endpoint is the only thing that distinguishes a finished job that produced a video from a finished job that produced a refusal.

What is different

On their queueHere
The modeltheir model id is the pathour model id is the path
Parameterseach model's own schemaone set, listed below
Unknown parametersignored by some endpointsrefused by name, with a 422
queue_positionyour place in the queuealways 0 — the queue is real, but no position is published yet
Cancel202 CANCELLATION_REQUESTED400, and the reason is below
Billingper second of computeper output token

The model path is the difference that will stop your first request. Their ids name their catalogue and we do not carry it, so /fal/fal-ai/some-model answers 404 model_not_found. Ours are the same two-segment shape, so the swap is mechanical — your models page lists the ids you can send, and so does GET /v1/models with your key.

The parameters we read

FieldMeaning
promptWhat to generate.
resolutionOne of the model's own bands. Required unless the model has a single one.
durationWhole seconds, as a number or a string — their models disagree about which, so both are read.
aspect_ratioWhere the model offers one.
image_urlA still to animate, on models that accept one.
video_urlA clip to extend, on models that accept one.
generate_audioWhether the model also produces sound. See the note below.

Anything else is refused by name rather than ignored — cfg_scale, seed, camera_control and the rest of the per-model fields their endpoints take. That is deliberate and it is about money: a video is priced before it runs, so a parameter we accepted and dropped would charge you for something other than what you asked for. A 422 naming the field is the cheaper outcome.

Consider sending generate_audio: false. Audio is on by default and costs nothing extra, but the audio the model generates is itself content-filtered, and we have measured an ordinary prompt failing after ninety seconds on an audio policy refusal with nothing objectionable in it. If you do not need sound, turning it off removes a failure mode you cannot predict or fix.

A whole job

# submit
curl https://api.tokenify.dev/fal/MODEL_ID \
-H "Authorization: Key $TOKENIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A paper boat on still water, slow push in",
"resolution": "480p",
"duration": "4",
"generate_audio": false
}'

# {"request_id":"7630138d-…","status":"IN_QUEUE","queue_position":0,
# "status_url":"https://api.tokenify.dev/fal/requests/7630138d-…/status", …}

# poll: 202 until it is 200
curl -i https://api.tokenify.dev/fal/requests/7630138d-…/status \
-H "Authorization: Key $TOKENIFY_API_KEY"

# then the result
curl https://api.tokenify.dev/fal/requests/7630138d-…/ \
-H "Authorization: Key $TOKENIFY_API_KEY"

# {"video":{"url":"https://…/vid/….mp4","content_type":"video/mp4"},
# "usage":{"completion_tokens":40594,"total_tokens":40594}}

Five seconds between polls is plenty, and a job takes one to two minutes. The URL in the result is on our own domain: we fetch the finished video and serve it ourselves, so it never points anywhere else.

Two things we answer differently, and why

Cancellation is refused. Their cancel answers 202 CANCELLATION_REQUESTED for a running request, which their own documentation notes can still complete. Ours answers 400.

The reason is narrower than this page used to claim. It said a job is with the model the moment it is accepted and we cannot stop it; since the queue shipped that is only true of a dispatched job. One still waiting could in principle be dropped, and we do not do it yet — so the honest statement is that we refuse every cancellation, not that every job is already running. Once dispatched, the job finishes and is charged for.

A job that waits longer than we are willing to hold your credit fails with queue_wait_exceeded and is refunded in full. That is the one path on which a job you submitted costs you nothing.

Deleting a finished job removes the record and the stored video; it does not refund it. Deleting one that has not settled answers 409 running_task_deletion.

There is a queue now, and it is one line for everybody. This page used to say we held no queue — that a job we accepted was already running and anything else was refused at the concurrency limit. That stopped being true when the queue shipped: past the model’s limit a job is accepted and waits its turn, in the order jobs arrived, and is sent to the model as capacity frees. You get the same 200 and the same id either way.

queue_position is still reported as 0. The queue is real but we do not yet publish a position in it, and reporting a number we do not maintain would be worse than reporting none. Poll the status: a waiting job reads IN_QUEUE and a running one IN_PROGRESS, which is the distinction your code probably branches on anyway.

What it costs

Billing is per output token, not per second of compute, and the count scales with the pixels and the seconds. There is no prompt charge. The video endpoint page has the formula and the rest of the billing rules, and they apply here unchanged — the dialect changes the shape of the request, never the price.

A failed job is not charged. A job that reports no usage at all is charged the estimate it was accepted on, which the submit returns to you as estimated_output_tokens so you know the commitment before you wait for it.

Last updated 2026-11-17.