Async Tasks

Unified async task API for video generation, image generation, music generation and other long-running tasks.

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

Provider	Example Models	Type
Kling	kling-v2, kling-v1-6	Video / Image
Luma	luma-ray-2, luma-photon	Video
Runway	runway-gen4	Video
RunwayML	runwayml-gen3a-turbo	Video
Veo (Google)	veo-3	Video
Minimax	minimax-video-01	Video
Vidu	vidu-2.0	Video
Jimeng	jimeng-v2	Video / Image
Doubao (VolcEngine)	doubao-seedance-1-0-pro	Video
Flux (BFL)	flux-pro, flux-kontext-pro	Image
Replicate	replicate/*	Image / Video
Xai (Grok)	grok-2-image	Video
Ali (Alibaba)	wanx-v2	Image / 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

Field	Type	Required	Description
model	string	Yes	Model name
input	object	Yes	Model-specific generation parameters
callback_url	string	No	Webhook URL for task status updates

Request Examples

cURL

curl -X POST https://api.ephone.ai/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

curl https://api.ephone.ai/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

Status	Description
queued	Task submitted, waiting to be processed
in_progress	Task is currently being generated
completed	Task finished — results available in outputs
failed	Task 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"
  ]
}

1. The callback URL must be publicly accessible over HTTPS
2. Callback requests have a 10-second timeout
3. Callback URLs cannot point to localhost, 127.0.0.1, or the platform’s own domain
4. Even with callbacks enabled, implement polling as a fallback to avoid missing notifications due to network issues

---

Complete Polling Example

Python

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.ephone.ai/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

Field	Type	Description
id	string	Unique task identifier
status	string	Task status: queued / in_progress / completed / failed
created_at	integer	Task creation time (Unix timestamp in seconds)
completed_at	integer	Task completion time (Unix timestamp in seconds), only present when completed or failed
outputs	string[]	List of result URLs (video/image/audio), only present when completed
error	string	Error message, only present when failed

---

Notes

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

Related Links

Video Models

Provider-specific video generation API documentation

Learn more

Image Models

Image generation API documentation

Learn more