Runway API Text to Video: A Developer Guide to Gen-4.5 via hiapi

Why Use a Hosted Text-to-Video Endpoint

Text-to-video is not a replacement for image generation or editing pipelines — it is a different primitive. An image model gives you a still you can crop, retouch, or composite. A text-to-video call gives you motion: camera movement, subject action, and lighting that changes across time. If your product needs a clip — a short marketing beat, an in-app background loop, a previsualization of a scene — a single request-to-clip call is often the fastest path from idea to asset.

The trade-off is control. You are describing motion in words rather than keyframing it, so the model interprets. That makes prompt quality matter more than in image work, and it makes iteration loops matter more than one-shot attempts.

A hosted endpoint via hiapi removes the infrastructure work around that primitive: you get one consistent interface, one credential model, and one response shape across the video models you call. You spend your time on prompts and product integration instead of on storage plumbing, job polling, and per-provider SDKs.

Where this fits well:

• Short clips generated on demand from user input or templates
• Rapid concept exploration before committing to a full production pipeline
• Background and B-roll assets where a slightly imperfect take is still useful

Where it fits poorly: anything needing frame-accurate continuity, deterministic output, or long-form narrative coherence. Plan for several candidate clips per usable result.

How the runway-gen-4.5/text-to-video Endpoint Is Structured

Conceptually, a request to runway-gen-4.5/text-to-video has three parts: the prompt, the request-level settings, and your identity/authorization. Only the first is creative. The other two determine how the model runs and how you are billed.

What you send

• A prompt string. The primary creative input — subject, action, camera, lighting, and mood in plain language.
• Request-level settings. Aspect ratio, duration, and any generation flags the endpoint exposes. These shape the container of the output rather than its content.
• Auth headers. Your hiapi key, sent with every call. Treat it as a secret; never ship it in client-side code.

What comes back

Video generation is not instantaneous, so expect either a job handle to poll or a response that resolves to a media URL, depending on how the endpoint is invoked. In either case you receive a reference to a generated clip, not the raw bytes inline. Download and persist the asset to your own storage if you need it beyond the lifetime of the returned URL.

A useful mental model: the endpoint is a function that maps (prompt, settings) to a clip plus metadata. Your integration should treat it as asynchronous, retryable, and non-deterministic — the same inputs will not always yield the same clip, and that is expected behavior rather than a bug.

Keep request construction boring. Build one small internal wrapper that assembles the payload, attaches auth, sends the call, and normalizes the response into { status, videoUrl, error }. Every later section of this guide assumes that wrapper exists.

Writing Cinematic Prompts That Survive Motion

Vague adjectives collapse in motion. "A beautiful cinematic shot of a city" gives the model nothing to animate, so it produces something generic and drifting. The fix is to specify the four things a camera operator would need: subject, camera, light, and motion.

Name the subject and the action

Say what is on screen and what it is doing across the clip. State a start and an implied end so the model has a trajectory.

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

Direct the camera explicitly

Use camera language the model can map to motion: slow push-in, static wide shot, handheld follow, low-angle tracking, slow pan right, aerial descent. One camera move per clip is safer than three competing moves.

Static wide shot, camera at ground level, no zoom.

Specify lighting and time of day

Lighting drives most of the perceived production value. Give a source and a quality: overcast diffused daylight, hard late-afternoon sun from camera left, practical neon at night with wet reflections.

Describe motion that is physically plausible

Fast motion in a short clip tends to smear. Prefer a single readable action at moderate speed over many rapid events. If you want energy, get it from camera movement and light rather than from a dozen things happening at once.

Keep it to one paragraph

A compact paragraph of one to three sentences outperforms a bulleted spec sheet. Write it as a shot description, not a wish list. Avoid stacked style adjectives; pick one look and commit.

A reliable template:

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

Rewrite your prompt into that template before you change any settings.

A Working Request, Step by Step

This walkthrough assumes Node.js and a wrapper function, but the shape is language-agnostic.

Step 1: Write the shot

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

Step 2: Choose request settings

Pick an aspect ratio that matches where the clip will live, and the shortest duration that tells the story. Short clips fail fast and cost less to explore.

