AI Provider Polling

AI APIs for image generation, video creation, and audio processing return a job ID and require polling until the result is ready. AsyncQueue handles this natively - submit your request and we poll for results on your behalf, with no timeout limits.

The Problem

Serverless functions on Vercel, AWS Lambda, or Cloudflare Workers have strict timeout limits (25-60 seconds). AI generation tasks like video creation with RunwayML or image generation with fal.ai can take minutes. You cannot hold a connection open long enough to wait for the result.

How It Works

1. Create a task with a provider template (or custom pollConfig)
2. AsyncQueue calls the AI provider’s submit endpoint
3. The task transitions to polling status
4. AsyncQueue periodically checks the provider’s status endpoint
5. When the AI job finishes, the task completes with the result
6. Your onCompleteUrl webhook receives the final output

Your App                AsyncQueue              AI Provider
  |                        |                        |
  |-- POST /v1/tasks ----->|                        |
  |   provider: "fal"      |-- POST submit -------->|
  |<-- 201 { task } -------|<-- { request_id } -----|
  |                        |   (status: "polling")  |
  |                        |                        |
  |                        |-- GET status ---------->|
  |                        |<-- "IN_PROGRESS" ------|
  |                        |                        |
  |                        |-- GET status ---------->|
  |                        |<-- "COMPLETED" --------|
  |                        |   (status: "completed")|
  |                        |                        |
  |                        |-- POST onCompleteUrl ->|
  |<-- webhook payload ----|                        |

Using a Provider Template

The simplest approach - specify a provider name and AsyncQueue configures polling automatically.

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "X-API-Key: async_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://queue.fal.run/fal-ai/flux/dev",
    "method": "POST",
    "headers": {
      "Authorization": "Key fal_your_key"
    },
    "body": "{\"prompt\": \"A sunset over mountains\"}",
    "provider": "fal",
    "onCompleteUrl": "https://your-app.com/api/image-ready"
  }'

Response:

{
  "task": {
    "id": "019d2b00-1234-7000-a000-000000000001",
    "status": "pending",
    "provider": "fal",
    "pollConfig": {
      "urlTemplate": "{startResult.body.status_url}",
      "interval": 3,
      "statusPath": "status",
      "doneValues": ["COMPLETED"],
      "failValues": ["FAILED"],
      "resultPath": "",
      "resultUrlTemplate": "{startResult.body.response_url}",
      "forwardAuth": true,
      "maxDuration": 600
    },
    "pollCount": 0
  }
}

Available providers: fal, replicate, runwayml, luma, elevenlabs-dubbing, stability-video. See Provider Templates for details on each.

Using a Custom pollConfig

For AI providers not in the template list, provide a custom pollConfig:

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "X-API-Key: async_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.custom-ai.com/v1/generate",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer custom_key"
    },
    "body": "{\"prompt\": \"Generate something\"}",
    "pollConfig": {
      "urlTemplate": "https://api.custom-ai.com/v1/jobs/{startResult.body.job_id}",
      "interval": 5,
      "statusPath": "status",
      "doneValues": ["done"],
      "failValues": ["error"],
      "resultPath": "output",
      "errorPath": "error_message",
      "forwardAuth": true,
      "maxDuration": 300
    },
    "onCompleteUrl": "https://your-app.com/api/done"
  }'

pollConfig Reference

Field	Type	Required	Default	Description
urlTemplate	string	Yes	-	URL to poll. Supports {startResult.body.<path>} template variables.
interval	number	No	5	Seconds between poll requests (1-60).
statusPath	string	Yes	-	Dot-notation path to the status field in the poll response (e.g., status, state).
doneValues	string[]	Yes	-	Status values that indicate completion (e.g., ["COMPLETED"], ["succeeded"]).
failValues	string[]	Yes	-	Status values that indicate failure (e.g., ["FAILED"], ["failed", "canceled"]).
resultPath	string	No	""	Dot-notation path to the result in the poll response. Empty string returns the full response.
errorPath	string	No	-	Dot-notation path to the error message in failure responses.
resultUrlTemplate	string	No	-	Separate URL to fetch the final result (e.g., fal.ai’s response_url).
forwardAuth	boolean	No	false	Forward the original Authorization/X-API-Key headers to poll requests.
maxDuration	number	No	600	Maximum seconds to poll before timing out.

Template Variables

Template variables are resolved after the initial HTTP call using data from the response:

• {startResult.body.<path>} - Extract a value from the initial response body (parsed as JSON). For example, {startResult.body.id} extracts the id field.
• {startResult.body.status_url} - Some providers like fal.ai return the full status URL in their response.

Examples:

• RunwayML: "urlTemplate": "https://api.dev.runwayml.com/v1/tasks/{startResult.body.id}"
• Replicate: "urlTemplate": "https://api.replicate.com/v1/predictions/{startResult.body.id}"
• fal.ai: "urlTemplate": "{startResult.body.status_url}" (uses the full URL from the response)

Task Lifecycle

A polling task goes through these states:

Status	Description
pending	Task created, waiting to be processed
processing	Initial HTTP call to the AI provider’s submit endpoint
polling	Periodically checking the provider’s status endpoint
completed	AI provider returned a success status
failed	AI provider returned a failure status, or all retries exhausted
timeout	Polling exceeded maxDuration without a result
cancelled	Task was cancelled (polling tasks can be cancelled)

Retrieving Results

Once the task completes, the result contains the AI provider’s output:

curl https://api.asyncqueue.io/v1/tasks/019d2b00-1234-7000-a000-000000000001 \
  -H "X-API-Key: async_your_key"

{
  "task": {
    "id": "019d2b00-1234-7000-a000-000000000001",
    "status": "completed",
    "provider": "fal",
    "pollCount": 4,
    "startResult": {
      "statusCode": 200,
      "body": "{\"request_id\": \"abc-123\", \"status_url\": \"...\"}",
      "duration": 234
    },
    "result": {
      "statusCode": 200,
      "body": "{\"images\": [{\"url\": \"https://v3.fal.media/files/...\", \"width\": 1024}]}",
      "duration": 0
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": "2025-01-15T10:30:14.000Z"
  }
}

The startResult field contains the response from the initial submit call (the provider’s job ID and metadata). The result field contains the final output.

Use Cases

• Image generation - fal.ai Flux, Stability AI, Replicate models
• Video generation - RunwayML Gen-4, Luma AI Dream Machine
• Audio dubbing - ElevenLabs dubbing and translation
• Model inference - Any Replicate model (text-to-image, image-to-video, upscaling)
• Custom AI pipelines - Any API that follows a submit-then-poll pattern