Runway Gen4 Video Turbo API

Runway Gen4 image-to-video API with prompt guidance, one source image, and per-second billing

Overview

Runway Gen4 Video Turbo animates a source image into a short video using a text prompt. Use it when you already have an image and want controlled motion, camera direction, or atmosphere.

Capability	Value
Model ID	runway-gen4-video-turbo
Mode	image-to-video
Prompt	Required non-empty string
Source image	Exactly 1 public image URL
Duration	Integer or integer string from 5 through 10 seconds
Aspect ratios	16:9, 4:3, 1:1, 3:4, 9:16
Billing	Per second

Endpoint and authentication

Base URL:

https://api.apixo.ai/api/v1

Method	Endpoint	Purpose
POST	/generateTask/runway-gen4-video-turbo	Submit a video generation task
GET	/statusTask/runway-gen4-video-turbo?taskId={taskId}	Poll task status and retrieve results

All requests require your APIXO API key:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

curl -X POST "https://api.apixo.ai/api/v1/generateTask/runway-gen4-video-turbo" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "prompt": "The subject walks forward through soft morning fog, cinematic camera movement",
      "image_urls": [
        "https://example.com/source-image.png"
      ],
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

Successful response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

Poll for result

curl -X GET "https://api.apixo.ai/api/v1/statusTask/runway-gen4-video-turbo?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/runway-gen4-video-turbo.mp4\"]}",
    "createTime": 1782980000000,
    "completeTime": 1782980060000,
    "costTime": 60000
  }
}

Request body

Image-to-video

{
  "request_type": "async",
  "input": {
    "mode": "image-to-video",
    "prompt": "He lifts the noodles with chopsticks as steam curls around his face",
    "image_urls": [
      "https://example.com/source-image.png"
    ],
    "duration": "10",
    "aspect_ratio": "4:3"
  }
}

The mode field is optional on this endpoint. If omitted, APIXO uses image-to-video.

Parameters

request_type · string · default: "async"

Result delivery mode. Use async for polling with statusTask, or callback for webhook delivery.

callback_url · string

Required when request_type is callback. Must be a public HTTPS URL that can receive the final task payload. See Webhooks.

input · object · required

Runway Gen4 Video Turbo input parameters.

Show properties

mode · string · default: "image-to-video"

Optional generation mode. This endpoint supports image-to-video only.

prompt · string · required

Text prompt describing the desired motion, camera movement, and scene changes. The prompt must be a non-empty string after trimming whitespace.

image_urls · string[] · required

Source image URLs. Provide exactly 1 public, directly accessible image URL.

duration · integer | string · default: "5"

Output duration in seconds. Accepts a JSON integer or integer string from 5 through 10. Decimal values are not valid.

aspect_ratio · string

Optional output aspect ratio. Supported values: 16:9, 4:3, 1:1, 3:4, 9:16.

Response format

Submit task response

POST /generateTask/runway-gen4-video-turbo returns a task ID when the task is accepted:

code · integer

API status code. 200 means the task was accepted.

message · string

Human-readable status message.

data.taskId · string

Unique task identifier used with the status endpoint.

Status response fields

taskId · string

Unique task identifier.

state · string

Current task state: pending, processing, success, or failed.

resultJson · string

JSON string containing generated video URLs in resultUrls. Present when state is success.

failCode · string

Machine-readable failure code. Present when state is failed.

failMsg · string

Human-readable failure message. Present when state is failed.

createTime · integer

Task creation timestamp in Unix milliseconds.

completeTime · integer

Task completion timestamp in Unix milliseconds. Present after completion.

costTime · integer

Processing duration in milliseconds when available.

Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

curl -X POST "https://api.apixo.ai/api/v1/generateTask/runway-gen4-video-turbo" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "prompt": "Slow dolly-in, soft cinematic motion, rain on the window",
      "image_urls": [
        "https://example.com/source-image.png"
      ],
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

See Webhooks for delivery requirements and retry behavior.

Billing

Runway Gen4 Video Turbo is billed per output second.

Unit	APIXO price
Per second	$0.01 / second

Formula:

total cost = duration * 0.01

Latency and polling

Actual latency may vary by duration, prompt complexity, source image accessibility, and current queue load.

Duration	Typical generation time	Recommended first poll	Poll interval
5s	45s-75s	45s after task creation	5s
10s	75s-120s	60s after task creation	5s

For production video workloads, use callback mode to avoid frequent polling while generation is still running.

Validation notes

Parameter	Backend behavior
input.mode	Optional. If provided, it must be image-to-video. If omitted, APIXO uses image-to-video.
input.prompt	Required string. Must not be empty after trimming whitespace.
input.image_urls	Required. Must be an array with exactly 1 non-empty string URL.
input.duration	Optional. Defaults to 5. Accepts a JSON integer or integer string from 5 through 10; decimals are rejected.
input.aspect_ratio	Optional. If provided, must be one of 16:9, 4:3, 1:1, 3:4, 9:16.

Errors and troubleshooting

Code	Meaning	What to do
400	Invalid request body, missing source image, invalid duration, invalid aspect ratio, or inaccessible image URL	Fix the request before retrying
401	Missing or invalid API key	Check the Authorization header
402	Insufficient balance or quota	Add balance or switch account/key
403	Key or route cannot access the model	Check permissions and route strategy
429	Rate limit or concurrency limit reached	Retry with exponential backoff
500	Server error or unknown generation failure	Retry with backoff
502	Generation service or network error	Retry with backoff
504	Generation timeout	Retry or use callback mode for long-running jobs

See Error Codes for the full error reference.

Related links

• Generation API Overview
• Video Models
• Generate Task
• Status Task
• Webhooks
• Error Codes
• Parameter Specification
• Routing Strategies
• Pricing