Step 3: Send the call

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

Step 4: Resolve the clip

If the response carries a job handle, poll until it reaches a terminal state with a small backoff. If it carries a media URL directly, skip to step 5.

Step 5: Persist the asset

Download the clip and store it under your own key. Treat the returned URL as ephemeral.

Step 6: Record the decision points

Log the prompt, the settings, and the resulting asset together. This log is what makes the next section — tuning — tractable instead of guesswork.

Tuning Output Without Changing the Prompt

When a clip disappoints, the instinct is to rewrite the prompt. Resist it for one round. Prompt and settings are separate variables, and changing both at once destroys your ability to learn which one mattered.

Isolate the variable

Hold the prompt fixed and change exactly one request-level setting — aspect ratio, duration, or a generation flag. Re-run. If the clip improves, the problem was structural, not creative. If it does not, revert the setting and move to the prompt.

Use settings for structural problems

• Composition wrong for the destination? Change aspect ratio.
• Action cut off before it resolves? Increase duration.
• Everything drifting and unmoored? Shorten the clip so there is less time to drift.

Use prompt edits for content problems

• Subject wrong or missing? Name it earlier and make it concrete.
• Camera wandering? Remove every camera word except the one move you want.
• Flat and lifeless? Add a lighting source and direction.

Run a small A/B

Keep a fixed seed prompt and generate three variants that each change one clause. Compare them side by side rather than from memory. Non-determinism means a single bad clip is not evidence; look for a pattern across two or three runs before you conclude a clause is hurting.

Write down the conclusion in the same log you already keep. Over a dozen iterations this becomes a prompt-and-settings playbook specific to your product, which is far more valuable than any generic prompt list.

Debugging Common Failures

Most first-week failures fall into four classes. Each has a different triage path.

Rejected or blocked requests

A non-2xx response with a policy message means the prompt or settings were not accepted. Read the error body rather than retrying blindly. Rewrite the offending description, remove named real people or brands, and resend. Log the rejected prompt verbatim — recurring rejections usually trace to one habit in your prompt template.

Timeouts

Video generation is slow. If your HTTP client times out before the endpoint responds, the job may still be running and billable. Raise client timeouts for generation calls and move polling into a background worker rather than holding a request open.

Empty or unusable clips

A successful response with a clip that has no discernible subject usually means the prompt was too abstract. Re-read it against the subject-camera-light-motion template. If one of the four is missing, that is your fix.

Auth and configuration errors

401 and 403 mean the key, not the prompt. Confirm the key is present in the runtime environment, not just your local shell, and confirm the header format. These failures are cheap to find early and expensive to find in production.

A general rule: classify the error before you change anything. Prompt-shaped errors, settings-shaped errors, and infrastructure-shaped errors need different fixes, and mixing them wastes generation budget.

Cost, Latency, and Production Guardrails

Before you ship, decide how the endpoint behaves when things go wrong, because video generation is the most expensive and slowest call in most products.

Budget by clip, not by call

Billing for video is generally tied to the length of output, so a longer clip costs more than a shorter one. Budget in units of finished clips — including retries and rejected candidates — rather than counting API calls. Set a per-user and per-session cap on generations. Current rates live on the pricing panel; do not hardcode them into business logic.

Design for latency

Never block a user-facing request on generation. Kick off the job, return a handle immediately, and deliver the clip through polling, a webhook, or a notification. Show progress in the UI so a slow render reads as work in progress rather than a hang. Cache generated clips by prompt and settings so repeated requests do not regenerate.

Validate before you generate

Cheap checks before the call save expensive ones after:

• Enforce a minimum and maximum prompt length in your wrapper
• Reject prompts missing a subject or an action
• Verify aspect ratio against your render targets
• Confirm the user is within their quota

Moderate on the way in and out

Run a text check on the prompt before sending. Run a light check on the returned clip before showing it. Both are cheaper than a support incident.

Keep a fallback

If generation fails or takes too long, serve a static poster frame or a placeholder clip rather than an error. The feature should degrade, not break.

Start with one endpoint, one wrapper, and one log; add guardrails as you learn where your product actually fails, and let the pricing panel stay the single source of truth for cost.