Runway Gen4 Image API

Runway Gen4 image generation API for text-to-image and reference-guided image workflows

Overview

Runway Gen4 Image generates still images from text prompts and optional reference images. Use it for higher-quality image generation when you need explicit aspect ratio, resolution, and seed controls.

Capability	Value
Model ID	runway-gen4-image
Modes	text-to-image, image-to-image
Prompt	Required non-empty string
Reference images	Required for image-to-image; optional for text-to-image; 1-3 public image URLs when provided
Aspect ratios	1:1, 16:9, 9:16, 4:3, 3:4
Resolution tiers	720p, 1080p
Seed	Integer from 1 through 2147483647

Endpoint and authentication

Base URL:

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

Method	Endpoint	Purpose
POST	/generateTask/runway-gen4-image	Submit an image generation task
GET	/statusTask/runway-gen4-image?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-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A cinematic product photo of a silver running shoe on wet asphalt",
      "aspect_ratio": "4:3",
      "resolution": "1080p"
    }
  }'

Successful response:

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

Save the taskId; you need it to poll for the final result.

Poll for result

curl -X GET "https://api.apixo.ai/api/v1/statusTask/runway-gen4-image?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-image.png\"]}",
    "createTime": 1782980000000,
    "completeTime": 1782980020000,
    "costTime": 20000
  }
}

Request body

Text-to-image

{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A fashion editorial portrait with dramatic side lighting",
    "aspect_ratio": "3:4",
    "resolution": "1080p",
    "seed": 123456
  }
}

Text-to-image with optional references

{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "Use the reference composition but render it as a studio product photo",
    "image_urls": [
      "https://example.com/reference-1.png"
    ],
    "aspect_ratio": "4:3",
    "resolution": "1080p"
  }
}

Image-to-image

{
  "request_type": "async",
  "input": {
    "mode": "image-to-image",
    "prompt": "Keep the shoe silhouette but place it in a clean studio scene",
    "image_urls": [
      "https://example.com/reference-1.png"
    ],
    "aspect_ratio": "4:3",
    "resolution": "1080p"
  }
}

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 Image input parameters.

Show properties

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

Generation mode. Supported values: text-to-image, image-to-image. If omitted, APIXO uses image-to-image when image_urls is non-empty; otherwise it uses text-to-image.

prompt · string · required

Text prompt describing the desired image. The prompt must be a non-empty string after trimming whitespace.

image_urls · string[]

Reference image URLs. Required for image-to-image. Optional for text-to-image. When provided in any mode, the array must contain 1 to 3 public, directly accessible image URLs.

aspect_ratio · string · default: "4:3"

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

resolution · string · default: "1080p"

Output resolution tier. Supported values: 720p, 1080p.

seed · integer

Optional seed. Must be a JSON integer from 1 through 2147483647; decimal values and quoted strings are not valid.

Response format

Submit task response

POST /generateTask/runway-gen4-image 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 image 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-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "image-to-image",
      "prompt": "Create a premium catalog image using this product reference",
      "image_urls": [
        "https://example.com/reference-1.png"
      ],
      "resolution": "1080p",
      "aspect_ratio": "4:3"
    }
  }'

See Webhooks for delivery requirements and retry behavior.

Billing

Runway Gen4 Image is billed per generated image. text-to-image and image-to-image use the same price for the same resolution.

Resolution	APIXO price
720p	$0.05 / image
1080p	$0.08 / image

Latency and polling

Actual latency may vary by prompt complexity, reference image accessibility, resolution, and current queue load.

Resolution	Typical generation time	Recommended first poll	Poll interval
720p	15s-30s	15s after task creation	3s-5s
1080p	20s-45s	20s after task creation	3s-5s

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

Validation notes

Parameter	Backend behavior
input.mode	Optional. Supported values are text-to-image and image-to-image. If omitted, non-empty image_urls selects image-to-image; otherwise text-to-image.
input.prompt	Required string. Must not be empty after trimming whitespace.
input.image_urls	Required for image-to-image. Optional for text-to-image. When present, must be an array with 1-3 non-empty string URLs.
input.aspect_ratio	Optional. Defaults to 4:3. Must be one of 1:1, 16:9, 9:16, 4:3, 3:4.
input.resolution	Optional. Defaults to 1080p. Must be 720p or 1080p.
input.seed	Optional JSON integer. Must be from 1 through 2147483647.

Errors and troubleshooting

Code	Meaning	What to do
400	Invalid request body, mode, parameter value, or input 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
• Image Models
• Generate Task
• Status Task
• Webhooks
• Error Codes
• Parameter Specification
• Routing Strategies
• Pricing