How to Structure a First Runway Text-to-Video API Job

A Runway text-to-video request starts a task. Your application stores the task identifier, checks progress and copies the video from the output URL after success. The URL is temporary.

Worked example

Example Runway request body

{
  "model": "veo3.1",
  "promptText": "A stationary camera shows a yellow paper boat drifting across a shallow puddle.",
  "ratio": "1280:720",
  "duration": 8
}

Local success fixture

{
  "id": "9e53a0a0-83e0-4af1-a654-7aa8b2e6ade7",
  "status": "SUCCEEDED",
  "output": ["https://example.com/test-output.mp4"]
}

Steps

  1. Choose a short prompt you have rights to use. Check the API reference for a current text-to-video model and the supported ratio and duration before submitting any request.
  2. Use the JSON as a local fixture for your job handler. In a live integration, submit the body to the text-to-video endpoint using server-side credentials and persist the returned ID before checking status.
  3. Test the pending and successful branches with canned responses. Download a successful result to durable storage and save that path on the job.

What to check

  • Mock the download when using the example URL. A pending task should have no saved asset path.
  • Keep API credentials on the server. Review provider pricing before live submissions.

See the Runway listing

References