Trinity
Trinity AI

中文

English

中文

English

创建视频生成任务 ​

向视频模型提交异步任务并查询结果。先 POST /video/generations 创建任务，再用 task_id 轮询 GET /video/tasks/{taskId}。

模型 ID 见 获取模型（modality=video）或 模型广场。

支持素材库的模型（例如 Seedance）可先 登记视频素材，再在首尾帧或参考字段中传 asset://vidast_…；也可直接传公网 HTTPS URL（是否自动登记因模型而异）。

Endpoint ​

MethodURL说明
POST{TRINITY_BASE_URL}/video/generations创建视频生成任务
GET{TRINITY_BASE_URL}/video/tasks/{taskId}查询任务状态与结果

Base URL ​

项值
Base URLhttps://api.trinitydesk.ai/v1
协议HTTPS
bash
export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"
export TRINITY_API_KEY="xh-..."

Headers ​

Header必填说明
Authorization是Bearer <TRINITY_API_KEY>
Content-Type创建时application/json

请求示例 ​

文生视频 ​

bash
curl -sS "${TRINITY_BASE_URL}/video/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "kling-2.6",
    "prompt": "黄昏海边慢跑，电影感",
    "duration_sec": 5,
    "aspect_ratio": "16:9"
  }'

图生视频（首尾帧） ​

bash
curl -sS "${TRINITY_BASE_URL}/video/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "kling-2.6",
    "prompt": "镜头从城市全景推进到街道特写",
    "duration_sec": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "frame_images": [
      {
        "type": "image_url",
        "frame_type": "first_frame",
        "image_url": { "url": "https://example.com/first.png" }
      },
      {
        "type": "image_url",
        "frame_type": "last_frame",
        "image_url": { "url": "https://example.com/last.png" }
      }
    ]
  }'

引用已登记素材（asset://） ​

bash
curl -sS "${TRINITY_BASE_URL}/video/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "seedance-2.0-os",
    "prompt": "镜头从城市全景推进到街道特写",
    "duration_sec": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "frame_images": [
      {
        "type": "image_url",
        "frame_type": "first_frame",
        "image_url": { "url": "asset://vidast_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
      }
    ]
  }'

vidast_… 来自 登记 / 查询视频素材 的响应字段 id。

查询任务 ​

bash
curl -sS "${TRINITY_BASE_URL}/video/tasks/vidtsk_xxx" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}"

请求体字段 ​

字段类型必填说明
modelstring是视频模型 ID
promptstring条件无素材时必填
duration_secinteger否时长（秒），默认 5，受模型能力限制
resolutionstring否如 480p、720p、1080p
aspect_ratiostring否如 16:9、9:16、1:1
generate_audioboolean否是否生成音频，默认 false
frame_imagesarray否首帧 / 尾帧图；image_url.url 可为 HTTPS 或 asset://vidast_…
input_referencesarray否参考图 / 参考视频；URL 字段可为 HTTPS 或 asset://vidast_…
model_specific_configobject否模型专属参数（如 seed、enhance_prompt）

frame_images、input_references、model_specific_config 的完整字段见 视频生成 · 高级参数。素材登记见 登记 / 查询视频素材。

返回字段 ​

创建响应 ​

字段类型说明
trinity_task.task_idstring任务 ID，形如 vidtsk_xxx
trinity_task.modestring固定 "async"
trinity_task.statusstring初始为 "queued"
trinity_task.poll_urlstring轮询路径 /v1/video/tasks/{taskId}
trinity_task.poll_interval_secinteger建议轮询间隔（秒）

查询响应 ​

字段类型说明
task_idstring任务 ID
statusstring任务状态（见下表）
billing_statusstring结算状态：billed / billing_in_progress
modelstring模型 ID
result_urlstring视频结果 URL（status=succeeded 时有值）
error_codestring错误码（status=failed 时有值）
error_messagestring错误描述

任务状态 ​

status说明
queued排队中
running生成中
succeeded生成成功，可读取 result_url
failed生成失败，可读取 error_code / error_message

返回示例 ​

创建成功 ​

json
{
  "trinity_task": {
    "mode": "async",
    "status": "queued",
    "task_id": "vidtsk_xxx",
    "poll_url": "/v1/video/tasks/vidtsk_xxx",
    "poll_interval_sec": 8
  }
}

查询 · 生成中 ​

json
{
  "task_id": "vidtsk_xxx",
  "status": "running",
  "model": "kling-2.6"
}

查询 · 生成成功 ​

json
{
  "task_id": "vidtsk_xxx",
  "status": "succeeded",
  "billing_status": "billed",
  "model": "kling-2.6",
  "result_url": "https://..."
}

查询 · 生成失败 ​

json
{
  "task_id": "vidtsk_xxx",
  "status": "failed",
  "model": "kling-2.6",
  "error_code": "upstream_task_failed",
  "error_message": "..."
}

轮询建议 ​

  • 创建响应中的 poll_interval_sec 为建议轮询间隔（默认 8 秒）
  • 视频生成通常需要 1~5 分钟，建议最多轮询 75 次
  • status 为 succeeded 或 failed 后停止轮询
  • status=succeeded 但 billing_status 非 billed 时，可继续轮询等待结算完成

错误码 ​

HTTP 状态码code说明
400invalid_request请求体格式错误或缺少必填字段
400model_not_supported_on_interface模型不支持视频生成
401authentication_errorAPI Key 缺失或无效
402insufficient_balance余额不足
404model_not_found模型未找到
404task_not_found任务 ID 不存在
429rate_limit_exceeded速率限制

完整错误码见 错误与调试。

Python 示例 ​

python
import os
import time
import requests

# 创建任务
r = requests.post(
    f"{os.environ['TRINITY_BASE_URL']}/video/generations",
    headers={
        "Authorization": f"Bearer {os.environ['TRINITY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-2.6",
        "prompt": "黄昏海边慢跑，电影感",
        "duration_sec": 5,
        "aspect_ratio": "16:9",
    },
    timeout=120,
)
r.raise_for_status()
task = r.json()["trinity_task"]
task_id = task["task_id"]
poll_interval = task.get("poll_interval_sec", 8)
print(f"Task created: {task_id}")

# 轮询查询
while True:
    time.sleep(poll_interval)
    q = requests.get(
        f"{os.environ['TRINITY_BASE_URL']}/video/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['TRINITY_API_KEY']}"},
        timeout=60,
    )
    q.raise_for_status()
    result = q.json()
    status = result.get("status")
    print(f"Status: {status}")
    if status in ("succeeded", "failed"):
        if status == "succeeded":
            print(f"Video URL: {result.get('result_url')}")
        else:
            print(f"Error: {result.get('error_code')} - {result.get('error_message')}")
        break

相关 ​

© Trinity AI

© Trinity AI