Runware

Runware API conversion guide - text-to-image, image editing, and text/image-to-video generation

Overview

Runware exposes a single synchronous endpoint (https://api.runware.ai/v1) that accepts an array of tasks. Bifrost wraps each request in this array envelope and maps the unified image and video schemas onto Runware’s imageInference and videoInference task types. Image tasks return synchronously; video tasks are submitted asynchronously and polled to completion.

Supported Operations

Operation	Supported	Task Type
Image Generation	✅	imageInference
Image Edit (inpainting / outpainting)	✅	imageInference
Video Generation	✅	videoInference (async)
Video Retrieve	✅	getResponse
Video Download	✅	via Retrieve + URL download
Image Variation	❌	-
Image / Image Edit (stream)	❌	-
Video Delete / List / Remix	❌	-

---

1. Image Generation

Generate (POST /v1/images/generations)

Parameter	Type	Required	Runware field	Notes
model	string	✅	model	Runware model (AIR identifier)
prompt	string	✅	positivePrompt	Text description of the image
negative_prompt	string	❌	negativePrompt	What to avoid
size	string	❌	width / height	WxH (e.g. 1024x1024; default 1024x1024)
num_inference_steps	int	❌	steps	Diffusion steps
seed	int	❌	seed	Seed for reproducibility
n	int	❌	numberResults	Number of images
response_format	string	❌	outputType	url → URL, b64_json → base64Data
output_format	string	❌	outputFormat	png/jpeg/webp → PNG/JPG/WEBP

Extra Params: pass a seedImage (a Runware image UUID, public URL, or base64/data-URI) to run image-to-image. Any other provider-native fields flow through extra_params.

Response: BifrostImageGenerationResponse with data[].url or data[].b64_json.

Example

Gateway

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runware/runware:100@1",
    "prompt": "A serene mountain landscape at sunset",
    "size": "1024x1024",
    "n": 1
  }'

Go SDK

resp, err := client.ImageGenerationRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostImageGenerationRequest{
    Provider: schemas.Runware,
    Model:    "runware:100@1",
    Input: &schemas.ImageGenerationInput{
        Prompt: "A serene mountain landscape at sunset",
    },
    Params: &schemas.ImageGenerationParameters{
        Size: schemas.Ptr("1024x1024"),
        N:    schemas.Ptr(1),
    },
})

---

2. Image Edit

Edit (POST /v1/images/edits)

The first input image becomes the seedImage; supplying a mask enables inpainting. Outpainting and other provider-native fields flow through extra_params.

Parameter	Runware field	Notes
image[] (first)	seedImage	Base image being edited (bytes → data URI)
mask	maskImage	Inpainting mask (bytes → data URI)
prompt	positivePrompt	Edit instruction
negative_prompt, size, num_inference_steps, seed, n, response_format, output_format	same as Image Generation

Example

curl -X POST 'http://localhost:8080/v1/images/edits' \
  --form 'model="runware/runware:100@1"' \
  --form 'image[]=@"image.png"' \
  --form 'prompt="Replace the sky with a starry night"' \
  --form 'mask=@"mask.png"'

Response: same shape as Image Generation (data[].url or data[].b64_json).

---

3. Video Generation

Generate (POST /v1/videos)

Video tasks are submitted with deliveryMethod: async and return a queued job. Poll Retrieve until status: completed, then download.

Parameter	Type	Required	Runware field	Notes
model	string	✅	model	Runware video model
prompt	string	❌	positivePrompt	Text description of the video
input_reference	string	❌	frameImages[0]	Reference image anchored to the first frame → image-to-video
negative_prompt	string	❌	negativePrompt	What to avoid
seed	int	❌	seed	Seed for reproducibility
size	string	❌	width / height	WxH (default 1920x1080)
seconds	string	❌	duration	Duration in seconds

Extra Params: provider-native fields flow through extra_params.

Response: BifrostVideoGenerationResponse with id, status, videos[].

Generation Modes (auto-detected): text-to-video (prompt only) · image-to-video (prompt + input_reference).

Bifrost statuses (normalized): queued → in_progress → completed / failed. Runware’s native statuses are processing, success, error.

Retrieve / Download

Operation	Endpoint	Notes
Get status	GET /v1/videos/{id}	Polls via a getResponse task; poll until status: completed
Download content	GET /v1/videos/{id}/content	Downloads raw video bytes (MP4) from the task’s output URL

Video Delete, List, and Remix are not supported by Runware.

---

Setup & Configuration

Configure Runware as a provider.

Web UI

1. Navigate to Models > Model Providers. Look for Runware under Configured Providers. If it is missing, click on Add New Provider and select Runware.
2. Click Add Key or edit an existing key.
3. Set a name for your key.
4. Paste your API key directly or use an environment variable (for example, env.RUNWARE_API_KEY).
5. Set Allowed Models to All Models (default) or the specific model allowlist you want this key to serve.
6. Save the provider configuration.

config.json

{
  "providers": {
    "runware": {
      "keys": [
        {
          "name": "runware-key-1",
          "value": "env.RUNWARE_API_KEY",
          "models": [
            "*"
          ],
          "weight": 1.0
        }
      ]
    }
  }
}

API

Refer to the API documentation for Provider Keys Management.

Go SDK

case schemas.Runware:
    return []schemas.Key{{
        Name:   "runware-key-1",
        Value:  *schemas.NewSecretVar("env.RUNWARE_API_KEY"),
        Models: []string{"*"},
        Weight: 1.0,
    }}, nil

---

Reference Links

• Runware API Documentation
• Runware Model Explorer
• Bifrost Runware Provider Source