API
CLUB

Uika H3 Flex

Uika H3 Flex 参考生视频:根据图片、视频和音频参考,生成带原生音频的 5 至 15 秒视频,支持 480p、768p,或增强至 1080p、2K、4K。除输出秒数外,参考视频也按秒计费。

pika/pika-h3-flex/reference-to-video

能力

最适合

  • •电影感文生视频镜头
  • •社交媒体短片与广告
  • •连贯的多镜头片段
  • •视觉开发与风格探索

不适合

  • •逐帧精确转描
  • •长篇视频渲染
  • •像素级精确合成
  • •准确呈现画面文字

身份验证

API 密钥标头

Uika API 使用 API 密钥来验证请求。将您的密钥发送到 X-API 密钥 标题。API 密钥必须保密,不要暴露在浏览器或其他客户端代码中。请从服务端调用 API。登录后的试玩使用控制台会话,不会发送你的 API 密钥。

标题
X-API-Key: YOUR_API_KEY

端点

异步·轮询结果

发布https://api.dev.pika.art/v1/media/pika/pika-h3-flex/reference-to-video生成端点
获取https://api.dev.pika.art/v1/media/jobs/{request_id}民意调查直至完成
获取https://api.dev.pika.art/v1/media/jobs/{request_id}/content输出 URL,适用于仅保留 id 的客户端
删除https://api.dev.pika.art/v1/media/jobs/{request_id}删除存储的媒体并提示

REST 接入

标准 HTTPS

视频 通过上方 REST 接口生成。API 使用 HTTPS 传输标准 JSON,可搭配任意 HTTP 客户端,无需厂商专用 SDK。

生成

POST /v1/media/pika/pika-h3-flex/reference-to-video

请求

curl -X POST https://api.dev.pika.art/v1/media/pika/pika-h3-flex/reference-to-video \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A 15-second multi-shot product commercial for the chunky clear lip gloss tube with crimson jelly gloss from reference image 1 (exact same faceted clear cap, ridged neck and deep crimson gloss, no label), served like a luxury dessert.\nSHOT 1 (0-3s): Overhead crane move descending onto a duck-egg blue table as a polished silver cloche lifts off a white plate, revealing the pink panna cotta with the gloss tube resting on it. The cloche's mirror surface reflects only the pale blue room and soft light — no people, no camera, no crew reflected anywhere.\nSHOT 2 (3-6s): Extreme macro side angle: the panna cotta wobbles gently, light rolling across its glossy surface and through the crimson gloss inside the clear tube.\nSHOT 3 (6-10s): Hard cut to a clean, empty, seamless pale duck-egg blue background — no plate, no dessert, nothing else in frame. The gloss tube floats upright in soft light and opens by itself: the faceted clear cap slowly unscrews and lifts away, drawing the applicator wand up out of the tube, a thick glossy string of crimson gloss stretching between the doe-foot tip and the tube neck and catching the light. Slow-motion macro, camera arcing smoothly around it. No hands, no people.\nSHOT 4 (10-12s): Same clean duck-egg blue background: macro on the glossy crimson doe-foot applicator tip, a single drop of gloss gathering and glistening, light refracting through the faceted cap.\nSHOT 5 (12-15s): Hard cut back to the table: low dolly gliding across and settling on the final hero frame exactly like reference image 1.\nSOUND: refined restaurant ambience, the metallic lift of the cloche, a soft wobble, the satisfying twist-and-pull sound of the cap opening, a glossy stretch, then a chic playful French-pop instrumental. LOOK: high-end cinematic beauty/tech commercial, editorial and refined, Jacquemus / Loewe campaign energy. Soft pale true-colour grounds against deep saturated hero colours, large soft diffused light, shadows soft but present, low-to-moderate contrast, creamy highlights, subtle 35mm film grain, shallow depth of field, anamorphic feel. CAMERA is always moving with bold confident motion — dollies, macro orbits, crane moves, motion blur on fast moves — never static. Product always tack-sharp and recognisable. Hard cuts between shots, each shot a different angle and scale, one clear story from start to end. Correct real-world physics. NO text, NO titles, NO captions, NO logos, NO subtitles anywhere. Audio: no voiceover, no dialogue, only a polished commercial soundtrack plus crisp tactile sound design.",
"duration": 15,
"resolution": "768p",
"seed": 0,
"rewrite": true,
"output_mode": "video",
"channel_mode": "stereo",
"references": [
{
"type": "image",
"url": "https://example.com/input.png"
},
{
"type": "video",
"url": "https://example.com/reference.mp4"
},
{
"type": "audio",
"url": "https://example.com/input.mp3"
}
]
}'

返回数据

{
"id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
"status": "queued"
}

请求正文

