Pixverse 任务 API 集成与使用指南

简介

Pixverse 任务 API 是 Ace Data Cloud 提供的一项服务，主要用于查询由 Pixverse 视频生成 API 生成的任务的执行状态。通过该 API，您可以轻松获取视频任务的进度和结果，进而更好地管理您的视频生成工作流。

本文将详细介绍如何集成和使用 Pixverse 任务 API，帮助您充分利用这一强大的功能。

环境准备/前置条件

注册 Ace Data Cloud 账号 ：访问 Ace Data Cloud 官网注册账号。
申请 Pixverse 视频生成 API：在申请页面获取相应服务。
获取任务 ID：使用 Pixverse 视频生成 API 时生成的任务 ID。

详细步骤

申请使用 Pixverse 任务 API

首先，您需要在 Pixverse 视频生成 API 申请页面上申请对应服务。生成任务 ID 后，请复制该 ID，如下图所示：

接下来，访问 Pixverse 任务 API 页面申请相应服务。页面加载后，点击"获取"按钮，如下图所示：

如果您尚未登录或注册，系统将自动重定向到登录页面，请注册并登录，随后会自动返回到当前页面。

首次申请用户可享有免费的使用配额。

请求示例

Pixverse 任务 API 可用于查询 Pixverse 视频生成 API 的结果。有关如何使用 Pixverse 视频生成 API 的详细信息，请参考 Pixverse 视频生成操作文档。

以下是使用任务 ID 查询的示例。假设我们有一个任务 ID：e3d52b98-b944-438e-b122-1a9141b5626c。

设置请求头和请求体

请求头包括：

accept: 指定响应格式为 JSON，设置为 application/json。
authorization: 调用 API 的密钥，申请后可直接选取。

请求体包括：

id: 上传的任务 ID。
action: 任务的操作方法。

设置示例如下图所示：

代码示例

您可以在页面右侧看到多种语言的代码示例，如下图所示：

CURL 示例

bash 复制代码

curl -X POST 'https://api.acedata.cloud/pixverse/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "e3d52b98-b944-438e-b122-1a9141b5626c",
  "action": "retrieve"
}'

Python 示例

python 复制代码

import requests

url = "https://api.acedata.cloud/pixverse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "prompt": "quiver"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

响应示例

请求成功后，API 将返回视频任务的详细信息，示例响应如下：

json 复制代码

{
  "_id": "6789f8ce550a4144a5a102e3",
  "id": "e3d52b98-b944-438e-b122-1a9141b5626c",
  "api_id": "2cc118fc-d019-4782-b02f-649df3b9f603",
  "application_id": "5723a03b-774d-479e-943e-f3c0f92d7b33",
  "created_at": 1737095374.496,
  "credential_id": "c65e346e-55b1-4c16-9370-6eff6e0a84a9",
  "request": {
    "action": "generate",
    "prompt": "quiver"
  },
  "trace_id": "ab568894-5536-4b47-97c6-8936fddf6ce7",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "e3d52b98-b944-438e-b122-1a9141b5626c",
    "trace_id": "ab568894-5536-4b47-97c6-8936fddf6ce7",
    "data": [
      {
        "id": 317384746578432,
        "first_frame": "",
        "video_width": 0,
        "video_height": 0,
        "prompt": "quiver",
        "model": "v3.5",
        "quality": "360p",
        "motion": "normal",
        "video_url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2F2c8425c5-f772-4add-ad73-e9265f68e336_seed0.mp4",
        "template_id": 0,
        "template_name": "",
        "style": "",
        "aspect_ratio": "16:9",
        "duration": 5,
        "extended": 0,
        "last_frame": "",
        "seed": 0,
        "asset_id": 0,
        "asset_name": ""
      }
    ]
  }
}

返回结果包含多个字段，其中 request 字段为任务发起时的请求体，response 字段为任务完成后返回的响应体。

批量查询操作

如果需要查询多个任务 ID 的详细信息，您可以选择操作为 retrieve_batch。

请求体包括：

ids: 上传的任务 ID 数组。
action: 任务的操作方法。

代码示例

CURL 示例

bash 复制代码

curl -X POST 'https://api.acedata.cloud/pixverse/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["e3d52b98-b944-438e-b122-1a9141b5626c","bb0b2c63-dbae-4536-97f7-aba9cd8c55fc"],
  "action": "retrieve_batch"
}'

Python 示例

python 复制代码

import requests

url = "https://api.acedata.cloud/pixverse/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "ids": ["e3d52b98-b944-438e-b122-1a9141b5626c","bb0b2c63-dbae-4536-97f7-aba9cd8c55fc"],
    "action": "retrieve_batch"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

常见问题

当调用 API 时，如果发生错误，API 会返回相应的错误代码和消息。常见错误包括：

400 token_mismatched: 请求错误，可能是由于缺少或无效参数。
401 invalid_token: 未授权，令牌无效或缺失。
429 too_many_requests: 请求过多，您已超出速率限制。
500 api_error: 内部服务器错误，服务器发生错误。

错误响应示例

json 复制代码

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

总结

通过本文，您了解了如何使用 Pixverse 任务 API 查询单个或批量视频任务的具体信息。希望这份文档能帮助您