Async Workflow

ViralAPI uses an asynchronous task processing model. All image generation requests are non-blocking — you submit a task and poll for results.

Task Lifecycle

┌─────────┐     ┌────────────┐     ┌───────────┐
│ pending  │ ──> │ processing │ ──> │ completed │
└─────────┘     └────────────┘     └───────────┘


                 ┌──────────┐
                 │  failed  │
                 └──────────┘

Status

Description

progress

results

pending

Task queued, waiting to be processed

0

[]

processing

Image generation in progress

1-99

[]

completed

Generation finished successfully

100

[url, ...]

failed

Generation failed

0

[]

Polling Strategy

Polling Intervals

Phase
Recommended Interval

First 10 seconds

2 seconds

10-60 seconds

3-5 seconds

After 60 seconds

10 seconds

Node.js Example

Error Handling

When a task fails or the API returns an error, the response follows a consistent structure:

Retry Strategy

Error Code
Retry?
Strategy

400

No

Fix request parameters

401

No

Check/refresh API key

402

No

Top up account balance

403

No

Check model access permissions

404 (task)

No

Task expired, create a new one

500

Yes

Retry with exponential backoff

502

Yes

Retry after 30 seconds

503

Yes

Retry after 60 seconds

Image URL Expiration

Generated image URLs in the results array are valid for 24 hours. Download and store them in your own storage before they expire.

Last updated