Pika Videos Generation API 对接说明

本文将介绍一种 Pika Videos Generation API 对接说明，它是可以通过输入自定义参数来生成Pika官方的视频。

申请流程

要使用 Pika Videos Generation API，首先到 Ace Data Cloud 控制台获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。

一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在控制台充值通用余额。

📘 完整文档：Pika Videos Generation API →

基本使用

首先先了解下基本的使用方式，就是输入提示词 prompt、生成行为 action、参考图片 image_url 以及模型 model，便可获得处理后的结果，首先需要简单地传递一个 action 字段，它的值为 generate，然后我们还需要输入模型，目前文生视频只支持 1.5，具体的内容如下：

可以看到这里我们设置了 Request Headers，包括：

accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。
authorization：调用 API 的密钥，申请之后可以直接下拉选择。

另外设置了 Request Body，包括：

model：生成视频的模型，支持 2.0、1.5，目前文生视频只支持 1.5，视频生视频只支持 2.0。
action：此次视频生成任务的行为，当前仅支持 generate。
effect：此次视频生成任务采用的官方特效，文生图/图生图时可选，见文末模版列表。
image_url：需要上传的参考图片链接或者 Base64 编码。
video_url：视频生视频模式下的参考视频链接。
aspect_ratio：宽高比，图片模式下不传；视频模式下按宽高比字符串填写。
prompt：提示词。
negative_prompt：需要规避的反向提示词。
callback_url：需要回调结果的 URL。
async：可选，设为 true 时接口立即返回 task_id，无需提供 callback_url，随后通过对应的任务查询接口轮询获取结果。

选择之后，可以发现右侧也生成了对应代码，如图所示：

点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：

{
  "success": true,
  "task_id": "1bc50b89-ce4e-4046-8297-0a2f39ed89ea",
  "trace_id": "b7dd6242-9367-4b49-b0af-f7748ab14447",
  "data": [
    {
      "id": "39a8723a-de78-4e7b-a2bd-59116c3d5d61",
      "state": "complete",
      "prompt": "moving",
      "model": "1.5",
      "quality": "720p",
      "video_url": "https://cdn.pika.art/v1/39a8723a-de78-4e7b-a2bd-59116c3d5d61/moving_seed1223321842.mp4",
      "image_url": "https://cdn.pika.art/v1/39a8723a-de78-4e7b-a2bd-59116c3d5d61/poster.jpg",
      "duration": 5
    }
  ]
}

返回结果一共有多个字段，介绍如下：

success，此时视频生成任务的状态情况。
task_id，此时视频生成任务ID。
trace_id，此时视频生成跟踪ID。
data，此时视频生成任务的结果列表。
- id，此时视频生成任务的视频ID。
- image_url，此时视频生成任务的封面链接。
- video_url，此时视频生成任务的视频链接。
- duration，此时视频生成任务的时长。
- state，此时视频生成任务的状态。

可以看到我们得到了满意的视频信息，我们只需要根据结果中 data 的视频链接地址获取生成的Pika视频即可。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

curl -X POST 'https://api.acedata.cloud/pika/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "effect": "Ta-da",
  "prompt": "moving",
  "model": "1.5"
}'

视频生视频任务

如果想视频生视频任务任务，首先参数video_url必须传入参考视频链接，此时 model 只支持 2.0，就可以指定如下内容：

effect：该视频生视频任务采用的特效，目前只支持：”Pink Hair”、”Its Computer”、”Its Alive”、”Duplicate it”、”Wizard Cat”。
model：此次生成视频任务所采用的模型，视频生视频任务目前支持者 2.0。
video_url：上传参考视频的视频链接。

填写样例如下：

填写完毕之后自动生成了代码如下：

对应的代码：

import requests

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

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

payload = {
    "action": "generate",
    "effect": "Pink Hair",
    "prompt": "moving",
    "model": "2.0",
    "video_url": "https://cdn.acedata.cloud/0slqxa.mp4"
}

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

点击运行，可以发现会立即得到一个结果，如下：

{
  "success": true,
  "task_id": "a852042b-987b-4378-8699-7c2d33b4f36d",
  "trace_id": "49944c40-e948-4640-a1b3-732379883203",
  "data": [
    {
      "id": "d4472f11-bbce-4512-8054-cab1c04e3a8b",
      "state": "complete",
      "prompt": "Pink Hair",
      "model": "Pro",
      "quality": "1080p",
      "video_url": "https://cdn.pika.art/v1/d4472f11-bbce-4512-8054-cab1c04e3a8b/Pink_Hair_seed776225645.mp4",
      "image_url": "https://cdn.pika.art/v1/d4472f11-bbce-4512-8054-cab1c04e3a8b/poster.jpg",
      "duration": 5.041666666666667
    }
  ]
}

可以看到，生成的效果是视频生建视频的，结果与上文类似。

异步回调

由于 Pika Videos Generation API生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成视频的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。

下面我们通过示例来了解下具体怎样操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下：

1
2
3

{
  "task_id": "c372e7bc-1877-4b6d-9732-e1b9e16c06c0"
}

稍等片刻，我们可以在 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab 上观察到生成歌曲的结果，如图所示：

内容如下：

{
    "success": true,
    "task_id": "c372e7bc-1877-4b6d-9732-e1b9e16c06c0",
    "trace_id": "781cc036-926b-44d2-83ea-4045bf8e85d4",
    "data": [
        {
            "id": "458d50a4-43d1-4339-927a-c2f7d43fa570",
            "video_url": "https://cdn.pika.art/v1/458d50a4-43d1-4339-927a-c2f7d43fa570/moving_seed3878215573.mp4",
            "image_url": "https://cdn.pika.art/v1/458d50a4-43d1-4339-927a-c2f7d43fa570/thumbnail.jpg",
            "duration": 5,
            "state": "succeeded"
        }
    ]
}

可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

目前所支持的模版id以及对应的效果：

图片模版

模版id
Bald Me
Looong Hair
Squish
Poke
Cake-ify
Baby Me
Inflate
Explode
Peel
Epic Me
Crush
Melt
Decapitate
Crumble
Ta-da
Princess Me
Warrior Me
Dissolve
Hero Me
Museum Me
Levitate
Deflate
Fairytale Me
Mrs Me
Eye-pop
VIP Me
Jungle Me
Puppy Me
Classy Me
Tear
Leprechaun Me
Royal Me
Captain Me
Rose
Mona Me
Zen Me
Cupid Strike
Hearts Bouquet
Love Bomb
Proposal
Crazy in Love

视频模版

模版id
Pink Hair
Its Computer
Its Alive
Duplicate it
Wizard Cat

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
401 invalid_token：Unauthorized, invalid or missing authorization token.
429 too_many_requests：Too many requests, you have exceeded the rate limit.
500 api_error：Internal server error, something went wrong on the server.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用 Pika Videos Generation API 可通过输入提示词以及参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。