> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Runway Gen4 Image

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

```text theme={null}
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:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

```bash theme={null}
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:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

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

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/runway-gen4-image?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Success response:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<ParamField body="request_type" type="string" default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Runway Gen4 Image input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="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`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Text prompt describing the desired image. The prompt must be a non-empty string after trimming whitespace.
    </ParamField>

    <ParamField body="image_urls" type="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.
    </ParamField>

    <ParamField body="aspect_ratio" type="string" default="4:3">
      Output aspect ratio. Supported values: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`.
    </ParamField>

    <ParamField body="resolution" type="string" default="1080p">
      Output resolution tier. Supported values: `720p`, `1080p`.
    </ParamField>

    <ParamField body="seed" type="integer">
      Optional seed. Must be a JSON integer from `1` through `2147483647`; decimal values and quoted strings are not valid.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/runway-gen4-image` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing generated image URLs in `resultUrls`. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds when available.
</ResponseField>

## Webhook callback mode

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

```bash theme={null}
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](/api-reference/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         |

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

## 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](/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Routing Strategies](/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)