runway_skill

Overview

This skill provides curl-based access to the Runway AI API for generating and transforming video, image, and audio assets from text, images, or existing video. It focuses on practical, reproducible curl examples and the minimal request/response workflow needed to create, poll, cancel, and download generated outputs. Use it when you want programmatic, shell-based control over Runway video generation without an SDK.

How this skill works

Requests are sent to the Runway REST endpoints (base URL https://api.dev.runwayml.com/v1) with an API key in the Authorization header and a version header. Create jobs by POSTing JSON payloads to endpoints like /image_to_video, /text_to_video, /video_to_video, /text_to_image, /video_upscale, or /sound_effect. The API returns a task id; poll /tasks/{id} until the status is SUCCEEDED, then download the output URL(s).

When to use it

• Generate short AI videos from a single image (image-to-video) for motion effects or timelapses.
• Create videos directly from prompts (text-to-video) for storyboards or quick concept visuals.
• Apply stylistic or effect-based transforms to an existing clip (video-to-video).
• Upscale low-resolution footage by 4× for higher-quality exports.
• Produce sound effects or short speech audio from text prompts.
• Generate reference images from text for concept art or thumbnails.

Best practices

• Store RUNWAY_API_KEY in an environment variable and use bash -c when piping to avoid env-var loss in some shells.
• Always poll /tasks/{id} and handle statuses: PENDING, RUNNING, SUCCEEDED, FAILED.
• Choose models by use case (e.g., gen4_turbo for image-to-video, gen4_aleph for video-to-video).
• Keep promptImage or videoUri reachable via HTTPS and download outputs promptly because URLs can expire.
• Monitor organization credits via GET /organization and implement retry/backoff when receiving 429 rate-limit responses.

Example use cases

• Create a 5s timelapse video from a landscape photo using image_to_video with model gen4_turbo.
• Generate a 6s concept clip from a text prompt (veo3.1) for quick product demos or pitches.
• Apply magical particle effects to a source clip using video_to_video and gen4_aleph, then upscale the result.
• Produce a thunder SFX clip from a text description via the sound_effect endpoint for game assets.
• Batch-generate multiple thumbnails by calling text_to_image with gen4_image_turbo and different prompts.