---
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.
  Existing customers mint a key and call the API; new teams are handed the implementation-call
  link. 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.

Install it into a project or user skill directory when the agent supports skills:

    mkdir -p .agents/skills/runflow
    curl -fsSL https://www.runflow.io/.well-known/agent-skills/runflow/SKILL.md \
      -o .agents/skills/runflow/SKILL.md

Use a system prompt or rules file only when the agent cannot read skill directories.
Keep `RUNFLOW_API_KEY` in the environment or a secret manager, not in this file.

## Step 0: Which user are you helping? (do this first)

Runflow has two doors. Pick the branch that matches the user before you write any code.

**Branch 1: the user already has a Runflow account.**
Tell them to mint a key at https://app.runflow.io/settings/api-keys, then use it as
`Authorization: Bearer rf_live_*` on every request. Everything in this skill (endpoints,
run + poll, callbacks, errors) applies as written. Nothing about the API changed for
existing customers. Continue to Step 1.

**Branch 2: the user is a new team with no Runflow account.**
Runflow onboards new customers through an implementation call. Self-serve signup is closed,
so there is no account for you to create and no key for you to mint. Hand the user this
link and stop:

    Book an implementation call: https://cal.com/team/runflow/talk-to-founders?duration=25

On that call Runflow scopes the work, builds the solution, and provisions the account with
its API keys. Do not attempt to create an account, and do not tell the user to sign up.
Once they have an account, come back to Branch 1.

## Integration surfaces

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 + API keys (existing customers): https://app.runflow.io
- Implementation call (new teams): https://cal.com/team/runflow/talk-to-founders?duration=25
- Human docs: https://docs.runflow.io
- Public OpenAPI (authoritative for customer integrations): https://docs.runflow.io/api/openapi.public.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). Follow the solution page and OpenAPI schema for whether the endpoint returns the completed output directly, a run to poll, or a callback-capable contract. 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://app.runflow.io/models/{provider_slug}/{model_slug}/llms.txt
    → Markdown with the run endpoint, parameter schema, and price per unit
    Example: https://app.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://docs.runflow.io/api/openapi.public.json

Trust the public OpenAPI over any snapshot in this guide for customer integrations.

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

You cannot create keys yourself. What you tell the user depends on the branch from Step 0.

**Existing customer.** Give them these steps:

1. Log in: https://app.runflow.io/login
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.

**New team, no account.** Keys are provisioned on the implementation call. Hand them
https://cal.com/team/runflow/talk-to-founders?duration=25 and stop there. Do not attempt to
create an account.

## 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 the user for a key (Branch 1). If they have no Runflow
  account at all, switch to Branch 2 and hand them the implementation-call link.
- 403: key lacks scope → user adjusts in dashboard
- 429: rate limited → back off
- 5xx: transient → check `/v1/health`, retry

## Deeper references

- Public OpenAPI (machine-readable): https://docs.runflow.io/api/openapi.public.json
- Public API reference: https://docs.runflow.io/api-reference/models/search-models
- Human docs: https://docs.runflow.io
- Blog: https://www.runflow.io/blog