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
- 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.
- 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.
- 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.