Video Generation

Multi-provider video generation with async job support for long-running generations.

Supported Providers

Provider	Models	Max Duration	Key Features
OpenAI Sora	`openai/sora-2`, `openai/sora-2-pro`	90s	4K support, video-to-video
Runway	`runway/gen3a`, `runway/gen4`	10s	Camera control, keyframes
Kling	`kling/v1`	60s	Lip sync support
Pika	`pika/v1`	-	Fast generation

Basic Request

POST /v1/videos


{
  "prompt": "A person walking through a forest at sunset",
  "model": "runway/gen4",
  "duration": 10,
  "size": "1280x720",
  "fps": 24
}

Async Job Flow

Video generation may return immediately with a job status for long-running generations:

Initial Response (job queued)


{
  "code": 200,
  "data": {
    "id": "vid_abc123",
    "object": "video",
    "status": "queued",
    "created": 1735500000,
    "metadata": {
      "provider": "runway",
      "request_id": "req_123",
      "job_id": "runway_job_xyz"
    }
  }
}

Poll for Completion


GET /v1/videos/{video_id}

Completed Response


{
  "code": 200,
  "data": {
    "id": "vid_abc123",
    "object": "video",
    "status": "completed",
    "created": 1735500000,
    "completed_at": 1735500120,
    "file_id": "file_vid123",
    "file_url": "https://cdn.picklayer.com/...",
    "model": "runway/gen4",
    "usage": {
      "video_pixels": 88473600,
      "frames": 240,
      "width": 1280,
      "height": 720,
      "fps": 24,
      "duration": 10
    }
  }
}

Core Parameters

Parameter	Type	Default	Description
`prompt`	string	required	Text prompt
`model`	string	required	Provider-prefixed model ID
`size`	string	”1280x720”	Output resolution
`duration`	number	5	Duration in seconds
`fps`	number	24	Frames per second
`input_image`	string	-	First frame image (file ID)
`input_video`	string	-	Video-to-video input (file ID)

Provider-Specific Examples

Runway with Camera Control


{
  "prompt": "A person walking through a forest",
  "model": "runway/gen4",
  "input_image": "file_first_frame",
  "duration": 10,
  "camera_control": {
    "pan": "left",
    "tilt": "up",
    "zoom": "in",
    "intensity": 0.5
  }
}

OpenAI Sora Video-to-Video


{
  "prompt": "Transform into a watercolor painting style",
  "model": "openai/sora-2",
  "input_video": "file_source_video",
  "duration": 10,
  "size": "1920x1080"
}

Kling with Lip Sync


{
  "prompt": "A person speaking",
  "model": "kling/v1",
  "input_image": "file_face_image",
  "lip_sync_audio": "file_audio"
}

Provider Duration Limits

Provider	Min	Max	Notes
OpenAI Sora 2	-	90s	4K support
Runway Gen-3 Turbo	5s	10s	Requires input image
Runway Gen-3 Alpha	5s	10s	Text-to-video supported
Runway Gen-4	5s	10s	Highest fidelity
Kling v1	-	60s	Lip sync support

Provider Capability Comparison

Provider	Max Duration	Image Input	Video Input	Camera Control	Lip Sync
OpenAI Sora 2	90s	Yes	Yes	-	-
Runway Gen-3 Alpha	10s	Yes	-	Yes	-
Runway Gen-3 Turbo	10s	Yes (required)	-	Yes	-
Runway Gen-4	10s	Yes	Yes	Yes	-
Kling v1	60s	Yes	Yes	-	Yes

CDN Storage

Generated videos are automatically stored to PickLayer’s CDN:

file_id: PickLayer file ID for permanent storage
file_url: CDN URL for direct access (optional convenience)
Provider URLs or raw b64_json payloads are not returned in API responses
Use GET /v1/files/{file_id}/signed-url to fetch a fresh download URL
If storage is disabled or unavailable, responses may include url or b64_json instead

Download via Files API


GET /v1/files/{file_id}/signed-url


{
  "code": 200,
  "data": {
    "file_id": "file_vid123",
    "url": "https://cdn.picklayer.com/...",
    "expires_in": 3600
  }
}

Billing

Charged by output megapixel-frames (width x height x frames) or per-second depending on provider. Guard reserves before job starts and finalizes with actual usage.