跳转到主要内容
统一异步任务接口提供标准化的提交 → 轮询 → 获取结果流程,屏蔽不同厂商 API 差异。

概述

视频生成、图片生成、音乐生成等 AI 任务通常需要几十秒甚至数分钟才能完成。为保障用户体验与系统稳定性,这些任务统一通过异步任务接口处理:
  1. 提交任务 — 发送生成请求,立即获得任务 ID
  2. 查询状态 — 使用任务 ID 轮询进度,或通过回调地址接收通知
  3. 获取结果 — 任务完成后从响应中获取生成的资源 URL

支持的模型

厂商模型示例类型
Kling (可灵)kling-v2, kling-v1-6视频/图片
Lumaluma-ray-2, luma-photon视频
Runwayrunway-gen4视频
RunwayMLrunwayml-gen3a-turbo视频
Veo (Google)veo-3视频
Minimaxminimax-video-01视频
Viduvidu-2.0视频
Jimeng (即梦)jimeng-v2视频/图片
Doubao (豆包)doubao-seedance-1-0-pro视频
Flux (BFL)flux-pro, flux-kontext-pro图片
Replicatereplicate/*图片/视频
Xai (Grok)grok-2-image视频
Ali (阿里)wanx-v2图片/视频
以上为示例,实际可用模型以平台 模型列表 为准。input 中的参数因模型而异,请在模型列表中点击对应模型进入详情页查看文档。

提交任务

POST /v1/task/submit

请求参数

字段类型必填说明
modelstring模型名称
inputobject模型所需的生成参数(因模型而异)
callback_urlstring任务状态变更时的回调地址

请求示例

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": "一只金色的柴犬在樱花树下奔跑,慢镜头,电影质感",
      "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.elkapi.com/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.elkapi.com/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)

响应字段说明

字段类型说明
idstring任务唯一标识
statusstring任务状态:queued / in_progress / completed / failed
created_atinteger任务创建时间(Unix 时间戳,秒)
completed_atinteger任务完成时间(Unix 时间戳,秒),仅在完成/失败时返回
outputsstring[]生成结果的 URL 列表(视频/图片/音频),仅在 completed 时返回
errorstring错误信息,仅在 failed 时返回

注意事项

  • 使用标准 Authorization: Bearer <API_KEY> 鉴权
  • input 中的参数因模型而异,请在 模型列表 中点击对应模型查看详情文档
  • 建议轮询间隔 3~10 秒,避免过于频繁的请求
  • 任务结果中的资源 URL 可能有有效期限制,建议及时下载保存

相关链接

视频模型

各视频模型的官方 API 格式文档

图片模型

各图片模型的 API 格式文档