提示词字符串需要
提示词
持续时间整数5 – 15默认: 5
视频时长为 5 至 15 秒的整数。
aspect_ratioenum
输出画面比例。Auto 根据原始提示词和参考视频自动选择,即使 rewrite 为 false 也生效;有关键帧时遵循首张关键帧。固定比例始终优先。省略时,启用改写则自动选择;未改写则遵循首张关键帧,无关键帧时为 16:9。关键帧将缩放并居中裁切以适配。
分辨率枚举
480p 和 768p 为原生分辨率。选择 1080p、2K 或 4K 时,先生成 768p,再用 V1 模型增强一次,并保留音频与帧率。
种子整数0 – 9223372036854776000默认: 0
种子
rewrite布尔值默认: true
生成前优化提示词;关闭则使用原始提示词。
output_modeenum
audio-stems 返回带音频的原始视频,以及对白、配乐、音效、拟音、环境声 WAV 文件。生产环境支持 Flex,测试环境支持全部 H3 系列。使用标准保留期,并加收模型目录中的分离费用。Flex 按所有解码后输出音轨的时长总和计费,不乘声道数。默认仅返回视频。
channel_modeenum
仅针对音频分轨:stereo 保留双声道,mono 先混为单声道再分离;视频原始音频不变。
object[]1 – 12需要
有序参考媒体:最多 9 个图像、3 个视频和 3 个音频文件,总共 12 个。至少需要一张图像或视频。每个文件的大小限制为 24 MiB,base64 的总大小限制为 64 MiB(大约 48 MiB 原始文件)。图片必须为 PNG、JPEG 或 WebP,源像素最多 4000 万;超过 1600 万像素的图像会按比例调整大小。视频大小根据模型的像素预算按比例调整;源限制为每帧 1600 万像素、总像素 40 亿和 2000 帧。剪辑的时长必须为 2-15 秒,每种视频/音频类型的总时长最多为 15 秒。参考重写使用图像预览和稀疏视频帧,而不是音频转录。

接受的值

aspect_ratio
分辨率
output_mode
channel_mode
参考文献[].type

返回

返回一个 工作对象 状态 ,不是最终输出。存储响应中的 ID 并轮询作业直至完成。

民意调查状态

获取/v1/media/jobs/{request_id}

请求

curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
-H "X-API-Key: YOUR_API_KEY"

返回数据

{
"id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
"status": "running"
}

按 ID 轮询作业,直到达到最终状态:已完成或失败。已完成的作业在输出中携带其下载 URL,并且 GET /v1/media/jobs/{request_id}/content 返回与 { "url" } 对于只保留 ID 的客户端。

DELETE /v1/media/jobs/{request_id} 删除作业的存储介质以及提交时捕获的请求(提示和参数)。然后作业报告 deleted_at 并且没有输出,内容端点回答410。

作业对象

id字符串
作业的唯一标识符。
状态枚举
作业的状态。其中之一:
对象
生成输出。工作完成后立即出现。
错误字符串
如果作业失败,则失败的原因。
deleted_atnumber
当您删除作业的存储媒体时,以纪元秒为单位。在此之前为空,一旦设置后输出为空。
用法对象
提供者为作业报告的单位,例如 video_output_tokens 或 image_output_tokens。一旦作业终止就存在,仅携带作业报告的单位,并且当没有报告任何内容时为空。
对象
工作收费。工作结束后在场;提交响应和 webhooks 上为 null。

错误

在通话中共享

错误使用传统的 HTTP 状态代码以及形状的 JSON 主体 {"message": "..."}. 参数校验失败时返回 422 并带有一条命名有问题字段的消息。作业行存在后提交拒绝(余额、速率限制)返回失败的作业信封 — 分支 error.code.

状态当身体
401 未经授权API 密钥丢失或无效。{"message":"Invalid API key"}
403 禁止非活动密钥被拒绝 {"message"} 身体。作业行存在并返回失败的作业信封后,组织余额或后付费周期限制无法覆盖的提交将被拒绝。 GET /billing/balance 将两者分开: 200 表示密钥处于活动状态,因此拒绝的是余额或循环限制。{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}}
404 未找到您的组织中不存在具有该 ID 的作业,或者媒体路径名称未知的供应商/型号/功能。{"message":"media job not found"}
409冲突在作业完成之前请求结果,或者将 Idempotency-Key 标头与不同的正文重用。{"message":"media job is not ready"}
422 无法处理的实体请求正文验证失败:枚举值无效、缺少必填字段、类型错误或 JSON 格式错误。 JSON 消息命名有问题的字段。无法定价的架构有效参数组合在创建作业后失败,并返回失败的作业信封和错误代码 invalid_input.{"message":"duration: Input should be less than or equal to 15"}
429 请求太多您已达到每分钟或每天的请求限制,或者您组织的作业队列已满。作为失败的作业信封返回。如果存在 Retry-After 标头,请等待那么长时间,然后使用新的 Idempotency-Key 重试。{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}}
503服务不可用模型导轨或后端依赖项暂时不可用。作为失败的作业信封退回;使用退避和新的幂等密钥重试。{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}}