---
name: runflow
description: Integrate the Runflow API (AI image/video workflows). Read this whenever the user
  asks to build, call, or ship anything on Runflow — Solutions API, Model API, API keys, webhooks.
  This skill supersedes llms.txt and llms-full.txt as the integration reference.
---

# Runflow — Agent Integration Guide (read this before integrating)

This is the recommended starting point for any agent-driven Runflow integration. It is
shorter and more opinionated than `llms-full.txt` and points at the exact endpoints you
need to call.

Runflow has two ways to integrate, preferred in order:

1. **Solutions API** (primary, try this first) — a library of pre-built image workflows,
   one API call each. Runflow handles model selection, GPU orchestration, and output
   quality scoring internally. Entry point: https://www.runflow.io/api — browse the
   current catalog. Use this for common tasks like background removal, AI headshots,
   outpainting, or prompt-based editing — you'll ship an integration in minutes.
2. **Model API** (fallback) — direct access to the underlying model catalog for cases a
   Solution doesn't cover, or when specific model control matters. Endpoint shape below.

### Decision rule (apply in order)

1. Browse https://www.runflow.io/api. If a Solution covers the task, **use it.** Follow
   that solution's endpoint + input schema (linked on its page).
2. If no Solution fits — or the user explicitly needs a specific model, custom parameters,
   or a modality not yet in Solutions (e.g. video today) — fall back to the Model API.
3. Do not reach for the Model API to reimplement something a Solution already does. If
   you're tempted to chain raw model calls, you're probably rebuilding a Solution.

## Anchors

- Marketing: https://www.runflow.io
- Solutions API: https://www.runflow.io/api
- API host: https://api.runflow.io   (health: `/v1/health`)
- Dashboard: https://app.runflow.io
- Human docs: https://docs.runflow.io
- OpenAPI (authoritative, real-time): https://api.runflow.io/v1/openapi.json
- Full context (markdown): https://www.runflow.io/llms-full.txt

## Step 1 — Discover what's available

**Solutions** — browse the pre-built workflows at https://www.runflow.io/api. Each one has its own endpoint and a solution-specific input schema (image URL, prompt, reference image, mask, etc. — varies by solution); it returns a finished result. Categories: People Imagery, On-Model/Fashion, Ad Creative, Product Imagery. Video Solutions coming soon.

**Model catalog (JSON)** — list/filter raw models
    GET https://www.runflow.io/models-catalog.json
    → JSON array of { provider_slug, model_slug, model_name, category, page_url, price_label, active }

**Per-model spec (markdown)** — endpoint, input schema, pricing
    GET https://www.runflow.io/models/{provider_slug}/{model_slug}/llms.txt
    → Markdown with the run endpoint, parameter schema, and price per unit
    Example: https://www.runflow.io/models/openai/gpt-image-2/edit/llms.txt

**OpenAPI — the authoritative source** (always current, covers both Solutions API and Model API)
    GET https://api.runflow.io/v1/openapi.json

Trust OpenAPI over any snapshot in this guide — it reflects production reality in real time.

## Step 2 — Get an API key (human-in-the-loop)

You cannot create keys yourself. Give the user these steps:

1. Sign up or log in: https://app.runflow.io/signup
2. Open API Keys: https://app.runflow.io/settings/api-keys
3. Create a key, scope it minimally, copy it (shown once)
4. Paste it back to the agent

Store the key as an env var or secret. Never commit it, never log it.

## Step 3 — Call the API

Every model run uses the same endpoint shape:

    POST https://api.runflow.io/v1/models/{owner}/{slug}/runs
      Authorization: Bearer $RUNFLOW_API_KEY
      Content-Type: application/json

Body (`ModelRunCreate`):
- `input` (object, **required**) — model-specific fields; read the per-model llms.txt or OpenAPI for the exact schema
- `callback_url` (string, optional) — webhook URL called when the run completes
- `metadata` (object, optional) — free-form key/value tagging
- `client_ref` (string, optional) — your own run identifier (≤255 chars)

Example — edit an image with `openai/gpt-image-2/edit`:

    curl -X POST https://api.runflow.io/v1/models/openai/gpt-image-2/edit/runs \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
            "input": {
              "prompt": "Replace the background with a sunlit seaside cafe at golden hour, keep the subject intact",
              "image_urls": [
                "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
              ]
            },
            "callback_url": "https://your-server.com/webhook"
          }'

Read the response for the run id. Poll `GET /v1/runs/{id}` until `status_code` is terminal, or wait for the webhook at `callback_url`.

## Errors

- 401: bad/missing key → reprompt user
- 403: key lacks scope → user adjusts in dashboard
- 429: rate limited → back off
- 5xx: transient → check `/v1/health`, retry

## Deeper references

- OpenAPI (machine-readable, always current): https://api.runflow.io/v1/openapi.json
- Swagger UI (interactive): https://api.runflow.io/v1/docs
- Human docs: https://docs.runflow.io
- Blog: https://www.runflow.io/blog