统一异步任务接口提供标准化的提交 → 轮询 → 获取结果流程，屏蔽不同厂商 API 差异。
- 提交任务 — 发送生成请求，立即获得任务 ID
- 查询状态 — 使用任务 ID 轮询进度，或通过回调地址接收通知
- 获取结果 — 任务完成后从响应中获取生成的资源 URL
支持的模型
| 厂商 | 模型示例 | 类型 |
|---|
| Kling (可灵) | kling-v2, kling-v1-6 | 视频/图片 |
| Luma | luma-ray-2, luma-photon | 视频 |
| Runway | runway-gen4 | 视频 |
| RunwayML | runwayml-gen3a-turbo | 视频 |
| Veo (Google) | veo-3 | 视频 |
| Minimax | minimax-video-01 | 视频 |
| Vidu | vidu-2.0 | 视频 |
| Jimeng (即梦) | jimeng-v2 | 视频/图片 |
| Doubao (豆包) | doubao-seedance-1-0-pro | 视频 |
| Flux (BFL) | flux-pro, flux-kontext-pro | 图片 |
| Replicate | replicate/* | 图片/视频 |
| Xai (Grok) | grok-2-image | 视频 |
| Ali (阿里) | wanx-v2 | 图片/视频 |
以上为示例，实际可用模型以平台 模型列表 为准。input 中的参数因模型而异，请在模型列表中点击对应模型进入详情页查看文档。
提交任务
POST /v1/task/submit
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
model | string | 是 | 模型名称 |
input | object | 是 | 模型所需的生成参数（因模型而异） |
callback_url | string | 否 | 任务状态变更时的回调地址 |
请求示例
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": "一只金色的柴犬在樱花树下奔跑，慢镜头，电影质感",
"duration": "5",
"aspect_ratio": "16:9"
},
"callback_url": "https://your-server.com/webhook/task"
}'
响应示例
{
"id": "task_abc123",
"status": "queued",
"created_at": 1711234567
}
查询任务
GET /v1/task/{task_id}
请求示例
curl https://api.ephone.ai/v1/task/task_abc123 \
-H "Authorization: Bearer $API_KEY"
响应示例
任务进行中：
{
"id": "task_abc123",
"status": "in_progress",
"created_at": 1711234567
}
{
"id": "task_abc123",
"status": "completed",
"created_at": 1711234567,
"completed_at": 1711234620,
"outputs": [
"https://cdn.example.com/video/result.mp4"
]
}
{
"id": "task_abc123",
"status": "failed",
"created_at": 1711234567,
"completed_at": 1711234590,
"error": "Content policy violation detected"
}
任务状态
| 状态 | 说明 |
|---|
queued | 任务已提交，等待处理 |
in_progress | 任务正在生成中 |
completed | 任务完成，outputs 中包含结果 |
failed | 任务失败，error 中包含原因 |
回调通知
提交任务时传入 callback_url，当任务状态发生变更时，系统会向该地址发送 POST 请求，请求体与查询接口响应格式一致：
{
"id": "task_abc123",
"status": "completed",
"created_at": 1711234567,
"completed_at": 1711234620,
"outputs": [
"https://cdn.example.com/video/result.mp4"
]
}
- 回调地址必须是公网可访问的 HTTPS 地址
- 回调请求超时时间为 10 秒
- 回调地址不能指向
localhost、127.0.0.1 或平台自身域名
- 即使设置了回调，仍建议实现轮询作为兜底，避免因网络原因错过通知
完整轮询示例
import time
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.ephone.ai/v1"
# 1. 提交任务
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": "一只金色的柴犬在樱花树下奔跑",
"duration": "5",
"aspect_ratio": "16:9",
},
},
)
task = submit_resp.json()
task_id = task["id"]
print(f"任务已提交: {task_id}")
# 2. 轮询等待完成
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}")
if status == "completed":
print("生成结果:", result["outputs"])
break
elif status == "failed":
print("任务失败:", result.get("error", "Unknown error"))
break
time.sleep(5)
响应字段说明
| 字段 | 类型 | 说明 |
|---|
id | string | 任务唯一标识 |
status | string | 任务状态：queued / in_progress / completed / failed |
created_at | integer | 任务创建时间（Unix 时间戳，秒） |
completed_at | integer | 任务完成时间（Unix 时间戳，秒），仅在完成/失败时返回 |
outputs | string[] | 生成结果的 URL 列表（视频/图片/音频），仅在 completed 时返回 |
error | string | 错误信息，仅在 failed 时返回 |
注意事项
- 使用标准
Authorization: Bearer <API_KEY> 鉴权
input 中的参数因模型而异，请在 模型列表 中点击对应模型查看详情文档- 建议轮询间隔 3~10 秒，避免过于频繁的请求
- 任务结果中的资源 URL 可能有有效期限制，建议及时下载保存
相关链接