# RunwayML Integration via LowCodeAPI

## Overview

RunwayML is a general-purpose multimodal AI platform for video and image generation and editing. The RunwayML API provides cutting-edge functionality for:

- **Text to Video** - Generate videos from text prompts
- **Image to Video** - Transform images into dynamic video clips
- **Video Generation** - Create videos with various AI models
- **Video Editing** - Edit and enhance video content

## Base Endpoint

```
https://api.lowcodeapi.com/runwayml/
```

## Authentication

LowCodeAPI handles authentication automatically using Bearer token authentication. You only need to:

1. **Sign up** at [RunwayML](https://runwayml.com) to get your API Key
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your RunwayML API key
- Apply it to each request as a Bearer token

**Auth Type**: Bearer Token

## API Categories

- **Video Generation AI** - AI-powered video creation and editing

## Common Endpoints

### Category: Start Generating

#### Generate Video from Image

**Method**: `POST` | **LowCodeAPI Path**: `/v1/image_to_video`

**Full URL**:
```
https://api.lowcodeapi.com/runwayml/v1/image_to_video?api_token={api_token}
```

**Description**: Generate a video from an input image using RunwayML's Gen-3 Alpha model.

**Request Body**:
```json
{
  "uri": "https://example.com/input-image.jpg",
  "model": "gen3a_turbo",
  "duration": 5,
  "ratio": "1280:720",
  "position": "0,0",
  "watermark": false,
  "promptText": "A slow zoom in with subtle camera movement"
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uri` | string | Yes | HTTPS URL or data URI of the input image |
| `model` | string | Yes | Model variant to use (e.g., "gen3a_turbo") |
| `duration` | number | No | Duration of output video in seconds (default: 10) |
| `ratio` | string | No | Resolution of output video (e.g., "1280:720") |
| `position` | string | Yes | Position of image in output video (e.g., "0,0") |
| `watermark` | boolean | No | Whether to include Runway watermark (default: false) |
| `promptText` | string | No | Detailed description of what should appear in output |
| `seed` | number | No | Random seed for reproducibility |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/runwayml/v1/image_to_video?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/input-image.jpg",
    "model": "gen3a_turbo",
    "duration": 5,
    "ratio": "1280:720",
    "position": "0,0",
    "watermark": false,
    "promptText": "Gentle camera movement with smooth transitions"
  }'
```

**Official Documentation**: [Image to Video](https://docs.dev.runwayml.com/api)

---

#### Generate Video from Text

**Method**: `POST` | **LowCodeAPI Path**: `/v1/text_to_video`

**Full URL**:
```
https://api.lowcodeapi.com/runwayml/v1/text_to_video?api_token={api_token}
```

**Description**: Generate a video from a text prompt.

**Request Body**:
```json
{
  "promptText": "A serene sunset over mountains with gentle clouds",
  "model": "gen3a_turbo",
  "duration": 5,
  "ratio": "1280:720",
  "watermark": false
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `promptText` | string | Yes | Detailed description of the video to generate |
| `model` | string | Yes | Model variant to use |
| `duration` | number | No | Duration in seconds (default: 10) |
| `ratio` | string | No | Resolution of output video |
| `watermark` | boolean | No | Include watermark (default: false) |
| `seed` | number | No | Random seed for reproducibility |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/runwayml/v1/text_to_video?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "A serene sunset over mountains with gentle clouds",
    "model": "gen3a_turbo",
    "duration": 5,
    "ratio": "1280:720",
    "watermark": false
  }'
```

**Official Documentation**: [Text to Video](https://docs.dev.runwayml.com/api)

---

### Category: Check Status

#### Get Task Status

**Method**: `GET` | **LowCodeAPI Path**: `/v1/tasks/id`

**Full URL**:
```
https://api.lowcodeapi.com/runwayml/v1/tasks/id?id={id}&api_token={api_token}
```

**Description**: Check the status of a video generation task.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Task ID returned from generation request |

**Example Request**:
```bash
# Replace TASK_ID with actual task ID
curl -X GET "https://api.lowcodeapi.com/runwayml/v1/tasks/id?id=TASK_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Task Status](https://docs.dev.runwayml.com/api)

---

## Usage Examples

### Example 1: Generate Video from Image

Transform an image into a video:

```bash
# Step 1: Start video generation from image
# No ID needed - starts new generation task
curl -X POST "https://api.lowcodeapi.com/runwayml/v1/image_to_video?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/landscape-photo.jpg",
    "model": "gen3a_turbo",
    "duration": 5,
    "ratio": "1920:1080",
    "position": "0,0",
    "promptText": "Slow cinematic pan with atmospheric movement"
  }'

# Step 2: Check task status
# Replace TASK_ID with actual task ID from step 1
curl -X GET "https://api.lowcodeapi.com/runwayml/v1/tasks/id?id=TASK_ID&api_token=YOUR_API_TOKEN"
```

### Example 2: Generate Video from Text

Create video from text description:

```bash
# Step 1: Start text-to-video generation
# No ID needed - starts new generation task
curl -X POST "https://api.lowcodeapi.com/runwayml/v1/text_to_video?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "A futuristic city at night with neon lights and flying vehicles",
    "model": "gen3a_turbo",
    "duration": 10,
    "ratio": "16:9",
    "watermark": false
  }'

# Step 2: Poll for completion
# Replace TASK_ID with actual task ID
curl -X GET "https://api.lowcodeapi.com/runwayml/v1/tasks/id?id=TASK_ID&api_token=YOUR_API_TOKEN"
```

### Example 3: Batch Video Generation

Generate multiple videos:

```bash
# Generate multiple videos with different prompts
# No ID needed for each request
curl -X POST "https://api.lowcodeapi.com/runwayml/v1/text_to_video?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "Ocean waves crashing on a beach at sunset",
    "model": "gen3a_turbo",
    "duration": 5
  }'

curl -X POST "https://api.lowcodeapi.com/runwayml/v1/text_to_video?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "Rain falling on a window in a cozy room",
    "model": "gen3a_turbo",
    "duration": 5
  }'

# Check status of each task using returned task IDs
```

## Complete Endpoint Reference

For a complete list of all 3 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/runwayml/definition
- **Official RunwayML Documentation**: https://docs.dev.runwayml.com/api

## Rate Limits & Best Practices

- **Rate Limit**: Refer to your RunwayML plan for rate limits
- **Best Practices**:
  - Video generation is asynchronous - always poll task status
  - Store task IDs for tracking generation progress
  - Use descriptive prompts for better video quality
  - Consider shorter durations for faster generation
  - Test with turbo models before using standard models
  - Implement proper error handling for failed tasks
  - Use appropriate resolution ratios for your use case

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from RunwayML
  }
}
```

Task status responses:
- **PENDING**: Task is queued
- **PROCESSING**: Video is being generated
- **SUCCEEDED**: Video generation complete
- **FAILED**: Generation failed

Common errors:
- **400**: Invalid request parameters
- **401**: Invalid API key
- **429**: Rate limit exceeded
- **500**: Internal server error during generation