Vercel AI SDK integration

Use Runware's image generation capabilities through the Vercel AI SDK with our community provider. Complete setup guide and usage examples.

Introduction

The Runware provider for Vercel AI SDK allows you to integrate Runware's image generation capabilities directly into applications built with the Vercel AI SDK. This integration provides a standardized interface that follows Vercel's conventions while maintaining full access to Runware's advanced features and flexible API.

Source code: https://github.com/Runware/ai-sdk-provider

Installation

Install the provider package alongside the Vercel AI SDK:

npm install @runware/ai-sdk-provider ai@^4.3.16

Basic setup

Before you start generating images, you'll need to configure your API key. The simplest approach is to set it as an environment variable, which keeps your credentials secure and makes deployment easier:

export RUNWARE_API_KEY="your-api-key-here"

To set the API key in code, or to change the connection settings, see custom provider configuration further down this page.

Once your API key is configured, you can generate your first image with just a few lines of code:

import { runware } from '@runware/ai-sdk-provider';
import { experimental_generateImage as generateImage } from 'ai';

const { image } = await generateImage({
  model: runware.image('runware:101@1'),
  prompt: 'A serene mountain landscape at sunset',
  size: '1024x1024',
});

console.log('Generated image:', image.url);

That's it! Your first AI-generated image is ready. The provider handles all the API communication, authentication, and response formatting automatically.

Key integration concepts

Model selection with AIR IDs

Runware identifies every model with an AIR ID, whatever its source. The provider takes models in that same format:

// High-quality generation with FLUX.1 Dev
const fluxDev = runware.image('runware:101@1');

// Ultra-fast generation with FLUX.1 Schnell
const fluxSchnell = runware.image('runware:100@1');

// Community models from Civitai
const civitaiModel = runware.image('civitai:133005@782002');

// Your own fine-tuned models
const customModel = runware.image('custom:your-model@1');

Each model page carries its own parameters, pricing and examples. Browse the full catalog in the models directory.

Accessing advanced features

The Vercel AI SDK keeps a standardized interface, and providerOptions.runware is where the rest of the Runware API lives:

const { image } = await generateImage({
  model: runware.image('runware:101@1'),
  prompt: 'A cyberpunk cityscape with neon lights',
  size: '1024x1024',
  providerOptions: {
    runware: {
      steps: 30,                     // Higher steps for better quality
      CFGScale: 7.5,                 // How closely to follow the prompt
      scheduler: 'DPM++ 2M',         // Sampling algorithm
      seed: 42,                      // For reproducible results
    },
  },
});

You keep the Vercel AI SDK's call shape and still reach every parameter the model accepts. Each one is listed on its own page in the model documentation.

Common usage patterns

Image transformation

Transform an existing image while preserving its structure, which is what style transfer and enhancement need:

const { image } = await generateImage({
  model: runware.image('runware:97@2'), // HiDream Dev
  prompt: 'vibrant cyberpunk style with neon lighting',
  size: '1024x1024',
  providerOptions: {
    runware: {
      seedImage: 'image-uuid-or-url',   // Accepts UUID, URL, or Base64
      strength: 0.7,                    // Controls transformation intensity
      steps: 20,
    },
  },
});

strength is the parameter that decides the outcome here. Lower values (0.1-0.4) preserve more of the original image structure, while higher values (0.7-1.0) let the model depart from it. Start between 0.6 and 0.8.

Batch generation

Generate multiple variations of the same concept in a single request, which is how you give users a choice or A/B test two approaches:

// Configure the model to allow multiple images
// Note: This model configuration pattern is specific to the Vercel AI SDK
const model = runware.image('runware:100@1', {
  maxImagesPerCall: 4,
  outputFormat: 'webp',
});

const { images } = await generateImage({
  model,
  prompt: 'A friendly AI assistant robot in a modern office',
  n: 4,                              // Generate 4 variations
  size: '1024x1024',
  providerOptions: {
    runware: {
      steps: 4,                      // Schnell model works well with fewer steps
    },
  },
});

// Process each generated variation
images.forEach((img, index) => {
  console.log(`Variation ${index + 1}:`, img.url);
});

Runware excels at batch generation, supporting up to 20 images in a single request without any speed penalties.

Precise editing with inpainting

Inpainting replaces part of an image and leaves the rest untouched, with your prompt deciding what appears in the replaced area:

const { image } = await generateImage({
  model: runware.image('runware:102@1'), // FLUX.1 Fill - specialized for inpainting
  prompt: 'A beautiful zen garden with cherry blossoms and stone lanterns',
  size: '1024x1024',
  providerOptions: {
    runware: {
      seedImage: 'base-image-uuid',        // Your source image
      maskImage: 'mask-image-uuid',        // Black/white mask defining edit areas
      steps: 25,
    },
  },
});

Create masks in any image editor, where white pixels mark the areas to regenerate and black pixels are preserved. The same mask serves whether you are removing an object, replacing a background or adding something that was never there.

Configuration options

Default provider

The simplest setup uses environment variables for configuration, which works great for most applications:

import { runware } from '@runware/ai-sdk-provider';
// Automatically uses RUNWARE_API_KEY from environment

This default provider handles authentication automatically and connects to Runware's standard API endpoint.

Custom provider configuration

The provider takes additional options for cases the defaults do not cover, such as proxying the API or running your own authentication flow:

import { createRunware } from '@runware/ai-sdk-provider';

const runware = createRunware({
  apiKey: 'your-specific-api-key',         // Override environment variable
  baseURL: 'https://your-proxy.com/v1',    // Custom endpoint for proxying
  headers: {
    'X-Proxy-Auth': 'token',               // Additional headers as needed
  }
});

Model configuration

The Vercel AI SDK lets you bind default parameters to a model instance, which Runware's own SDKs do not. The defaults then apply to every generation made through it:

const highQualityModel = runware.image('runware:101@1', {
  outputFormat: 'png',       // Always use PNG for this model
  outputQuality: 95,         // High quality
  checkNSFW: true,           // Enable content filtering
  steps: 30,                 // Default to high quality
  scheduler: 'DPM++ 2M',     // Preferred scheduler
});

// Now every generation with this model uses these defaults
const { image } = await generateImage({
  model: highQualityModel,
  prompt: 'A stunning landscape photography',
  size: '1024x1024',
  // Configuration is already applied
});

It earns its place when your application has more than one quality tier. The pattern belongs to the Vercel AI SDK integration and does not exist in the native SDKs.

Error handling

The provider returns descriptive error messages, so you can tell a failed generation apart from a bad request without reading the raw response:

try {
  const { image } = await generateImage({
    model: runware.image('runware:101@1'),
    prompt: 'A detailed architectural rendering',
    size: '1024x1024',
  });

  // Success - use the generated image
  console.log('Generated successfully:', image.url);

} catch (error) {
  if (error.name === 'RunwareAPIError') {
    // API-specific errors with detailed information
    console.error('Runware API Error:', error.message);
    console.error('Status Code:', error.status);
  } else {
    // Network errors, timeout, or other issues
    console.error('Request failed:', error.message);
  }
}

The usual failures are insufficient credits, an invalid model ID, a parameter combination the model rejects, or the network. The provider surfaces each one with its own message, so your application can tell them apart.

TypeScript support

The provider ships TypeScript definitions for every API, model configuration and response type, so your editor autocompletes and type-checks them.