Integrating Runway ML API in .NET: a complete guide

About Runway ML

Runway AI, Inc. was founded in 2018 in New York, USA. They build generative AI tools for creative professionals — video, image, and audio generation. Their flagship product is the Gen-series video generation model, exposed via a REST API at api.dev.runwayml.com/v1.

The API is production-ready and used by studios, startups, and indie developers globally. It authenticates via a Bearer token in the Authorization header and requires the X-Runway-Version header (e.g. 2024-11-06) on every request.

Available models

Runway provides three current model variants under the seedance2 family. The older gen3a_turbo is deprecated — it returns 403 errors on /text_to_video and 400 errors on /image_to_video. Do not use it in new projects.

All three models support:

• Text to video and image to video
• Multi-image input (up to 9 images)
• Optional audio generation
• Duration: 5–15 seconds
• Aspect ratios: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
• Output resolutions: 480p, 720p, 1080p

Aspect ratios and pixel dimensions

Runway does not accept generic ratio strings like 16:9 directly. You must pass exact pixel dimension strings (e.g. 1280:720). The resolution determines which dimensions are valid.

In your code, implement a mapping function that takes (aspectRatio, outputResolution) and returns the correct pixel string. Passing an invalid or unrecognized value results in a 400 error from the API.

Pricing and credits

Runway charges in credits. You purchase credit packs, and each generation consumes credits based on model, duration, resolution, and whether audio is enabled.

Always verify current pricing at runwayml.com/pricing before estimating production costs. Runway adjusts rates as models evolve.

Approximate credit cost per video

Audio generation adds roughly 1 credit per second of video. A 10-second video with audio costs approximately 10 additional credits on top of the base generation cost. If cost is a concern, offer users an audio toggle and default it to false.

How the API works

Runway's video generation API is asynchronous. You do not receive a video file immediately. Instead:

1. POST to /text_to_video or /image_to_video with your parameters
2. Receive a task_id in the response
3. Poll GET /tasks/{task_id} repeatedly until status changes
4. When status is SUCCEEDED, download the video from the output URL
5. Re-host the video in your own storage — Runway's output URLs are temporary

Task status values

Key request fields

Important: For image-to-video with a single image, pass promptImage as a plain base64 data URI string. For multiple images (up to 9), pass an array of objects: [{"uri":"data:image/jpeg;base64,..."}]. Passing plain strings inside an array returns a 400 error.

Integration architecture in .NET

In an ASP.NET Core application, use a layered approach:

1. Service layer — IRunwayMLService

Encapsulate all Runway HTTP calls behind an interface. Register it in DI. Methods needed:

• CreateTaskAsync(request, endpoint, cancellationToken) — POST to Runway, returns task ID
• GetTaskStatusAsync(taskId, cancellationToken) — GET task status and progress
• DownloadVideoAsync(videoUrl, cancellationToken) — download completed video bytes

2. Controller layer — VideoGenerationController

Accept user input via [FromForm], validate parameters, call the service, and stream progress back to the client using Server-Sent Events (SSE).

3. Storage layer — Cloudflare R2 or S3

Once generation completes, download the video from Runway's temporary URL and store it in your own object storage. Never return Runway's output URL directly to clients — it expires.

4. Database layer — EF Core

Persist the task ID, status, and final video URL. Poll and update the record as the task progresses. Index on RunwayTaskId (unique) and UserId for fast lookups.

SSE polling strategy

Video generation takes 30 seconds to several minutes. A simple HTTP response will time out. Use Server-Sent Events to stream live progress to the client without holding a blocking connection.

Adaptive polling is the key to avoiding the most common failure — socket timeout when progress stalls at ~90–95%:

Only write to the database when status or progress actually changes — avoid unnecessary writes on every poll iteration.

Environment variables you need

Never hardcode secrets. Store all credentials as environment variables and read them at runtime.

In development, use appsettings.Development.json or dotnet user-secrets. In production (Azure App Service, etc.), set these as Application Settings environment variables. Never commit secrets to source control.

Common errors and how to fix them

Implementation checklist

1. Register HttpClient with a 10-minute timeout in Program.cs for the Runway service
2. Read the API key from environment variables — never from committed config files
3. Validate duration is between 5 and 15 seconds — Runway rejects values outside this range
4. Map aspect ratio + resolution to the correct pixel dimension string before calling the API
5. Implement adaptive SSE polling — 2s normally, 0.8s when progress ≥ 80%
6. Download and re-host the video in your own R2/S3 bucket — Runway output URLs expire
7. Persist task state in your database — only write when status or progress actually changes
8. Handle multi-image input correctly — 1 image = string, 2–9 images = array of {"uri":"..."} objects
9. Offer an audio toggle and clearly communicate the added credit cost to users
10. Index your database on RunwayTaskId (unique) and UserId for efficient polling queries

Which model should you use?

For most applications, start with seedance2_fast. It strikes the right balance between speed, quality, and cost. Upgrade to seedance2 when users need maximum quality (ad production, portfolio exports). Use seedance2_mini for draft previews or high-volume non-critical workflows.

Recommended default configuration: seedance2_fast · 720p · 5 seconds · audio: false

This gives a solid user experience at roughly 10 credits per video (~$0.50–$0.70 USD), and users can opt into longer duration, higher resolution, or audio when they need it.

Runway ML's API evolves quickly. Always verify model names, pricing, and endpoint paths against the official documentation at docs.dev.runwayml.com before shipping to production.