August 26, 2026AIExplore

How to Use the Runway API and Developer Integration

Integrate Runway Dev API generation with documented gen4.5 textToVideo calls, separate API billing, async handling, and prompt discipline.

Runway

The Runway Dev API lets you generate video programmatically outside the consumer app at app.runwayml.com. Official credit FAQs state web app credits are completely separate from API credits. The developer portal quickstart shows client.textToVideo.create with model gen4.5, promptText, ratio, duration, and seed, then waiting for task output. Portal materials list Gen-4.5 API pricing at $0.12 per second with up to 10 second duration and text or image inputs. Docs live at docs.dev.runwayml.com. Explore overview: /explore/runway.

This guide covers safe integration habits without inventing endpoints. Use only model ids and methods published in official docs. For creative prompting patterns that also apply in API promptText fields, see /blog/how-to-use-runway-text-to-video-generation and /blog/how-to-use-runway-image-to-video-generation.

App versus API

Creators on app subscriptions do not automatically receive API credits. Developers must fund API usage through the developer portal. Enterprise options exist for higher limits per official API pricing guidance.

Step by step developer workflow

1. Read official quickstart and auth docs

Create credentials in the developer portal. Follow current authentication instructions in Runway Dev docs. Do not copy unofficial SDK snippets that invent methods.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Integration checklist [ ] API key stored in secrets manager [ ] Official SDK or HTTP examples only [ ] Separate billing from app.runwayml.com [ ] Logging for prompt, model, duration, seed, task id. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Integration checklist [ ] API key stored in secrets manager [ ] Official SDK or HTTP examples only [ ] Separate billing from app.runwayml.com [ ] Logging for prompt, model, duration, seed, task id" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Inputs:
Use the actual source material required for this task, together with the intended audience, destination, format, and quality requirements. Specify relevant files, text, URLs, structured data, reference assets, dimensions, language, tone, timing, model or generation settings, credentials, field mappings, or integration values when they apply. Keep secrets out of the example and use the product's supported credential or configuration mechanism.

Workflow:
1. Start with one representative input that contains the important characteristics of the real workload.
2. Configure runway specifically for the requested task and make the important settings explicit.
3. Run the first pass and inspect the result against the objective.
4. Correct only the settings or source material responsible for a failed requirement instead of changing everything at once.
5. Validate the intermediate result before passing it to the next step.
6. When the result meets the requirements, save the successful configuration so the same process can be repeated consistently.
7. If this is a multi-step workflow, verify each handoff and keep a clear fallback or review path for failures.

Requirements:
The example must use supported functionality only. Do not invent product features, pricing, limits, integrations, model names, API behavior, or unavailable settings. Preserve important source data and formatting. Validate required fields before processing, handle empty or invalid input explicitly, prevent accidental duplicate processing where relevant, and stop or route the item for review when a required step fails. For credentials, use the supported secure configuration rather than placing secrets directly in the content.

Expected output:
The final result should directly satisfy the "Integration checklist [ ] API key stored in secrets manager [ ] Official SDK or HTTP examples only [ ] Separate billing from app.runwayml.com [ ] Logging for prompt, model, duration, seed, task id" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

2. Start with the documented textToVideo example shape

Official portal examples use textToVideo.create with model gen4.5. Keep ratio and duration within documented ranges. Prefer short durations while validating prompts.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Example shape from official quickstart style const task = await client.textToVideo.create({ promptText: "A cinematic slow push in across a sunlit kitchen as steam curls from a fresh cup of coffee, soft morning light, gentle natural motion.", model: "gen4.5", ratio: "1280:720", duration: 5, seed: 692126734 }).waitForTaskOutput();. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Example shape from official quickstart style const task = await client.textToVideo.create({ promptText: "A cinematic slow push in across a sunlit kitchen as steam curls from a fresh cup of coffee, soft morning light, gentle natural motion.", model: "gen4.5", ratio: "1280:720", duration: 5, seed: 692126734 }).waitForTaskOutput();" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Example shape from official quickstart style const task = await client.textToVideo.create({ promptText: "A cinematic slow push in across a sunlit kitchen as steam curls from a fresh cup of coffee, soft morning light, gentle natural motion.", model: "gen4.5", ratio: "1280:720", duration: 5, seed: 692126734 }).waitForTaskOutput();" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

