# Runway Gen-4 Image - Core.Today AI API

> Runway's Gen-4 Image model with references: combine up to 3 reference images with @tag mentions in your prompt to keep characters, objects, and locations consistent across every angle and scene, at 720p or 1080p.

- **Provider**: Runway
- **Model ID**: runwayml/gen4-image
- **Category**: Image Generation
- **Credits**: 190 per image at 1080p (default) — 720p 120 credits, 1080p 190 credits
- **Speed**: Medium
- **Quality**: Ultra

## Features
- Up to 3 reference images for consistent characters, objects, and locations
- @tag_name mentions in the prompt bind each reference to a role
- 720p and 1080p output resolutions with differential pricing
- 6 aspect ratios from 21:9 cinematic to 9:16 vertical
- Seed support for reproducible generation

## Use Cases
- Multi-character scenes that keep every person consistent
- Product shots placing the same item in new environments
- Storyboards and comics reusing characters across panels
- Brand campaigns anchored to a consistent visual style
- Placing a known character into a specific referenced location

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **prompt**: string - Text prompt for image generation. Reference your images using @tag_name

### Optional
- **seed**: integer - Random seed. Set for reproducible generation
- **resolution**: string (default: 1080p) - Image resolution — 720p bills 150 credits, 1080p bills 240 credits
  Options: 720p, 1080p
- **aspect_ratio**: string (default: 16:9) - Image aspect ratio
  Options: 16:9, 9:16, 4:3, 3:4, 1:1, 21:9
- **reference_tags**: array (default: []) - An optional tag for each reference image, referenced in your prompt as @tag_name. Alphanumeric, starts with a letter, 3-15 characters
- **reference_images**: array (default: []) - Up to 3 reference images. Images must be between 0.5 and 2 aspect ratio

## Examples

### Two Characters in a Referenced Location
Three references (a park, a woman, a man) combined with @tag mentions
```json
{
  "model": "runwayml/gen4-image",
  "input": {
    "prompt": "a close up portrait of @woman and @man standing in @park, hands in pockets, looking cool. She is wearing her pink sweater and bangles.",
    "resolution": "1080p",
    "aspect_ratio": "4:3",
    "reference_tags": [
      "park",
      "woman",
      "man"
    ],
    "reference_images": [
      "https://example.com/park.jpg",
      "https://example.com/woman.jpg",
      "https://example.com/man.jpg"
    ]
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- Choose 720p (150 credits) for drafts and iterations, then re-run keepers at 1080p (240 credits)
- Give each reference image a tag and mention it as @tag_name in the prompt — untagged references are harder to control
- Reference images must have an aspect ratio between 0.5 and 2; crop extreme panoramas before uploading
- Fix the seed to iterate on wording while keeping composition stable
- Only use photos of real people as references with the person's explicit consent

## Documentation
https://replicate.com/runwayml/gen4-image