DigitalOcean API (unofficial showcase)
POST/v1/async-invoke

Generate Image, Audio, or Text-to-Speech Using fal Models

Generate Image, Audio, or Text-to-Speech Using fal Models. This endpoint starts an asynchronous job and returns a request_id. The job status is QUEUED initially. Use the request_id to poll for the result.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 body fields
model_idstringrequired
The ID of the model to invoke asynchronously.
inputobjectrequired
The input parameters for the model invocation. Fields vary by model type. For **image generation** models (e.g., `fal-ai/flux/schnell`, `fal-ai/fast-sdxl`), use `prompt` along with optional image parameters like `output_format`, `num_inference_steps`, `guidance_scale`, `num_images`, and `enable_safety_checker`. For **audio generation** models (e.g., `fal-ai/stable-audio-25/text-to-audio`), use `prompt` along with `seconds_total` to control the duration. For **text-to-speech** models (e.g., `fal-ai/elevenlabs/tts/multilingual-v2`), use `text` with the content you want converted to speech.
tagsarray<object>optional
An optional list of key-value tags to attach to the invocation request for tracking or categorization.

6 status codes
200The async invocation completed synchronously.
request_idstringrequired
A unique identifier for the async invocation request. Use this ID to check the status and retrieve the result.
statusstringrequired
The current status of the async invocation.
Allowed:QUEUEDIN_PROGRESSCOMPLETEDFAILED
model_idstringrequired
The model ID that was invoked.
created_atstringrequired
The timestamp when the request was created.
started_atstringoptional
The timestamp when the job started processing. Null while queued.
completed_atstringoptional
The timestamp when the job completed. Null until finished.
outputobjectoptional
The output of the invocation. Null while the job is queued or in progress. Contains the result once completed.
errorstringoptional
Error message if the job failed. Null on success.
202The async invocation request was accepted.
request_idstringrequired
A unique identifier for the async invocation request. Use this ID to check the status and retrieve the result.
statusstringrequired
The current status of the async invocation.
Allowed:QUEUEDIN_PROGRESSCOMPLETEDFAILED
model_idstringrequired
The model ID that was invoked.
created_atstringrequired
The timestamp when the request was created.
started_atstringoptional
The timestamp when the job started processing. Null while queued.
completed_atstringoptional
The timestamp when the job completed. Null until finished.
outputobjectoptional
The output of the invocation. Null while the job is queued or in progress. Contains the result once completed.
errorstringoptional
Error message if the job failed. Null on success.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.