3. Handle async completion and failures

Generations are asynchronous. Wait for task output using official helpers or documented status patterns. Retry transient failures with backoff. Persist seeds for reproducible tests when the API returns or accepts them.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Runtime checklist [ ] Timeout budget set [ ] Failed task ids retained [ ] Cost estimated as seconds * listed $/sec [ ] Outputs scanned for unwanted text or artifacts before publish. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Runtime checklist [ ] Timeout budget set [ ] Failed task ids retained [ ] Cost estimated as seconds * listed $/sec [ ] Outputs scanned for unwanted text or artifacts before publish" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Runtime checklist [ ] Timeout budget set [ ] Failed task ids retained [ ] Cost estimated as seconds * listed $/sec [ ] Outputs scanned for unwanted text or artifacts before publish" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

4. Mirror app prompt discipline in promptText

API quality still depends on motion clarity. Use the same visual plus motion structure as the web app. For image conditioned generations, follow official parameters for image inputs when your chosen model supports them.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: promptText template Subject + environment + lighting. Camera move + subject action + scene motion. Locks: no logos, no on screen text. One primary motion idea.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "promptText template Subject + environment + lighting. Camera move + subject action + scene motion. Locks: no logos, no on screen text. One primary motion idea." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "promptText template Subject + environment + lighting. Camera move + subject action + scene motion. Locks: no logos, no on screen text. One primary motion idea." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Practical API use cases

Marketing batch kitchen

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: promptText kitchen push in; model gen4.5; duration 5; ratio 1280:720; store seed; human QA before CMS upload.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "promptText kitchen push in; model gen4.5; duration 5; ratio 1280:720; store seed; human QA before CMS upload." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "promptText kitchen push in; model gen4.5; duration 5; ratio 1280:720; store seed; human QA before CMS upload." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Social vertical pipeline

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Generate 9:16 ratio supported by your model docs. Template prompt for neon rain street. Queue off peak. Review watermarks policy for your surface.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Generate 9:16 ratio supported by your model docs. Template prompt for neon rain street. Queue off peak. Review watermarks policy for your surface." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Generate 9:16 ratio supported by your model docs. Template prompt for neon rain street. Queue off peak. Review watermarks policy for your surface." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Seed locked A/B

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Same promptText, two seeds. Compare motion cleanliness. Keep winner seed in CMS metadata.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Same promptText, two seeds. Compare motion cleanliness. Keep winner seed in CMS metadata." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Same promptText, two seeds. Compare motion cleanliness. Keep winner seed in CMS metadata." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Duration ladder

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Test duration 5 then 8 then 10 only if sequenced actions need time. Estimate cost at $0.12/sec for Gen-4.5 per portal listing.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Test duration 5 then 8 then 10 only if sequenced actions need time. Estimate cost at $0.12/sec for Gen-4.5 per portal listing." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Test duration 5 then 8 then 10 only if sequenced actions need time. Estimate cost at $0.12/sec for Gen-4.5 per portal listing." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Prompt lint before send

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Reject promptText missing a camera verb or missing a subject. Save credits on empty motion.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Reject promptText missing a camera verb or missing a subject. Save credits on empty motion." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Reject promptText missing a camera verb or missing a subject. Save credits on empty motion." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Image conditioned when supported

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Follow official image input fields for the model. Do not invent parameter names.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Follow official image input fields for the model. Do not invent parameter names." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Follow official image input fields for the model. Do not invent parameter names." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Webhook style processing

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: On completion, transcode, virus scan if required, and push to object storage. Never expose API keys to browsers.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "On completion, transcode, virus scan if required, and push to object storage. Never expose API keys to browsers." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "On completion, transcode, virus scan if required, and push to object storage. Never expose API keys to browsers." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Enterprise limit planning

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: If self serve tiers are insufficient, use the official usage exception path described in API pricing docs.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "If self serve tiers are insufficient, use the official usage exception path described in API pricing docs." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "If self serve tiers are insufficient, use the official usage exception path described in API pricing docs." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Cost guardrail

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Hard cap daily seconds generated. Alert when approaching budget.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Hard cap daily seconds generated. Alert when approaching budget." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Hard cap daily seconds generated. Alert when approaching budget." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Creative ops mirror

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: Reuse the same prompt library as producers on app.runwayml.com so results feel consistent across surfaces.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "Reuse the same prompt library as producers on app.runwayml.com so results feel consistent across surfaces." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "Reuse the same prompt library as producers on app.runwayml.com so results feel consistent across surfaces." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

