Agent skill

runway

Runway ML API for AI video generation. Use when user mentions "Runway", "Runway ML", "AI video", "Gen-2", or video generation.

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/runway

SKILL.md

Runway API

Use the Runway API via direct curl calls to generate AI videos from images, text, or video inputs.

Official docs: https://docs.dev.runwayml.com/

When to Use

Use this skill when you need to:

  • Generate video from images (image-to-video)
  • Generate video from text prompts (text-to-video)
  • Transform existing videos (video-to-video)
  • Generate images from text (text-to-image)
  • Upscale video resolution (4X upscale)
  • Generate sound effects or speech

Prerequisites

  1. Sign up at Runway Developer Portal
  2. Purchase credits ($10 for 1000 credits)
  3. Create an API key in the dashboard
  4. Store it in the environment variable RUNWAY_TOKEN
bash
export RUNWAY_TOKEN="your-api-key"

Pricing

  • Credits are consumed per generation
  • ~25 credits per 5-second video

How to Use

All examples below assume you have RUNWAY_TOKEN set.

Base URL: https://api.dev.runwayml.com/v1

Required headers for all requests:

  • Authorization: Bearer ${RUNWAY_TOKEN}
  • X-Runway-Version: 2024-11-06
  • Content-Type: application/json

1. Check Organization Credits

Check your credit balance:

bash
curl -s -X GET "https://api.dev.runwayml.com/v1/organization" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06"

2. Image to Video

Generate a video from an image:

Write to /tmp/runway_request.json:

json
{
  "model": "gen4_turbo",
  "promptImage": "https://example.com/your-image.jpg",
  "promptText": "A timelapse of clouds moving across the sky",
  "ratio": "1280:720",
  "duration": 5
}

Then run:

bash
curl -s -X POST "https://api.dev.runwayml.com/v1/image_to_video" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json

Response:

json
{
  "id": "task-id-here"
}

3. Text to Video

Generate a video from text only:

Note: Text-to-video only supports duration values of 4, 6, or 8 seconds (not arbitrary values like image-to-video).

Write to /tmp/runway_request.json:

json
{
  "model": "veo3.1",
  "promptText": "A serene forest with sunlight filtering through the trees",
  "ratio": "1280:720",
  "duration": 6
}

Then run:

bash
curl -s -X POST "https://api.dev.runwayml.com/v1/text_to_video" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json

4. Video to Video

Transform an existing video:

Write to /tmp/runway_request.json:

json
{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source-video.mp4",
  "promptText": "Add magical sparkles and fairy dust effects",
  "ratio": "1280:720"
}

Then run:

bash
curl -s -X POST "https://api.dev.runwayml.com/v1/video_to_video" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json

5. Text to Image

Generate images from text:

Write to /tmp/runway_request.json:

json
{
  "model": "gen4_image_turbo",
  "promptText": "A futuristic cityscape at sunset",
  "ratio": "1920:1080",
  "referenceImages": []
}

Then run:

bash
curl -s -X POST "https://api.dev.runwayml.com/v1/text_to_image" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json

6. Check Task Status

Poll for task completion. Replace <your-task-id> with the actual task ID:

bash
curl -s -X GET "https://api.dev.runwayml.com/v1/tasks/<your-task-id>" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06"

Response when complete:

json
{
  "id": "task-id",
  "status": "SUCCEEDED",
  "output": ["https://cdn.runwayml.com/generated-video.mp4"]
}

Possible statuses: PENDING, RUNNING, SUCCEEDED, FAILED

7. Cancel a Task

Cancel a running task. Replace <your-task-id> with the actual task ID:

bash
curl -s -X DELETE "https://api.dev.runwayml.com/v1/tasks/<your-task-id>" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06"

8. Video Upscale (4X)

Upscale video resolution:

Write to /tmp/runway_request.json:

json
{
  "model": "upscale_v1",
  "videoUri": "https://example.com/low-res-video.mp4"
}

Then run:

bash
curl -s -X POST "https://api.dev.runwayml.com/v1/video_upscale" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json

9. Generate Sound Effects

Generate audio from text:

Write to /tmp/runway_request.json:

json
{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunder rumbling in the distance"
}

Then run:

bash
curl -s -X POST "https://api.dev.runwayml.com/v1/sound_effect" --header "Authorization: Bearer $(printenv RUNWAY_TOKEN)" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json

Available Models

Endpoint Models
Image to Video gen4_turbo, gen3a_turbo, veo3.1, veo3
Text to Video veo3.1, veo3.1_fast, veo3
Video to Video gen4_aleph
Text to Image gen4_image_turbo, gen4_image
Video Upscale upscale_v1

Aspect Ratios

Common ratios for video generation:

  • 1280:720 (16:9 landscape)
  • 720:1280 (9:16 portrait)
  • 1024:1024 (1:1 square)

Guidelines

  1. Poll for completion: Video generation is async; poll /tasks/{id} until status is SUCCEEDED
  2. Use appropriate models: gen4_turbo is faster, gen4_aleph for video-to-video
  3. Download promptly: Output URLs may expire after some time
  4. Monitor credits: Check /organization endpoint to track usage
  5. Handle rate limits: API returns 429 when rate limited; add delays

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

vm0-ai/vm0-skills

brave-search

Brave Search API for web search. Use when user says "search web", "Brave search", or asks to "find on web" without specifying Google.

50 8
Explore
vm0-ai/vm0-skills

supadata

Supadata API for YouTube/web data. Use when user mentions "Supadata", "YouTube data", "channel stats", or web scraping data.

50 8
Explore
vm0-ai/vm0-skills

roadmap-planning

Build and prioritize product roadmaps using scoring models like RICE, ICE, and value-effort matrices. Activate when creating a product roadmap, prioritizing features, sequencing initiatives, mapping dependencies, balancing team capacity, choosing between Now/Next/Later or quarterly planning, or communicating roadmap tradeoffs to executives and stakeholders.

50 8
Explore
vm0-ai/vm0-skills

qdrant

Qdrant API for vector search. Use when user mentions "Qdrant", "vector database", "semantic search", or embeddings storage.

50 8
Explore
vm0-ai/vm0-skills

calendly

Calendly scheduling API. Use when user mentions "Calendly", "calendly.com", "schedule a meeting", "booking link", "event types", or asks about interview scheduling.

50 8
Explore
vm0-ai/vm0-skills

stripe

Stripe API for payments. Use when user mentions "Stripe", "payment", "subscription", "billing", "invoice", or asks about payment processing.

50 8
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results