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 查询的示例。假设我们有一个任务 IDe3d52b98-b944-438e-b122-1a9141b5626c。设置请求头和请求体请求头包括accept: 指定响应格式为 JSON设置为application/json。authorization: 调用 API 的密钥申请后可直接选取。请求体包括id: 上传的任务 ID。action: 任务的操作方法。设置示例如下图所示代码示例您可以在页面右侧看到多种语言的代码示例如下图所示CURL 示例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 示例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, jsonpayload, headersheaders) print(response.text)响应示例请求成功后API 将返回视频任务的详细信息示例响应如下{ _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 示例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 示例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, jsonpayload, headersheaders) print(response.text)常见问题当调用 API 时如果发生错误API 会返回相应的错误代码和消息。常见错误包括400 token_mismatched: 请求错误可能是由于缺少或无效参数。401 invalid_token: 未授权令牌无效或缺失。429 too_many_requests: 请求过多您已超出速率限制。500 api_error: 内部服务器错误服务器发生错误。错误响应示例{ success: false, error: { code: api_error, message: fetch failed }, trace_id: 2cf86e86-22a4-46e1-ac2f-032c0f2a4e89 }总结通过本文您了解了如何使用 Pixverse 任务 API 查询单个或批量视频任务的具体信息。希望这份文档能帮助您