More examples

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: log line taskId | model | duration | ratio | seed | promptHash | status | costEstimate. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "log line taskId | model | duration | ratio | seed | promptHash | status | costEstimate" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "log line taskId | model | duration | ratio | seed | promptHash | status | costEstimate" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: safe default model gen4.5 | duration 5 | ratio 1280:720 | reject prompts over needless length. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "safe default model gen4.5 | duration 5 | ratio 1280:720 | reject prompts over needless length" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "safe default model gen4.5 | duration 5 | ratio 1280:720 | reject prompts over needless length" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: QA gate auto reject outputs with burned in UI text patterns before publish. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "QA gate auto reject outputs with burned in UI text patterns before publish" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "QA gate auto reject outputs with burned in UI text patterns before publish" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: secrets API key only on server. Rotate on schedule. Separate staging and production projects.. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "secrets API key only on server. Rotate on schedule. Separate staging and production projects." that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "secrets API key only on server. Rotate on schedule. Separate staging and production projects." requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Scenario:
A realistic runway workflow is being prepared for Use Runway Text to Video Generation using runway. The starting requirement is: docs first before adding a new model id, confirm it appears in official Runway Dev model listings. The work should be tested on a representative input first so the result can be reviewed before the same process is applied to the full project or production workload.

Objective:
Create a production-ready result for "docs first before adding a new model id, confirm it appears in official Runway Dev model listings" that directly supports the article use case. The output should be specific, reviewable, and reproducible rather than a generic demonstration. Keep the requested goal as the primary outcome and avoid adding unrelated features, assumptions, or unsupported capabilities.

Expected output:
The final result should directly satisfy the "docs first before adding a new model id, confirm it appears in official Runway Dev model listings" requirement and be understandable without guessing what was supplied or configured. A successful run should produce the intended output in the requested format, with the important values and workflow decisions clear enough to reproduce the result. If the workflow can fail, the expected behavior should also make the failure visible and provide a clear next action instead of silently producing an incomplete result.

Tips

Never assume app credits fund API calls
Use only documented model ids such as gen4.5 when listed
Estimate cost from official per second API prices
Keep prompt libraries shared with creative teams
Add human review for customer facing media
Watch developer portal usage dashboards

Limitations and verification

This article does not invent endpoints, SDK methods, or model ids beyond what official Runway Dev materials demonstrate. Always re check docs.dev.runwayml.com and the developer portal before shipping. API prices and available models can change.

Keep a short shot list beside your Runway session. Note model, duration, aspect ratio, and the one motion change you will try next. That habit saves credits when you iterate.

When a generation pauses or a plan limit appears, confirm your plan and remaining credits in the dashboard instead of guessing. Official Free plan help notes watermarks and a one time credit deposit.

Treat every clip as a draft until you review subject identity, flicker, and unwanted text. Export only after a full playback, not a frozen thumbnail.

If you collaborate, store winning prompts on a shared page with the seed when available. Reuse the prompt skeleton and change one variable at a time.

Match delivery early. A 9:16 social cut is harder to rescue from a 16:9 master than starting in the correct ratio.

Separate exploration from finals. Draft on lower cost models when they fit the mode, then spend Gen-4.5 credits once motion and framing are locked.

For client work, keep a verification note: no invented logos, no trademarked characters, and no claims the footage cannot support.

Close each session by archiving the best still or last frame for the next shot. Continuity across clips beats regenerating from memory.