Pika H3 Flex
Generate a video with native audio from ordered image, video and audio references. Choose any whole-second duration from 5 to 15, 480p or 768p resolution, and one of 11 aspect ratios. Prompt rewriting is enabled by default; set rewrite=false to use the original prompt. 1080p/2k/4k generates at 768p and upscales once with Pika Upsampler V1, preserving audio and frame rate. Combined pricing is per actual output second; the quote reserves the native frame-count duration bound. Reference video seconds are billed at the same rate in addition to output seconds; image and audio references add no duration charge.
pika/pika-h3-flex/reference-to-video
Capabilities
Best for
- •Cinematic text-to-video shots
- •Short social and ad clips
- •Consistent multi-shot sequences
- •Look-dev and style exploration
Not for
- •Frame-exact rotoscoping
- •Feature-length renders
- •Pixel-perfect compositing
- •Precise on-screen text
Authentication
api key header
The Pika API uses API keys to authenticate requests. Send your key in the X-API-Key header. Your API key is a secret. Don't expose it in browsers or other client-side code. Instead, call the API from your server. The signed-in playground uses a portal session and never sends your API key.
header
X-API-Key: YOUR_API_KEY
Endpoint
asynchronous · poll for the result
POSThttps://api.dev.pika.art/v1/media/pika/pika-h3-flex/reference-to-videogenerate endpoint
GEThttps://api.dev.pika.art/v1/media/jobs/{request_id}poll until completed
GEThttps://api.dev.pika.art/v1/media/jobs/{request_id}/contentthe output URL, for clients that only kept the id
DELETEhttps://api.dev.pika.art/v1/media/jobs/{request_id}erase the stored media and prompt
REST Setup
plain HTTPS
Video generation runs through the REST endpoint shown above. The API is plain JSON over HTTPS, so any HTTP client works. No provider-specific SDK is required.
Generate
POST /v1/media/pika/pika-h3-flex/reference-to-video
Request
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"}]}'
Response
{"id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status": "queued"}
Request body
promptstringrequired
Promptdurationinteger5 – 15default: 5
Video duration in whole seconds, from 5 to 15.aspect_ratioenum
Output aspect ratio. Auto selects from the original prompt and reference video, even when rewrite is false; with a keyframe it follows the first supplied keyframe. A fixed ratio always wins. When omitted, rewriting enables Auto; without rewriting, the first supplied keyframe sets the ratio, or 16:9 without a keyframe. Keyframes are resized and center-cropped to fit.resolutionenum
480p/768p are native. 1080p/2k/4k generates at 768p, then upscales once with the V1 model, preserving audio and frame rate.seedinteger0 – 9223372036854776000default: 0
Seedrewritebooleandefault: true
Improve the prompt before generation; disable to use the original prompt.output_modeenum
audio-stems (Flex in production, every H3 family in staging) returns the original video with audio plus Dialogue, Score, SFX, Foley and Ambience WAV files. Uses standard retention and adds the catalog's separation fee. Flex bills the sum of all decoded output-stem durations, without a channel multiplier. The default returns only the video.channel_modeenum
Audio stems only: stereo preserves both channels; mono downmixes before separation. The video's audio is unchanged.object[]1 – 12required
Ordered reference media: up to 9 images, 3 videos and 3 audio files, 12 total. At least one image or video is required. Each file is limited to 24 MiB, with a combined 64 MiB base64 limit (approximately 48 MiB raw). Images must be PNG, JPEG or WebP, up to 40 million source pixels; images above 16 million pixels are proportionally resized. Videos are proportionally resized to the model's pixel budget; source limits are 16 million pixels per frame, 4 billion total pixels and 2000 frames. clips must be 2–15 seconds, at most 15 seconds combined per video/audio type. Reference rewriting uses image previews and sparse video frames, not audio transcription.Accepted values
- aspect_ratio
- resolution
- output_mode
- channel_mode
- references[].type
Returns
Returns a job object with status , not the final output. Store the id from the response and poll the job until it completes.
Poll status
GET /v1/media/jobs/{request_id}
Request
curl https://api.dev.pika.art/v1/media/jobs/{request_id} \-H "X-API-Key: YOUR_API_KEY"
Response
{"id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status": "running"}
Poll the job by id until it reaches a terminal state: completed or failed. A completed job carries its download URL in output, and GET /v1/media/jobs/{request_id}/content returns that same URL as { "url" } for clients that only kept the id.
DELETE /v1/media/jobs/{request_id} erases the stored media for a job, and the request captured at submit (the prompt and parameters). The job then reports deleted_at and no output, and the content endpoint answers 410.
The job object
idstring
Unique identifier for the job.statusenum
The status of the job.One of:object
The generation output. Present once the job completes.errorstring
If the job failed, the reason for the failure.deleted_atnumber
When you deleted the job's stored media, in epoch seconds. Null until then, and output is null once it is set.usageobject
Units the provider reported for the job, such as video_output_tokens or image_output_tokens. Present once the job is terminal, carries only the units the job reports, and is null when nothing was reported.object
What the job charged. Present once the job is terminal; null on the submit response and on webhooks.Errors
shared across calls
Errors use conventional HTTP status codes with a JSON body of the shape {"message": "..."}. Validation failures return 422 with a message naming the offending field. Submit rejections after the job row exists (balance, rate limit) return the failed job envelope — branch on error.code.
| Status | When | Body |
|---|---|---|
| 401 Unauthorized | The API key is missing or invalid. | {"message":"Invalid API key"} |
| 403 Forbidden | An inactive key is rejected with a {"message"} body. A submit that the org balance or postpaid cycle limit cannot cover is rejected after the job row exists and returns the failed job envelope. GET /billing/balance separates the two: a 200 means the key is active, so the rejection was the balance or the cycle limit. | {"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}} |
| 404 Not Found | No job with that id exists in your org, or the media path names an unknown vendor/model/function. | {"message":"media job not found"} |
| 409 Conflict | The result was requested before the job completed, or an Idempotency-Key header was reused with a different body. | {"message":"media job is not ready"} |
| 422 Unprocessable Entity | The request body failed validation: an invalid enum value, a missing required field, a wrong type, or malformed JSON. The JSON message names the offending field. A schema-valid parameter combination that cannot be priced instead fails after job creation and returns the failed job envelope with error code invalid_input. | {"message":"duration: Input should be less than or equal to 15"} |
| 429 Too Many Requests | You've hit your per-minute or per-day request limit, or your org's job queue is full. Returned as the failed job envelope. If there's a Retry-After header, wait that long, then retry with a fresh Idempotency-Key. | {"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}} |
| 503 Service Unavailable | The model rail or a backend dependency is temporarily unavailable. Returned as the failed job envelope; retry with backoff and a fresh Idempotency-Key. | {"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}} |