Skip to main content
The unified async task API provides a standardized submit → poll → retrieve workflow, abstracting away provider-specific differences.

​
Overview

AI tasks such as video generation, image generation, and music generation can take anywhere from tens of seconds to several minutes. To ensure a good user experience and system stability, these tasks are handled through an async task API:
  1. Submit a task — Send a generation request and immediately receive a task ID
  2. Poll for status — Use the task ID to check progress, or receive a callback notification
  3. Retrieve results — Once complete, get the generated resource URLs from the response

​
Supported Models

ProviderExample ModelsType
Klingkling-v2, kling-v1-6Video / Image
Lumaluma-ray-2, luma-photonVideo
Runwayrunway-gen4Video
RunwayMLrunwayml-gen3a-turboVideo
Veo (Google)veo-3Video
Minimaxminimax-video-01Video
Viduvidu-2.0Video
Jimengjimeng-v2Video / Image
Doubao (VolcEngine)doubao-seedance-1-0-proVideo
Flux (BFL)flux-pro, flux-kontext-proImage
Replicatereplicate/*Image / Video
Xai (Grok)grok-2-imageVideo
Ali (Alibaba)wanx-v2Image / Video
The above are examples. Check the Models page for currently available models. The input parameters vary by model — click on any model in the list to view its detailed documentation.

​
Submit a Task

POST /v1/task/submit

​
Request Parameters

FieldTypeRequiredDescription
modelstringYesModel name
inputobjectYesModel-specific generation parameters
callback_urlstringNoWebhook URL for task status updates

​
Request Examples

curl -X POST https://api.elkapi.com/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3/text-to-video",
    "input": {
      "prompt": "A golden retriever running under cherry blossom trees, slow motion, cinematic",
      "duration": "5",
      "aspect_ratio": "16:9"
    },
    "callback_url": "https://your-server.com/webhook/task"
  }'

​
Response Example

{
  "id": "task_abc123",
  "status": "queued",
  "created_at": 1711234567
}

​
Query a Task

GET /v1/task/{task_id}

​
Request Examples

curl https://api.elkapi.com/v1/task/task_abc123 \
  -H "Authorization: Bearer $API_KEY"

​
Response Examples

Task in progress: 
{
  "id": "task_abc123",
  "status": "in_progress",
  "created_at": 1711234567
}
Task completed: 
{
  "id": "task_abc123",
  "status": "completed",
  "created_at": 1711234567,
  "completed_at": 1711234620,
  "outputs": [
    "https://cdn.example.com/video/result.mp4"
  ]
}
Task failed: 
{
  "id": "task_abc123",
  "status": "failed",
  "created_at": 1711234567,
  "completed_at": 1711234590,
  "error": "Content policy violation detected"
}

​
Task Statuses

StatusDescription
queuedTask submitted, waiting to be processed
in_progressTask is currently being generated
completedTask finished — results available in outputs
failedTask failed — reason available in error

​
Callback Notifications

When you include a callback_url in your submit request, the system will send a POST request to that URL whenever the task status changes. The callback body uses the same format as the query response: 
{
  "id": "task_abc123",
  "status": "completed",
  "created_at": 1711234567,
  "completed_at": 1711234620,
  "outputs": [
    "https://cdn.example.com/video/result.mp4"
  ]
}
  • The callback URL must be publicly accessible over HTTPS
  • Callback requests have a 10-second timeout
  • Callback URLs cannot point to localhost, 127.0.0.1, or the platform’s own domain
  • Even with callbacks enabled, implement polling as a fallback to avoid missing notifications due to network issues

​
Complete Polling Example

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.elkapi.com/v1"

# 1. Submit task
submit_resp = requests.post(
    f"{BASE_URL}/task/submit",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-v3/text-to-video",
        "input": {
            "prompt": "A golden retriever running under cherry blossom trees",
            "duration": "5",
            "aspect_ratio": "16:9",
        },
    },
)

task = submit_resp.json()
task_id = task["id"]
print(f"Task submitted: {task_id}")

# 2. Poll until complete
while True:
    resp = requests.get(
        f"{BASE_URL}/task/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    result = resp.json()
    status = result["status"]
    print(f"Status: {status}")

    if status == "completed":
        print("Results:", result["outputs"])
        break
    elif status == "failed":
        print("Failed:", result.get("error", "Unknown error"))
        break

    time.sleep(5)

​
Response Fields

FieldTypeDescription
idstringUnique task identifier
statusstringTask status: queued / in_progress / completed / failed
created_atintegerTask creation time (Unix timestamp in seconds)
completed_atintegerTask completion time (Unix timestamp in seconds), only present when completed or failed
outputsstring[]List of result URLs (video/image/audio), only present when completed
errorstringError message, only present when failed

​
Notes

  • Authentication uses standard Authorization: Bearer <API_KEY> headers
  • The input parameters vary by model — click on the model in the Models page to view its documentation
  • Recommended polling interval is 3–10 seconds to avoid excessive requests
  • Resource URLs in task results may have expiration limits — download and save promptly

Video Models

Provider-specific video generation API documentation

Image Models

Image generation API documentation