# Runflow docs (full)

Generated from https://docs.runflow.io. Public OpenAPI: https://docs.runflow.io/api/openapi.public.json. Model catalog: https://www.runflow.io/models-catalog.json.

---

# API catalog
<!-- https://docs.runflow.io/agents/api-catalog -->

[RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) defines an "API catalog" linkset: one URL that lists every machine-readable surface of an API. Runflow's lives at:

```
https://www.runflow.io/.well-known/api-catalog
```

## Payload

```json
{
  "linkset": [
    {
      "anchor": "https://api.runflow.io/",
      "service-desc": [
        { "href": "https://docs.runflow.io/api/openapi.public.json", "type": "application/json" }
      ],
      "service-doc": [
        { "href": "https://docs.runflow.io/api-reference/models/search-models", "type": "text/html" },
        { "href": "https://docs.runflow.io/", "type": "text/html" }
      ],
      "status": [
        { "href": "https://api.runflow.io/v1/health", "type": "application/json" }
      ]
    }
  ]
}
```

## Relations

| Rel | What it points to |
|---|---|
| `service-desc` | Machine-readable public spec (OpenAPI). |
| `service-doc` | Human-readable API reference and docs. |
| `status` | Health/status endpoint. |

## Use it

Discovery agents use the catalog to learn the spec URL without scraping. Code:

```python
import requests
from requests.exceptions import RequestException

TIMEOUT = 5

try:
    r = requests.get("https://www.runflow.io/.well-known/api-catalog", timeout=TIMEOUT)
    r.raise_for_status()
    catalog = r.json()
    spec_url = catalog["linkset"][0]["service-desc"][0]["href"]

    r = requests.get(spec_url, timeout=TIMEOUT)
    r.raise_for_status()
    spec = r.json()
except RequestException as exc:
    raise SystemExit(f"Could not load Runflow API catalog: {exc}")
```

## Related


  The spec the catalog points at.
  Higher-level agent integration.

---

# For agents
<!-- https://docs.runflow.io/agents -->

For agent integrations, start with the **Runflow skill**. It is the shortest path to the correct workflow.

## Install the skill

If your coding agent has file access, it can install the skill for you. Open the agent in the repo where you are integrating Runflow and ask:

```text
Install the Runflow Agent Skill for this project.

Create .agents/skills/runflow/SKILL.md by downloading:
https://www.runflow.io/.well-known/agent-skills/runflow/SKILL.md

Then use that skill whenever this repo integrates, calls, or debugs Runflow.
Use OpenAPI for endpoint schemas and auth, and the models catalog for model
availability and pricing. Never write API keys to files.
```

If you prefer to install it yourself, run this from the project root:

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

For a user-wide install, use your home directory instead:

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

Agents with native skill managers may also have their own install command or directory. Common project directories are `.agents/skills/`, `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, and `.codex/skills/`. Prefer `.agents/skills/` when you want the skill to travel with the repo across compatible agents.

Set `RUNFLOW_API_KEY` in the environment where your agent runs. Do not put it in `SKILL.md` or commit it to the repo.


  Only use a system prompt or rules file when your agent cannot read skill directories. In that case, add one short instruction: "Use the Runflow skill at https://www.runflow.io/.well-known/agent-skills/runflow/SKILL.md for Runflow integrations."


## Discovery resources

| Resource | URL | Purpose |
|---|---|---|
| Skill | [`agent-skills/runflow/SKILL.md`](https://www.runflow.io/.well-known/agent-skills/runflow/SKILL.md) | Workflow guide for AI coding assistants. |
| Skills index | [`agent-skills/index.json`](https://www.runflow.io/.well-known/agent-skills/index.json) | agentskills.io v0.2.0 manifest. |
| llms.txt | [`docs.runflow.io/llms.txt`](https://docs.runflow.io/llms.txt) | This site's index for LLMs. |
| llms-full.txt | [`docs.runflow.io/llms-full.txt`](https://docs.runflow.io/llms-full.txt) | Full corpus, one-shot ingestion. |
| Public OpenAPI | [`docs.runflow.io/api/openapi.public.json`](https://docs.runflow.io/api/openapi.public.json) | Customer integration spec. |
| API catalog | [`/.well-known/api-catalog`](https://www.runflow.io/.well-known/api-catalog) | RFC 9727 linkset. |
| Models catalog | [`models-catalog.json`](https://www.runflow.io/models-catalog.json) | All 50 models, prices, categories. |

## Hosts

| Host | Purpose |
|---|---|
| `api.runflow.io` | Production API. |
| `docs.runflow.io` | This site. |
| `app.runflow.io` | Dashboard and per-model `llms.txt`. |
| `www.runflow.io` | Marketing and agent discovery (`/.well-known/*`). |
| `public.runflow.io` | Public CDN for example assets. |

## Pages in this section


  agentskills.io v0.2.0 detail.
  llmstxt.org convention.
  Spec, codegen recipes.
  RFC 9727 linkset.

---

# llms.txt
<!-- https://docs.runflow.io/agents/llms-txt -->

[llmstxt.org](https://llmstxt.org) is a convention: a root `/llms.txt` file with a structured link index that LLMs and agents fetch to learn what a site contains. Runflow ships two:

| File | Use |
|---|---|
| [`/llms.txt`](https://docs.runflow.io/llms.txt) | Categorized link list. Quick site map. |
| [`/llms-full.txt`](https://docs.runflow.io/llms-full.txt) | Concatenation of every doc page, frontmatter stripped. One-shot ingestion. |

These files are generated from the docs corpus. Do not edit them by hand.

## Discovery

Mintlify also sets the `Link` response header on every page:

```http
Link: </llms.txt>; rel="llms-txt", </llms-full.txt>; rel="llms-full-txt"
```

Agents that follow RFC 8288 link relations find the index without crawling.

## Use it

```bash
# Index
curl https://docs.runflow.io/llms.txt

# Full corpus
curl https://docs.runflow.io/llms-full.txt
```

Pipe `llms-full.txt` into your model's context window. The full corpus is ~340 KB, well under any modern model's window.

## Two siblings

Runflow also publishes:

- `https://www.runflow.io/llms.txt` - marketing-side site index.
- `https://www.runflow.io/llms-full.txt` - marketing-side full corpus.
- `https://app.runflow.io/models/{provider}/{slug}/llms.txt` - per-model spec, including model specs that may not be public marketing pages.

Use docs.runflow.io's versions if you want the developer reference. Use the others if you need marketing context or a single model's spec.

## Related


  Machine-readable API spec.
  Integration guide for agents.

---

# OpenAPI
<!-- https://docs.runflow.io/agents/openapi -->

Runflow publishes a public OpenAPI 3.1 spec for customer integrations and codegen:

```
https://docs.runflow.io/api/openapi.public.json
```

The public spec is what generates the [API reference](/api-reference/models/search-models) tab on this site. Use it for codegen and agent integrations.


  Every endpoint still requires the right Bearer token and role. A path being listed does not mean an unauthenticated caller can use it.


## Codegen recipes

### TypeScript types

```bash
npx openapi-typescript https://docs.runflow.io/api/openapi.public.json -o runflow-types.ts
```

### Python client

```bash
pip install openapi-python-client
openapi-python-client generate --url https://docs.runflow.io/api/openapi.public.json
```

### Go client

```bash
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
oapi-codegen -package runflow https://docs.runflow.io/api/openapi.public.json > runflow.go
```

### Postman / Insomnia

Both import OpenAPI directly. Point them at `https://docs.runflow.io/api/openapi.public.json` for customer integrations.

## Auth

One scheme: `HTTPBearer`. See [Authentication](/concepts/authentication).

## Versioning

The path prefix is `/v1`. Breaking changes trigger a `/v2` path. Additive changes ship in `/v1`.

## Related


  No SDKs yet, codegen instead.
  RFC 9727 linkset.

---

# Agent skills
<!-- https://docs.runflow.io/agents/skills -->

[Agent Skills](https://agentskills.io) is a convention for publishing integration instructions that AI coding assistants discover and follow. Runflow exposes one skill.

## The index

```bash
curl https://www.runflow.io/.well-known/agent-skills/index.json
```

```json
{
  "$schema": "https://agentskills.io/schema/v0.2.0/index.json",
  "skills": [
    {
      "name": "runflow",
      "type": "instructions",
      "description": "Integrate the Runflow API.",
      "url": "https://www.runflow.io/.well-known/agent-skills/runflow/SKILL.md",
      "sha256": "<pinned hash>"
    }
  ]
}
```

The `sha256` lets agents detect tampering between fetch and use.

## The skill

```bash
curl https://www.runflow.io/.well-known/agent-skills/runflow/SKILL.md
```

Markdown body. Covers: API key setup, base URL, auth header, model catalog discovery, run lifecycle, callback or polling result delivery, error handling, common pitfalls.

## Install in your agent

See [For agents](/agents) for the recommended install flow. Prefer installing `SKILL.md` into a project or user skill directory over pasting long instructions into a prompt.

## Why a skill, not just docs?

A skill is a single, discoverable, hash-pinned document an agent fetches once. Docs are a website you navigate. Agents prefer the skill because:

- One fetch, no crawl.
- SHA256 makes tampering detectable.
- Versioned at the URL level.
- Freed from the surrounding marketing copy.

Use the skill as the workflow guide. Use OpenAPI for endpoint schemas and auth, and the models catalog for model availability and pricing. If they disagree, check the machine-readable source before coding.

## Related


  For agents that codegen instead.
  For LLMs that ingest the corpus.

---

# Authentication
<!-- https://docs.runflow.io/concepts/authentication -->

Every Runflow API request needs an `Authorization: Bearer <token>` header. Requests without a valid token return `401 Unauthorized`.

## Header

```http
Authorization: Bearer YOUR_API_KEY
```

## Get a key

1. Sign in at [app.runflow.io](https://app.runflow.io/settings/api-keys).
2. Open **Settings -> API Keys**, click **Create**.
3. Copy the token. It is shown once.
4. Save it as `RUNFLOW_API_KEY` in your secret manager.

## Example

```bash
export RUNFLOW_API_KEY="your_token_here"

curl https://api.runflow.io/v1/auth/me \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

A `200` with your account payload confirms the key works.

## Rotate

Compromised key? Revoke it from the dashboard, create a new one, deploy. No downtime if you keep both keys live during cutover.

## Best practices

- Read the token from an env var or secret manager. Never commit it.
- Use distinct keys per environment so a leak in staging cannot touch prod.
- Call the API from your backend, not the browser.
- Watch for `401` spikes. They usually mean a leaked or rotated key.

## Related


  Status codes and the error envelope.
  Make your first authenticated call.

---

# Callbacks
<!-- https://docs.runflow.io/concepts/callbacks -->

Long-running models push their final payload to a URL you control. You provide the URL on the request; Runflow POSTs the result when the run finishes.

## Pattern

1. Call `POST /v1/models/{model_id}/runs` with `callback_url`, where `{model_id}` is the slash-delimited provider/model path shown on the model page.
2. Save the returned `id`. Callback payloads call the same value `run_id`.
3. Run finishes in the background.
4. Runflow POSTs to `callback_url`.
5. Your handler returns `200 OK` within a few seconds.

## Callback payload

The callback body is an event envelope, frozen at delivery time:

```json
{
  "event": "run.completed",
  "run_id": "01J0...",
  "status": "succeeded",
  "output": { "image_urls": ["https://..."] },
  "duration_ms": 102345,
  "created_at": "2026-05-06T10:00:00.000+00:00",
  "completed_at": "2026-05-06T10:01:42.000+00:00",
  "metadata": null
}
```

| Field | Notes |
|---|---|
| `event` | One of `run.completed`, `run.failed`, `run.cancelled`, `run.partial_succeeded`. |
| `run_id` | UUIDv7 of the run. Match against the `id` from your `POST /runs` response. |
| `status` | Terminal callback status. Run records expose the same value as `status_code` on [`GET /v1/runs/{id}`](/api-reference/runs/get-run). |
| `output` | The normalized model output on success, an error envelope on failure, or `null` if cancelled. Batch callbacks use a self-describing `{items, succeeded, failed, cancelled, total}` envelope, see the OpenAPI for the full shape. |
| `duration_ms` | Total run wall-clock time. |
| `created_at`, `completed_at` | ISO 8601, `+00:00` offset (not `Z`) so HMAC verification stays byte-equivalent. |
| `metadata` | Whatever you passed at run creation, verbatim. |

Output URLs are presigned and time-limited. Download or re-upload them to your own storage on receipt. Batch callbacks ship the same envelope but with `batch_id` instead of `run_id`.

## Verify the source

Create a callback secret and Runflow signs every callback with HMAC-SHA256:

```bash
curl -X POST https://api.runflow.io/v1/callback-secrets \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "production"}'
```

Save the returned `plain_secret`. Runflow then sends `Runflow-Signature: <hmac-hex>` on every callback (alongside a `Runflow-Request-Id` for log correlation). See [Verify callback signatures](/guides/verify-callback-signatures) for handler code.

## Retries

Runflow retries failed callbacks (non-2xx response, timeout, connection error) on an exponential schedule. Inspect attempts with [`GET /v1/runs/{run_id}/callback`](/api-reference/runs/get-callback-delivery-history).

## Manual redelivery

Replay a callback at any time:

```bash
curl -X POST https://api.runflow.io/v1/runs/{run_id}/callback-redeliveries \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

## Local development

Your laptop is not reachable from the public internet. Tunnel it:

```bash
ngrok http 3000
# use the https://abc123.ngrok-free.app URL as callback_url
```

## Related


  HMAC verify in Node and Python.
  History, redelivery, and secrets.

---

# Clients
<!-- https://docs.runflow.io/concepts/clients -->

Runflow does not ship official client libraries. The API is small and stable enough that a generated client or a `requests` / `fetch` call covers nearly every use case.

## Use the OpenAPI

The public spec for customer integrations lives at:

```
https://docs.runflow.io/api/openapi.public.json
```

It is OpenAPI 3.1 and is the spec used to generate this site's API reference.

## Codegen

### TypeScript types

```bash
npx openapi-typescript https://docs.runflow.io/api/openapi.public.json \
  -o src/runflow-types.ts
```

### Python client

```bash
pip install openapi-python-client
openapi-python-client generate --url https://docs.runflow.io/api/openapi.public.json
```

### Go client

```bash
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
oapi-codegen -package runflow https://docs.runflow.io/api/openapi.public.json > runflow.go
```

## Hand-rolled

For 90% of integrations, this is enough. Both snippets bound the network wait so a stuck connection never hangs the caller.



```python Python
import os, requests

RUNFLOW_API_KEY = os.environ["RUNFLOW_API_KEY"]
REQUEST_TIMEOUT = 30  # seconds

def runflow_post(path, body):
    r = requests.post(
        f"https://api.runflow.io{path}",
        headers={"Authorization": f"Bearer {RUNFLOW_API_KEY}"},
        json=body,
        timeout=REQUEST_TIMEOUT,
    )
    r.raise_for_status()
    return r.json()
```

```javascript Node.js
const RUNFLOW_API_KEY = process.env.RUNFLOW_API_KEY;
const REQUEST_TIMEOUT_MS = 30_000;

async function runflowPost(path, body) {
  const r = await fetch(`https://api.runflow.io${path}`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${RUNFLOW_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
  });
  if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
  return r.json();
}
```



## When SDKs ship

We will list them here.

## Related


  Spec details and codegen recipes.
  Bearer header.

---

# Errors
<!-- https://docs.runflow.io/concepts/errors -->

## Envelope

Errors return a JSON body with `code`, `message`, and optional `errors[]`:

```json
{
  "code": "PERMISSION_DENIED",
  "message": "Your account is not authorized to access this resource.",
  "errors": null
}
```

| Field | Type | Notes |
|---|---|---|
| `code` | string | Machine-friendly identifier. Stable across releases. |
| `message` | string | Human-friendly message. May change. |
| `errors[]` | array | Field-level details for `422 Unprocessable Entity`. |

## Status codes

| Code | Meaning | Action |
|---|---|---|
| `400` | Bad request shape. | Check your JSON body against the spec. |
| `401` | Missing or invalid token. | Confirm `Authorization: Bearer <token>` is present and the key is active. |
| `402` | Payment required. | Check the balance at [`GET /v1/billing/balance`](/api-reference/account/get-organization-credit-balance), then top up from [`app.runflow.io/settings/billing`](https://app.runflow.io/settings/billing). |
| `403` | Permission denied or email not verified. | Check the `code` for `PERMISSION_DENIED` vs `EMAIL_NOT_VERIFIED`. |
| `404` | Resource not found. | Verify the path and the resource ID. |
| `409` | Conflict. | Usually a duplicate create or a race. Refetch and retry. |
| `422` | Validation error. | Read `errors[]` for per-field details. |
| `503` | Service unavailable. | Backoff and retry with jitter. Check [`/v1/health`](https://api.runflow.io/v1/health), [contact support](https://cal.com/team/runflow/talk-to-founders?duration=25) if persistent. |

## Common codes

| `code` | Cause |
|---|---|
| `UNAUTHORIZED` | Bad or missing token. |
| `PERMISSION_DENIED` | Token lacks scope for this operation. |
| `EMAIL_NOT_VERIFIED` | User has not confirmed their email. |
| `INSUFFICIENT_CREDIT` | Account balance is too low. Top up. |
| `RUN_NOT_FOUND` | The `run_id` does not exist or belongs to another org. |
| `MODEL_UNAVAILABLE` | Provider downtime. Retry or pick a sibling model. |

## Run failures

When `POST /v1/models/.../runs` succeeds but the run later fails, the run object carries `failure_code`, `failure_stage`, and `failure_message`:

```json
{
  "id": "01J0...",
  "status": "failed",
  "failure_code": "INPUT_VALIDATION_FAILED",
  "failure_stage": "preprocess",
  "failure_message": "image dimensions exceed 4096x4096"
}
```

## Retry strategy

- `5xx` and `429`: exponential backoff with jitter, max 5 attempts.
- `4xx` other than `429`: do not retry, fix the request.
- Network errors: same as `5xx`.

## Related


  401 and Bearer header detail.
  402 and credit balance.

---

# Pricing
<!-- https://docs.runflow.io/concepts/pricing -->

Each model has a `price_label` shown on its [model page](/models). The label tells you the unit:

- `$0.35/request` - flat per call.
- `$0.14/second` - per output second (video models).
- `$0.03/megapixel` - per output megapixel (image models).
- `$0.075/image` - per output image (multi-image models).

Prices come from the [models catalog](https://www.runflow.io/models-catalog.json). The [`/models`](/models) page is generated from that catalog and updates when the docs rebuild.

## Credits

Runflow uses a credit balance. Every successful run debits credits at the model's rate. Failed runs are not billed.

Check your balance:

```bash
curl https://api.runflow.io/v1/billing/balance \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Response:

```json
{
  "balance_cents": 12450,
  "currency": "USD"
}
```

Top up at [app.runflow.io/settings/billing](https://app.runflow.io/settings/billing).

## Auto-refill

Configure a card to auto-charge when the balance drops below a threshold. Done from the dashboard.

## When you run out

The next run returns `402 Payment Required` with `code: INSUFFICIENT_CREDIT`. Existing in-flight runs finish.

## Quotes

For volume pricing, an enterprise contract, or non-standard payment terms, [talk to us](https://cal.com/team/runflow/talk-to-founders?duration=25).

## Related


  Browse prices per model.
  402 and INSUFFICIENT_CREDIT.

---

# Rate limits
<!-- https://docs.runflow.io/concepts/rate-limits -->

Rate limits exist per organization. Defaults are sized for typical production load. Hit a limit, get `429 Too Many Requests` with a `Retry-After` header in seconds.

## Headers

Every response carries:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Calls allowed in the current window. |
| `X-RateLimit-Remaining` | Calls left in the window. |
| `X-RateLimit-Reset` | Unix timestamp when the window resets. |
| `Retry-After` | Seconds to wait before the next call. Sent only on `429`. |

## Backoff

Honor `Retry-After` when present, fall back to exponential-with-jitter otherwise. Pseudocode:

```python
import random, time

delay = 1
for attempt in range(5):
    response = call_runflow()
    if response.status != 429:
        break
    retry_after = response.headers.get("Retry-After")
    try:
        wait = float(retry_after) if retry_after else delay
    except ValueError:
        wait = delay  # ignore HTTP-date form, use exponential
    time.sleep(min(wait, 32) + random.uniform(0, 1))
    delay = min(delay * 2, 32)
```

## Concurrent runs

Each model has a per-org concurrency cap. Exceed it and runs queue. Watch the `queued` status duration and request a higher cap if it grows.

## Need a higher limit?

[Talk to us](https://cal.com/team/runflow/talk-to-founders?duration=25). Include peak QPS, average payload size, and target concurrency.

## Related


  All status codes including 429.
  Per-request and per-second pricing.

---

# Requests
<!-- https://docs.runflow.io/concepts/requests -->

## Base URL

```
https://api.runflow.io
```

All endpoints live under `/v1/`. The public OpenAPI spec is at [`docs.runflow.io/api/openapi.public.json`](https://docs.runflow.io/api/openapi.public.json).

## Content types

| Method | Content-Type | Use |
|---|---|---|
| `GET` | n/a | Read endpoints. |
| `POST`, `PATCH`, `PUT` | `application/json` | All mutations. |
| `POST /v1/asset-uploads/{id}/confirmations` | `application/json` | After uploading the file blob to the presigned URL. |

## Pagination

List endpoints return cursors, not page numbers. Pass `pq` (the cursor) and `limit` (page size, max 500).

```bash
curl https://api.runflow.io/v1/runs?limit=50 \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

The response includes `next_pq` and `prev_pq`. Pass `from_prev=true` to walk backward.

## Filtering

List endpoints accept a filter expression in `q`:

```bash
curl 'https://api.runflow.io/v1/runs?q=status_code:succeeded%20AND%20created_at>2026-04-01' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Operators: `=`, `:`, `>`, `<`, `>=`, `<=`, `AND`, `OR`, `NOT`. String values are case-sensitive.

## Field projection

Trim the response to the fields you need with `fields`:

```bash
curl 'https://api.runflow.io/v1/runs?fields=id,status_code,model_id' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

## Sorting

```bash
curl 'https://api.runflow.io/v1/runs?sort_by=created_at:desc' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Multi-field sort: `sort_by=status_code:asc,created_at:desc`.

## Idempotency

Mutations are not idempotent by default. To retry safely, save the response of the first call and skip on duplicate.

## Related


  Status codes and the error envelope.
  Callbacks, polling, statuses.

---

# Runs
<!-- https://docs.runflow.io/concepts/runs -->

A **run** is one execution of a model. You create runs with `POST /v1/models/{model_id}/runs`. The `model_id` segment is the model's `provider/slug` and may be more than two segments deep (e.g. `bytedance/seedance/2.0/fast/text-to-video`). Each run has an `id`, a `status_code`, optional logs, and optional node-runs (steps inside a multi-step model).

## Create a run

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "prompt": "..." },
    "callback_url": "https://your-server.com/webhook"
  }'
```

The response returns immediately with the run's `id` and `status_code: queued`. Save the `id`; that's what every other run endpoint takes.

## Lifecycle

| `status_code` | Meaning |
|---|---|
| `queued` | Accepted, waiting for compute. |
| `dispatching` | Being submitted to the execution provider. |
| `running` | Executing. |
| `succeeded` | Finished, outputs ready. |
| `failed` | Error during execution. See `failure_message`. |
| `cancelled` | You cancelled it. |
| `partial_succeeded` | Batch-only terminal status. Individual runs do not use it. |

Full enum: [`GET /v1/runs/statuses`](/api-reference/runs/list-run-statuses).

## Get the result

Runs are asynchronous by default. Decide per request whether to receive the final payload by callback or by polling.

- **Callback (recommended).** Provide `callback_url` on the create-run request. Runflow POSTs the event envelope there when the run reaches a terminal state. See [Callbacks](/concepts/callbacks).
- **Polling.** Omit `callback_url`. Poll [`GET /v1/runs/{id}`](/api-reference/runs/get-run) until `status_code` is terminal.

Some models also expose a model-specific `sync_mode` input for inline output. Use it only when the individual [model page](/models) documents `sync_mode` and you intentionally want the response body to carry media data. It is per-model, not platform-wide.

## Inspect a run

```bash
curl https://api.runflow.io/v1/runs/{id} \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Other reads:

- [`GET /v1/runs/{id}/logs`](/api-reference/runs/search-run-logs) - structured log lines.
- [`GET /v1/runs/{id}/node-runs`](/api-reference/runs/search-flow-node-runs) - per-step records for multi-step models.
- [`GET /v1/runs/{id}/callback`](/api-reference/runs/get-callback-delivery-history) - the event-envelope payload Runflow delivered (or attempted to deliver) to your `callback_url`. Same shape documented under [Callbacks](/concepts/callbacks).

## Related


  Async result delivery.
  Run a model on many inputs in one request.
  Failed run shape.

---

# Batch process media
<!-- https://docs.runflow.io/guides/batch-process-media -->

## What you'll do

Process a folder of product shots through one model in a single call. One callback fires when every item is done.

## Prerequisites

- A Runflow API key. [Create one.](https://app.runflow.io/settings/api-keys)
- The model you want to run. Pick one from [`/models`](/models).
- A list of input URLs or asset IDs.

## Steps


  
    `POST /v1/models/{model_id}/batches` with an array of items, where `{model_id}` is the slash-delimited provider/model path shown on the model page. Each item is a separate run.

    ```bash
    curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/batches \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "items": [
          { "input": { "image_url": "https://...01.jpg", "prompt": "white studio" } },
          { "input": { "image_url": "https://...02.jpg", "prompt": "white studio" } },
          { "input": { "image_url": "https://...03.jpg", "prompt": "white studio" } }
        ],
        "callback_url": "https://your-server.com/webhook"
      }'
    ```

    Response:

    ```json
    { "id": "01J0...", "status_code": "queued", "items_total": 3 }
    ```
  
  
    Either poll [`GET /v1/batches/{id}`](/api-reference/batches/get-batch-detail) or wait for the callback. Batch records expose `status_code`; terminal callback payloads expose the same value as `status`. Batches can also finish as `partial_succeeded`.
  
  
    [`GET /v1/batches/{id}/items`](/api-reference/batches/list-batch-items-with-live-execution-state) returns one entry per input with the resolved `run_id`, `status_code`, and outputs.
  


## Verify it worked

```json
{
  "id": "batch_01J0...",
  "status_code": "succeeded",
  "items_total": 3,
  "items_succeeded": 3,
  "items_failed": 0
}
```

`items_failed: 0`? You're done.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Some items fail, others succeed | Per-input validation error | Read each failed item's `failure_message`. |
| Whole batch fails fast | Auth or quota | Check the [balance](/concepts/pricing). |
| Callback never arrives | URL not reachable | See [Callbacks: local development](/concepts/callbacks). |

## Related


  Single-input lifecycle.
  Async result delivery.

---

# Handle async callbacks
<!-- https://docs.runflow.io/guides/handle-async-callbacks -->

## What you'll do

Stand up a webhook handler that takes a Runflow callback, persists the result, and returns `200` fast.

## Prerequisites

- A Runflow API key. [Create one.](https://app.runflow.io/settings/api-keys)
- A public URL for the handler. Use [ngrok](https://ngrok.com) for local dev.
- A database or queue to persist results.

## Steps


  
    The handler should: parse the body, persist the relevant fields, return `200` within a few seconds.

    These examples parse JSON directly for a local prototype. In production, verify `Runflow-Signature` against the raw request body before parsing JSON; see [Verify callback signatures](/guides/verify-callback-signatures).

    

    ```javascript Express
    import express from "express";
    const app = express();
    app.use(express.json({ limit: "5mb" }));

    app.post("/webhook/runflow", async (req, res) => {
      const { event, run_id, status, output } = req.body;

      // Persist immediately. Output URLs are presigned; copy them to your storage.
      await db.runs.upsert({ run_id, event, status, output });

      res.sendStatus(200);
      // Heavy work (downloading outputs) goes in a background job.
    });

    app.listen(3000);
    ```

    ```python FastAPI
    from fastapi import FastAPI, Request
    app = FastAPI()

    @app.post("/webhook/runflow")
    async def runflow_webhook(req: Request):
        body = await req.json()
        await db.runs.upsert(
            run_id=body["run_id"],
            event=body["event"],
            status=body["status"],
            output=body.get("output"),
        )
        return {"ok": True}
    ```

    
  
  
    ```bash
    curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "input": { "image_url": "https://...", "prompt": "..." },
        "callback_url": "https://your-server.com/webhook/runflow"
      }'
    ```
  
  
    Runflow retries failed callbacks. Match on `run_id` for run callbacks or `batch_id` for batch callbacks, and skip if you have already processed it.

    ```javascript
    const existing = await db.runs.findByRunId(run_id);
    if (existing?.status === "succeeded") return res.sendStatus(200);
    ```
  
  
    Output URLs are presigned and time-limited. Download or re-upload them to your own bucket on receipt. Do not store the raw URLs as your source of truth.
  


## Verify it worked

Trigger a run, watch your handler logs:

```
POST /webhook/runflow 200 1234ms
{ event: 'run.completed', run_id: '01J0...', status: 'succeeded' }
```

You have a row in your DB with `status: succeeded`. You're done.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Callback arrives but body is empty | Missing body parser | For unsigned prototypes, use `express.json()` or framework equivalent. For signed handlers, read the raw body first. |
| Handler times out | Heavy work in the request | Return `200` first, defer heavy work. |
| Same payload arrives twice | Retry on a 5xx your handler returned | Be idempotent on `run_id`. |
| Nothing arrives | URL not public | Use ngrok or Cloudflare Tunnel for local dev. |

## Production hardening

- [Verify the signature](/guides/verify-callback-signatures) so spoofed POSTs cannot reach your DB.
- Wrap your handler in a queue (SQS, Pub/Sub, BullMQ) so a slow downstream cannot drop callbacks.
- Monitor `4xx` and `5xx` from your endpoint. Runflow stops retrying after a few attempts.

## Related


  HMAC verify in code.
  Pattern, retries, redelivery.

---

# Pick a model
<!-- https://docs.runflow.io/guides/pick-a-model -->

## What you'll do

Match a task to the right Runflow model in under a minute.

## Decision tree

| Task | Reach for | Why |
|---|---|---|
| Replace a product photo background | [`runflow/background-replace`](/models/runflow/background-replace) | Preserves the foreground subject, matches new lighting. |
| Remove a background only | [`bria/background/remove`](/models/bria/background/remove) | Cheap and fast. |
| Remove a person, sign, or logo | [`runflow/object-removal`](/models/runflow/object-removal) | Inpaint with no prompt needed. |
| Change eye color | [`runflow/eye-color`](/models/runflow/eye-color) | Targeted edit, identity-preserving. |
| Edit any image with a prompt | [`google/nano-banana-2/edit`](/models/google/nano-banana-2/edit) or [`black-forest-labs/flux-pro/kontext`](/models/black-forest-labs/flux-pro/kontext) | Best general-purpose edit. |
| Generate an image from text | [`google/nano-banana-pro`](/models/google/nano-banana-pro) | High-quality general-purpose text-to-image. |
| Generate a video from text | [`google/veo3.1`](/models/google/veo3.1) or [`bytedance/seedance/2.0/text-to-video`](/models/bytedance/seedance/2.0/text-to-video) | veo3.1 for cinematic, seedance for speed. |
| Animate a still image | [`google/veo3.1/image-to-video`](/models/google/veo3.1/image-to-video) | Image-to-video conditioning. |
| Add character to a video | [`heygen/v3/video-agent`](/models/heygen/v3/video-agent) | Avatar-driven. |
| Generate speech | [`elevenlabs/tts/eleven-v3`](/models/elevenlabs/tts/eleven-v3) | High-fidelity TTS. |
| Upscale a photo | [`topaz/upscale/image`](/models/topaz/upscale/image) | Up to 4x with detail recovery. |

Browse the full catalog in [/models](/models).

## Three things to check before you pick

1. **Pricing unit.** `$/request` (flat) vs `$/megapixel` vs `$/second` (video). Map to your average asset size.
2. **Result delivery.** Runs are asynchronous by default. Use [callbacks](/concepts/callbacks) or polling unless the model page documents `sync_mode` and you intentionally want inline output.
3. **Inputs.** Most edit models accept either a public URL or an upload. Read the model page for required input keys.

## Try one

Pick a model from the table, open its page, and copy the curl block. The samples come straight from the per-model `llms.txt` and most use the literal string `Bearer RUNFLOW_API_KEY` rather than an env-var. Substitute your actual token before running, or change the header to `Bearer $RUNFLOW_API_KEY` (curl) / `Bearer ${process.env.RUNFLOW_API_KEY}` (Node) / `f"Bearer {os.environ['RUNFLOW_API_KEY']}"` (Python).

## Related


  Full filterable catalog.
  5-minute walkthrough.

---

# Upload large files
<!-- https://docs.runflow.io/guides/upload-large-files -->

## What you'll do

Upload a video or large image directly to Runflow's storage and reference the resulting asset by ID in subsequent run requests.

## When to use this

`POST /v1/asset-uploads` accepts `size_bytes` up to 50 MiB (52,428,800 bytes); larger uploads are rejected at create time.

| Input size | Approach |
|---|---|
| &lt; 1 MiB | Inline base64 or a public URL is fine. |
| 1 MiB to 50 MiB | Inline if convenient, presigned upload if you control the server. |
| &gt; 50 MiB | Not supported by the asset-upload API. Host the file at a public URL and pass that URL on the run. |

## Prerequisites

- A Runflow API key.
- The file on disk or in memory.

## Steps


  
    Get a presigned URL. Tell Runflow the filename, MIME type, and exact byte size.

    ```bash
    curl -X POST https://api.runflow.io/v1/asset-uploads \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "filename": "perfume-bottle.webp",
        "mime_type": "image/webp",
        "size_bytes": 2400000
      }'
    ```

    Response (201 Created):

    ```json
    {
      "asset_id": "01J0...",
      "upload_url": "https://storage.runflow.io/..."
    }
    ```
  
  
    Use the URL exactly as returned. No auth header, the presigned URL carries the credentials.

    ```bash
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: image/webp" \
      --upload-file ./perfume-bottle.webp
    ```
  
  
    Tell Runflow the upload is complete. The body is optional; pass `folder_id` to file the asset under a folder.

    ```bash
    curl -X POST https://api.runflow.io/v1/asset-uploads/{asset_upload_id}/confirmations \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    Response (201 Created) is the full Asset record. The fields you'll most often read:

    ```json
    {
      "id": "01J0...",
      "name": "perfume-bottle.webp",
      "mime_type": "image/webp",
      "size_bytes": 2400000,
      "url": "https://...",
      "thumbnail_url": "https://...",
      "asset_type": "image",
      "folder_id": null,
      "created_at": "2026-05-06T10:00:00Z"
    }
    ```
  
  
    Reference it by `id` (or by `url` if the model accepts a public URL):

    ```bash
    curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "input": {
          "asset_id": "01J0...",
          "prompt": "white studio"
        },
        "callback_url": "https://your-server.com/webhook"
      }'
    ```
  


## Verify it worked

```bash
curl https://api.runflow.io/v1/assets/{id} \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

A `200` with the Asset payload confirms it is usable.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `403` on the PUT | Presigned URL expired | Re-create with `POST /v1/asset-uploads`. |
| `422` on create | Size or MIME type rejected | `size_bytes` max is 50 MiB; check `mime_type` against the supported list at [`GET /v1/assets/types`](/api-reference/media/list-asset-types). |
| Asset never confirmed | Confirmation step skipped | POST to the confirmations endpoint. |

## Related


  List, get, delete assets.
  Organize uploads.

---

# Verify callback signatures
<!-- https://docs.runflow.io/guides/verify-callback-signatures -->

## What you'll do

Reject spoofed POSTs to your webhook by verifying the `Runflow-Signature` HMAC header against a shared secret.

## Prerequisites

- A Runflow API key.
- A webhook handler (see [Handle async callbacks](/guides/handle-async-callbacks)).

## Steps


  
    ```bash
    curl -X POST https://api.runflow.io/v1/callback-secrets \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "label": "production" }'
    ```

    Response:

    ```json
    { "id": "01J0...", "label": "production", "plain_secret": "whsec_..." }
    ```

    Save `plain_secret` to your secret manager. It is shown once.
  
  
    Runflow sends `Runflow-Signature: <hex>` where the value is `HMAC-SHA256(secret, raw_body)`. The hex string is 64 chars (SHA-256 digest size).

    

    ```javascript Express
    import crypto from "crypto";
    import express from "express";
    const app = express();

    // Use raw body, not parsed JSON, for HMAC.
    app.use(express.raw({ type: "application/json" }));

    const SIG_LEN = 64; // hex chars in HMAC-SHA256

    app.post("/webhook/runflow", (req, res) => {
      const signature = req.header("Runflow-Signature") || "";
      if (!/^[0-9a-f]{64}$/.test(signature)) {
        return res.sendStatus(401);
      }
      const expected = crypto
        .createHmac("sha256", process.env.RUNFLOW_WEBHOOK_SECRET)
        .update(req.body)
        .digest("hex");
      const a = Buffer.from(signature, "hex");
      const b = Buffer.from(expected, "hex");
      if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
        return res.sendStatus(401);
      }

      const payload = JSON.parse(req.body.toString("utf8"));
      // ...persist payload, return 200...
      res.sendStatus(200);
    });
    ```

    ```python FastAPI
    import hmac, hashlib, os, re
    from fastapi import FastAPI, Request, HTTPException

    app = FastAPI()
    SECRET = os.environ["RUNFLOW_WEBHOOK_SECRET"].encode()
    HEX_64 = re.compile(r"^[0-9a-f]{64}$")

    @app.post("/webhook/runflow")
    async def runflow_webhook(req: Request):
        body = await req.body()
        signature = req.headers.get("Runflow-Signature", "")
        if not HEX_64.match(signature):
            raise HTTPException(401, "bad signature")
        expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
        if not hmac.compare_digest(signature, expected):
            raise HTTPException(401, "bad signature")
        payload = await req.json()
        # ...persist, return 200...
        return {"ok": True}
    ```

    
  
  
    Always compare with `crypto.timingSafeEqual` (Node) or `hmac.compare_digest` (Python). Plain `==` leaks timing info. Both inputs must be the same length, hence the regex pre-check above.
  


## Verify it worked

Send a test callback (re-deliver one):

```bash
curl -X POST https://api.runflow.io/v1/runs/{run_id}/callback-redeliveries \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Your handler logs should show `200`. Now send a forged POST without the header. Your handler should return `401`.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Every callback fails verification | Hashing parsed JSON instead of raw body | Use the raw bytes Runflow sent. |
| Signatures match in dev, fail in prod | Different secret per env | Rotate, redeploy. |
| `Runflow-Signature` header missing | No callback secret registered for this endpoint | POST to `/v1/callback-secrets` first. |

## Rotation

Create a second secret. Both verify in parallel during cutover. Delete the old secret once traffic confirms the new one works.

## Related


  Handler structure.
  Pattern, retries.

---

# Runflow
<!-- https://docs.runflow.io/ -->

Start AI image and video runs with one HTTP call, then receive results by callback or polling. The Runflow API exposes a curated catalog of [50 models](/models) from Runflow, Google, Alibaba, OpenAI, and others. Auth is HTTP Bearer.

## Five-minute quickstart

```bash
export RUNFLOW_API_KEY="your_key"

curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "prompt": "white studio", "image_url": "https://..." } }'
```

Get a key at [app.runflow.io](https://app.runflow.io/settings/api-keys). Full walkthrough at [Quickstart](/quickstart).

## Where to go next


  50 models, 6 categories, prices and endpoints.
  First call in under 5 minutes.
  Generated from the public OpenAPI spec.
  Skill, llms.txt, OpenAPI catalog.


## Concepts


  Bearer header.
  Callbacks, polling, statuses.
  Async result delivery.
  Status codes, error envelope.
  Per-request, per-second, per-megapixel.
  Headers and backoff.


## Guides


  Decision tree from task to model.
  Many inputs, one request.
  Webhook handler patterns.
  HMAC verification.

---

# Happy Horse Image-to-Video
<!-- https://docs.runflow.io/models/alibaba/happy-horse/image-to-video -->

Pricing: **$0.14/second**. Endpoint: `POST /v1/models/alibaba/happy-horse/image-to-video/runs`.


Alibaba's #1-ranked Happy Horse 1.0 - generate 1080p video with synchronized native audio and multilingual lip-sync from text prompts or images.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/happy-horse/image-to-video/runs
- **Model ID**: alibaba/happy-horse/image-to-video
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.14/second
- **Note**: Per second of generated video (720p baseline)

# Happy Horse Image-to-Video API

**Endpoint:** `POST /v1/models/alibaba/happy-horse/image-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/happy-horse/image-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "She smiles warmly and looks toward the camera, gentle breeze in her hair",
            "duration": 5,
            "image_url": "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=1024&q=80",
            "resolution": "720p"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/happy-horse/image-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "She smiles warmly and looks toward the camera, gentle breeze in her hair",
            "duration": 5,
            "image_url": "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=1024&q=80",
            "resolution": "720p"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/happy-horse/image-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "She smiles warmly and looks toward the camera, gentle breeze in her hair",
        "duration": 5,
        "image_url": "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=1024&q=80",
        "resolution": "720p"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the first frame image. Formats: JPEG, JPG, PNG, BMP, WEBP. Dimensions must be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1. Max 10 MB. |
| `duration` | integer | optional | Any | Output video duration in seconds (3-15). |
| `prompt` | string | optional | Any | Optional text prompt guiding the animation. Max 2500 characters. |
| `enable_safety_checker` | boolean | optional | Any | Enable content moderation for input and output. |
| `resolution` | string | optional | `720p`, `1080p` | Output video resolution tier. |
| `seed` | integer | optional | Any | Random seed for reproducibility (0-2147483647). |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/happy-horse/image-to-video)
- [API Reference](https://app.runflow.io/models/alibaba/happy-horse/image-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Happy Horse Reference-to-Video
<!-- https://docs.runflow.io/models/alibaba/happy-horse/reference-to-video -->

Pricing: **$0.14/second**. Endpoint: `POST /v1/models/alibaba/happy-horse/reference-to-video/runs`.


Generate 1080p video with synchronized native audio from a text prompt and references. Aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4. Duration: 3–15s.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs
- **Model ID**: alibaba/happy-horse/reference-to-video
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.14/second
- **Note**: Per second of generated video (720p baseline)

# Happy Horse Reference-to-Video API

**Endpoint:** `POST /v1/models/alibaba/happy-horse/reference-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "character1 walks confidently down a neon-lit Tokyo street at night, cinematic lighting, smooth tracking shot",
            "duration": 5,
            "image_urls": [
                "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=1024&q=80"
            ],
            "resolution": "720p",
            "aspect_ratio": "16:9"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "character1 walks confidently down a neon-lit Tokyo street at night, cinematic lighting, smooth tracking shot",
            "duration": 5,
            "image_urls": [
                "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=1024&q=80"
            ],
            "resolution": "720p",
            "aspect_ratio": "16:9"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "character1 walks confidently down a neon-lit Tokyo street at night, cinematic lighting, smooth tracking shot",
        "duration": 5,
        "image_urls": [
            "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=1024&q=80"
        ],
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the desired video. Reference subjects from your images using ``character1``, ``character2``, ... up to ``character9`` (the order matches the order of ``image_urls``). Max 2500 characters. |
| `image_urls` | image_list | required | Any | Reference images for subject consistency (1-9 images). Formats: JPEG, JPG, PNG, WEBP. Shortest side must be at least 400 px (720P or higher recommended). Max 10 MB each. |
| `aspect_ratio` | string | optional | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` | Aspect ratio of the generated video. |
| `duration` | integer | optional | Any | Output video duration in seconds (3-15). |
| `enable_safety_checker` | boolean | optional | Any | Enable content moderation for input and output. |
| `resolution` | string | optional | `720p`, `1080p` | Output video resolution tier. |
| `seed` | integer | optional | Any | Random seed for reproducibility (0-2147483647). |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/happy-horse/reference-to-video)
- [API Reference](https://app.runflow.io/models/alibaba/happy-horse/reference-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Happy Horse Text-to-Video
<!-- https://docs.runflow.io/models/alibaba/happy-horse/text-to-video -->

Pricing: **$0.14/second**. Endpoint: `POST /v1/models/alibaba/happy-horse/text-to-video/runs`.


Generate 1080p video with synchronized native audio from a text prompt. Aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4. Duration: 3–15s.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/happy-horse/text-to-video/runs
- **Model ID**: alibaba/happy-horse/text-to-video
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.14/second
- **Note**: Per second of generated video (720p baseline)

# Happy Horse Text-to-Video API

**Endpoint:** `POST /v1/models/alibaba/happy-horse/text-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/happy-horse/text-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A cinematic shot of a hummingbird hovering near a vibrant red flower in slow motion, golden hour lighting, shallow depth of field",
            "duration": 5,
            "resolution": "720p",
            "aspect_ratio": "16:9"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/happy-horse/text-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A cinematic shot of a hummingbird hovering near a vibrant red flower in slow motion, golden hour lighting, shallow depth of field",
            "duration": 5,
            "resolution": "720p",
            "aspect_ratio": "16:9"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/happy-horse/text-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A cinematic shot of a hummingbird hovering near a vibrant red flower in slow motion, golden hour lighting, shallow depth of field",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the desired video. Max 2500 characters. |
| `aspect_ratio` | string | optional | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` | Aspect ratio of the generated video. |
| `duration` | integer | optional | Any | Output video duration in seconds (3-15). |
| `enable_safety_checker` | boolean | optional | Any | Enable content moderation for input and output. |
| `resolution` | string | optional | `720p`, `1080p` | Output video resolution tier. |
| `seed` | integer | optional | Any | Random seed for reproducibility (0-2147483647). |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/happy-horse/text-to-video)
- [API Reference](https://app.runflow.io/models/alibaba/happy-horse/text-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Happy Horse Video Edit
<!-- https://docs.runflow.io/models/alibaba/happy-horse/video-edit -->

Pricing: **$0.28/second**. Endpoint: `POST /v1/models/alibaba/happy-horse/video-edit/runs`.


HappyHorse video editing supports advanced video editing through natural language instructions. It allows for local or global editing of video elements using up to 5 reference images.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/happy-horse/video-edit/runs
- **Model ID**: alibaba/happy-horse/video-edit
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.28/second
- **Note**: Per second of edited video (720p baseline)

# Happy Horse Video Edit API

**Endpoint:** `POST /v1/models/alibaba/happy-horse/video-edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/happy-horse/video-edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Replace the underwater background with deep cosmic space, the jellyfish becomes a glowing nebula creature among shimmering stars",
            "video_url": "https://public.runflow.io/images/models/_shared/source-videos/jellyfish-1080.mp4",
            "resolution": "720p"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/happy-horse/video-edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Replace the underwater background with deep cosmic space, the jellyfish becomes a glowing nebula creature among shimmering stars",
            "video_url": "https://public.runflow.io/images/models/_shared/source-videos/jellyfish-1080.mp4",
            "resolution": "720p"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/happy-horse/video-edit/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Replace the underwater background with deep cosmic space, the jellyfish becomes a glowing nebula creature among shimmering stars",
        "video_url": "https://public.runflow.io/images/models/_shared/source-videos/jellyfish-1080.mp4",
        "resolution": "720p"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the desired edit. Reference any supplied reference images using @Image1, @Image2, ... up to @Image5. Max 2500 characters. |
| `video_url` | video | required | Any | URL of the source video to edit. Formats: MP4, MOV (H.264 recommended). Duration: 3-60 s. Longer side ≤ 2160 px, shorter side ≥ 320 px. Aspect ratio between 1:2.5 and 2.5:1. Frame rate > 8 fps. Max 100 MB. The output video preserves the source aspect ratio. Output duration matches the input video, capped at 15 s (longer inputs are truncated to the first 15 s). |
| `audio_setting` | string | optional | `auto`, `origin` | Audio handling. 'auto': model decides whether to regenerate audio. 'origin': preserve the original audio from the input video. |
| `enable_safety_checker` | boolean | optional | Any | Enable content moderation for input and output. |
| `reference_image_urls` | image_list | optional | Any | Optional reference images used to guide the edit (up to 5). Formats: JPEG, JPG, PNG, WEBP. Dimensions must be at least 300px. Aspect ratio between 1:2.5 and 2.5:1. Max 10 MB each. |
| `resolution` | string | optional | `720p`, `1080p` | Output video resolution tier. |
| `seed` | integer | optional | Any | Random seed for reproducibility (0-2147483647). |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/happy-horse/video-edit)
- [API Reference](https://app.runflow.io/models/alibaba/happy-horse/video-edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Qwen Image Edit 2511
<!-- https://docs.runflow.io/models/alibaba/qwen-image-edit-2511 -->

Pricing: **$0.03/megapixel**. Endpoint: `POST /v1/models/alibaba/qwen-image-edit-2511/runs`.


Advanced image editing model from Alibaba. Qwen Image Edit 2511 delivers superior text editing capabilities, multi-image support, and precise visual modifications through natural language instructions. Supports style transfer, object editing, and creative compositions.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/qwen-image-edit-2511/runs
- **Model ID**: alibaba/qwen-image-edit-2511
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.03/megapixel
- **Note**: Default price

# Qwen Image Edit 2511 API

**Endpoint:** `POST /v1/models/alibaba/qwen-image-edit-2511/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/qwen-image-edit-2511/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Move this person to a Mars colony habitat...",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/qwen-image-edit-2511/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Move this person to a Mars colony habitat...",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/qwen-image-edit-2511/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Move this person to a Mars colony habitat...",
        "image_urls": [
            "https://public.runflow.io/images/models/_shared/base-engineer.png"
        ]
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The prompt to edit the image with. |
| `num_images` | integer | optional | Any | The number of images to generate. |
| `acceleration` | string | optional | `none`, `regular`, `high` | The acceleration level to use. |
| `image_size` | string | optional | Any | The size of the generated image. If None, uses the input image dimensions. |
| `enable_safety_checker` | boolean | optional | Any | If set to true, the safety checker will be enabled. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | The format of the generated image. |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI. |
| `guidance_scale` | float | optional | Any | The guidance scale to use for the image generation. |
| `seed` | integer | optional | Any | The same seed and the same prompt given to the same version of the model will output the same image every time. |
| `image_urls` | image_list | required | Any | The URLs of the images to edit. |
| `negative_prompt` | string | optional | Any | The negative prompt to generate an image from. |
| `num_inference_steps` | integer | optional | Any | The number of inference steps to perform. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Seed of the generated Image. It will be the same value of the one passed in the             input or the randomly generated that was used in case none was passed. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/qwen-image-edit-2511)
- [API Reference](https://app.runflow.io/models/alibaba/qwen-image-edit-2511?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Wan 2.7 - Image to Video
<!-- https://docs.runflow.io/models/alibaba/wan/v2.7/image-to-video -->

Pricing: **$0.1/second**. Endpoint: `POST /v1/models/alibaba/wan/v2.7/image-to-video/runs`.


Wan 2.7 delivers enhanced motion smoothness, superior scene fidelity, and greater visual coherence.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/wan/v2.7/image-to-video/runs
- **Model ID**: alibaba/wan/v2.7/image-to-video
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.1/second
- **Note**: Per second of video

# Wan 2.7 - Image to Video API

**Endpoint:** `POST /v1/models/alibaba/wan/v2.7/image-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/wan/v2.7/image-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Product rotating slowly on a display pedestal, soft studio lighting, professional product photography",
            "duration": 5,
            "image_url": "https://public.runflow.io/images/models/_base/product-sneaker.png",
            "resolution": "1080p"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/wan/v2.7/image-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Product rotating slowly on a display pedestal, soft studio lighting, professional product photography",
            "duration": 5,
            "image_url": "https://public.runflow.io/images/models/_base/product-sneaker.png",
            "resolution": "1080p"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/wan/v2.7/image-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Product rotating slowly on a display pedestal, soft studio lighting, professional product photography",
        "duration": 5,
        "image_url": "https://public.runflow.io/images/models/_base/product-sneaker.png",
        "resolution": "1080p"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | optional | Any |  |
| `image_url` | image | optional | Any |  |
| `end_image_url` | image | optional | Any |  |
| `video_url` | video | optional | Any |  |
| `audio_url` | file | optional | Any |  |
| `resolution` | string | optional | `720p`, `1080p` |  |
| `duration` | integer | optional | Any |  |
| `negative_prompt` | string | optional | Any |  |
| `enable_prompt_expansion` | boolean | optional | Any |  |
| `seed` | integer | optional | Any |  |
| `enable_safety_checker` | boolean | optional | Any |  |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json |  |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/wan/v2.7/image-to-video)
- [API Reference](https://app.runflow.io/models/alibaba/wan/v2.7/image-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Wan 2.7 Pro Edit
<!-- https://docs.runflow.io/models/alibaba/wan/v2.7/pro/edit -->

Pricing: **$0.075/image**. Endpoint: `POST /v1/models/alibaba/wan/v2.7/pro/edit/runs`.


Edit and transform images using text instructions with the WAN 2.7 Pro model for precise, professional-grade image modifications.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/wan/v2.7/pro/edit/runs
- **Model ID**: alibaba/wan/v2.7/pro/edit
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.075/image
- **Note**: Per image

# Wan 2.7 Pro Edit API

**Endpoint:** `POST /v1/models/alibaba/wan/v2.7/pro/edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/wan/v2.7/pro/edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Turn the office into a cozy mountain cabin: snow falling outside the windows, exposed wooden beams on ceiling, stone fireplace crackling, warm amber light",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/wan/v2.7/pro/edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Turn the office into a cozy mountain cabin: snow falling outside the windows, exposed wooden beams on ceiling, stone fireplace crackling, warm amber light",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/wan/v2.7/pro/edit/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Turn the office into a cozy mountain cabin: snow falling outside the windows, exposed wooden beams on ceiling, stone fireplace crackling, warm amber light",
        "image_urls": [
            "https://public.runflow.io/images/models/_shared/base-engineer.png"
        ]
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the desired image edit. Supports Chinese and English. |
| `image_urls` | image_list | required | Any | Reference images for editing (1-4 images required). Order matters: reference them as image 1, image 2, image 3, image 4 in the prompt. |
| `negative_prompt` | string | optional | Any | Content to avoid in the generated image. Max 500 characters. |
| `image_size` | string | optional | Any | Output image size. Uses fal image size presets or explicit dimensions and is converted to DashScope size format. |
| `num_images` | integer | optional | Any | Number of images to generate (1-4). |
| `enable_prompt_expansion` | boolean | optional | Any | Enable DashScope prompt expansion. Supported only for image edit mode. |
| `seed` | integer | optional | Any | Random seed for reproducibility (0-2147483647). |
| `enable_safety_checker` | boolean | optional | Any | Enable content moderation for input and output. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | The seed used for generation. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/wan/v2.7/pro/edit)
- [API Reference](https://app.runflow.io/models/alibaba/wan/v2.7/pro/edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Wan 2.7 Text to Video
<!-- https://docs.runflow.io/models/alibaba/wan/v2.7/text-to-video -->

Pricing: **$0.1/second**. Endpoint: `POST /v1/models/alibaba/wan/v2.7/text-to-video/runs`.


Wan 2.7 is the latest generation AI video model, delivering enhanced motion smoothness, superior scene fidelity, and greater visual coherence.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/alibaba/wan/v2.7/text-to-video/runs
- **Model ID**: alibaba/wan/v2.7/text-to-video
- **Provider**: Alibaba
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.1/second
- **Note**: Per second of video

# Wan 2.7 Text to Video API

**Endpoint:** `POST /v1/models/alibaba/wan/v2.7/text-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/wan/v2.7/text-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Aerial drone shot pulling back slowly to reveal a vibrant coral reef teeming with tropical fish, crystal clear turquoise water, sunlight rays penetrating the surface",
            "duration": 5,
            "resolution": "1080p"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/wan/v2.7/text-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Aerial drone shot pulling back slowly to reveal a vibrant coral reef teeming with tropical fish, crystal clear turquoise water, sunlight rays penetrating the surface",
            "duration": 5,
            "resolution": "1080p"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/alibaba/wan/v2.7/text-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Aerial drone shot pulling back slowly to reveal a vibrant coral reef teeming with tropical fish, crystal clear turquoise water, sunlight rays penetrating the surface",
        "duration": 5,
        "resolution": "1080p"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the desired video. Max 5000 characters. |
| `audio_url` | file | optional | Any | URL of driving audio. Supports WAV and MP3. Duration: 3-30s. Max 15 MB. If not provided, the model auto-generates matching background music. |
| `aspect_ratio` | string | optional | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` | Aspect ratio of the generated video. |
| `resolution` | string | optional | `720p`, `1080p` | Output video resolution tier. |
| `duration` | integer | optional | `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | Output video duration in seconds (2-15). |
| `negative_prompt` | string | optional | Any | Content to avoid in the video. Max 500 characters. |
| `enable_prompt_expansion` | boolean | optional | Any | Enable intelligent prompt rewriting. |
| `seed` | integer | optional | Any | Random seed for reproducibility (0-2147483647). |
| `enable_safety_checker` | boolean | optional | Any | Enable content moderation for input and output. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | The seed used for generation. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/alibaba/wan/v2.7/text-to-video)
- [API Reference](https://app.runflow.io/models/alibaba/wan/v2.7/text-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# FLUX.2 [klein] 4B
<!-- https://docs.runflow.io/models/black-forest-labs/flux-2-klein-4b -->

Pricing: **$0.005/megapixel**. Endpoint: `POST /v1/models/black-forest-labs/flux-2-klein-4b/runs`.


Compact 4-billion parameter text-to-image model from Black Forest Labs. Step-distilled to 4 inference steps for sub-second generation. Unifies text-to-image and image editing in a single architecture with Apache 2.0 licensing.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-4b/runs
- **Model ID**: black-forest-labs/flux-2-klein-4b
- **Provider**: Black Forest Labs
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.005/megapixel
- **Note**: Per megapixel

# FLUX.2 [klein] 4B API

**Endpoint:** `POST /v1/models/black-forest-labs/flux-2-klein-4b/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-4b/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A vintage travel poster for 'RUNFLOW AIRWAYS' featuring a retro DC-3 airplane flying over snow-capped mountains at sunset, bold art deco typography, warm orange and teal color palette, textured paper grain, 1940s airline advertising style"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-4b/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A vintage travel poster for 'RUNFLOW AIRWAYS' featuring a retro DC-3 airplane flying over snow-capped mountains at sunset, bold art deco typography, warm orange and teal color palette, textured paper grain, 1940s airline advertising style"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-4b/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A vintage travel poster for 'RUNFLOW AIRWAYS' featuring a retro DC-3 airplane flying over snow-capped mountains at sunset, bold art deco typography, warm orange and teal color palette, textured paper grain, 1940s airline advertising style"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text description of the image to generate. |
| `image_size` | string | optional | `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9` | Size preset for the generated image. Alternatively use width/height for custom dimensions. |
| `num_images` | integer | optional | Any | Number of images to generate (1-4). |
| `num_inference_steps` | integer | optional | Any | Number of denoising steps. Default 4 for distilled variant, use higher for base variant. |
| `seed` | integer | optional | Any | Random seed for reproducible generation. Leave empty for random. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | Output image format. |
| `enable_safety_checker` | boolean | optional | Any | Enable NSFW content filtering. |
| `sync_mode` | boolean | optional | Any | Wait for the result synchronously instead of returning a request ID. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | The seed used for generation. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/black-forest-labs/flux-2-klein-4b)
- [API Reference](https://app.runflow.io/models/black-forest-labs/flux-2-klein-4b?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# FLUX.2 [klein] 9B
<!-- https://docs.runflow.io/models/black-forest-labs/flux-2-klein-9b -->

Pricing: **$0.006/megapixel**. Endpoint: `POST /v1/models/black-forest-labs/flux-2-klein-9b/runs`.


Text-to-image generation with FLUX.2 [klein] 9B from Black Forest Labs. Enhanced realism, crisper text generation, and native editing capabilities.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/runs
- **Model ID**: black-forest-labs/flux-2-klein-9b
- **Provider**: Black Forest Labs
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.006/megapixel
- **Note**: Per megapixel

# FLUX.2 [klein] 9B API

**Endpoint:** `POST /v1/models/black-forest-labs/flux-2-klein-9b/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A neon-lit Tokyo alleyway at night with a vending machine glowing amber, steam rising from grates, wet reflections on asphalt, cinematic",
            "image_size": "landscape_4_3",
            "output_format": "png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A neon-lit Tokyo alleyway at night with a vending machine glowing amber, steam rising from grates, wet reflections on asphalt, cinematic",
            "image_size": "landscape_4_3",
            "output_format": "png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A neon-lit Tokyo alleyway at night with a vending machine glowing amber, steam rising from grates, wet reflections on asphalt, cinematic",
        "image_size": "landscape_4_3",
        "output_format": "png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any |  |
| `seed` | integer | optional | Any |  |
| `num_inference_steps` | integer | optional | Any |  |
| `image_size` | string | optional | Any |  |
| `num_images` | integer | optional | Any |  |
| `sync_mode` | boolean | optional | Any |  |
| `enable_safety_checker` | boolean | optional | Any |  |
| `output_format` | string | optional | `jpeg`, `png`, `webp` |  |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json |  |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/black-forest-labs/flux-2-klein-9b)
- [API Reference](https://app.runflow.io/models/black-forest-labs/flux-2-klein-9b?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# FLUX.2 [klein] 9B - Edit
<!-- https://docs.runflow.io/models/black-forest-labs/flux-2-klein-9b/edit -->

Pricing: **$0.011/megapixel**. Endpoint: `POST /v1/models/black-forest-labs/flux-2-klein-9b/edit/runs`.


Image-to-image editing with FLUX.2 [klein] 9B from Black Forest Labs. Precise modifications using natural language descriptions and hex color control.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/edit/runs
- **Model ID**: black-forest-labs/flux-2-klein-9b/edit
- **Provider**: Black Forest Labs
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.011/megapixel
- **Note**: Per megapixel (input + output)

# FLUX.2 [klein] 9B - Edit API

**Endpoint:** `POST /v1/models/black-forest-labs/flux-2-klein-9b/edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Replace the computer monitors with a large glass aquarium full of colorful tropical fish and coral, the keyboard sits on a bed of white sand, small hermit crabs crawl on the mousepad, everything else stays the same",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Replace the computer monitors with a large glass aquarium full of colorful tropical fish and coral, the keyboard sits on a bed of white sand, small hermit crabs crawl on the mousepad, everything else stays the same",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/black-forest-labs/flux-2-klein-9b/edit/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Replace the computer monitors with a large glass aquarium full of colorful tropical fish and coral, the keyboard sits on a bed of white sand, small hermit crabs crawl on the mousepad, everything else stays the same",
        "image_urls": [
            "https://public.runflow.io/images/models/_shared/base-engineer.png"
        ]
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any |  |
| `image_urls` | image_list | required | Any |  |
| `seed` | integer | optional | Any |  |
| `num_inference_steps` | integer | optional | Any |  |
| `image_size` | string | optional | Any |  |
| `num_images` | integer | optional | Any |  |
| `sync_mode` | boolean | optional | Any |  |
| `enable_safety_checker` | boolean | optional | Any |  |
| `output_format` | string | optional | `jpeg`, `png`, `webp` |  |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json |  |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/black-forest-labs/flux-2-klein-9b/edit)
- [API Reference](https://app.runflow.io/models/black-forest-labs/flux-2-klein-9b/edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# FLUX Kontext
<!-- https://docs.runflow.io/models/black-forest-labs/flux-pro/kontext -->

Pricing: **$0.04/image**. Endpoint: `POST /v1/models/black-forest-labs/flux-pro/kontext/runs`.


FLUX.1 Kontext [pro] handles both text and reference images as inputs, seamlessly enabling targeted, local edits and complex transformations of entire scenes.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/black-forest-labs/flux-pro/kontext/runs
- **Model ID**: black-forest-labs/flux-pro/kontext
- **Provider**: Black Forest Labs
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.04/image
- **Note**: ~25 runs per $1

# FLUX Kontext API

**Endpoint:** `POST /v1/models/black-forest-labs/flux-pro/kontext/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/black-forest-labs/flux-pro/kontext/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Add a fluffy orange tabby cat sleeping on the desk between the two monitors, curled up on a small cushion, one paw draped over the keyboard. The cat is illuminated by the monitor glow. Everything else stays exactly the same.",
            "image_url": "https://public.runflow.io/images/models/_shared/base-engineer.png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/black-forest-labs/flux-pro/kontext/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Add a fluffy orange tabby cat sleeping on the desk between the two monitors, curled up on a small cushion, one paw draped over the keyboard. The cat is illuminated by the monitor glow. Everything else stays exactly the same.",
            "image_url": "https://public.runflow.io/images/models/_shared/base-engineer.png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/black-forest-labs/flux-pro/kontext/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Add a fluffy orange tabby cat sleeping on the desk between the two monitors, curled up on a small cushion, one paw draped over the keyboard. The cat is illuminated by the monitor glow. Everything else stays exactly the same.",
        "image_url": "https://public.runflow.io/images/models/_shared/base-engineer.png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Editing instruction describing the desired transformation. |
| `image_url` | image | required | Any | URL of the source image to edit. |
| `aspect_ratio` | string | optional | `21:9`, `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`, `9:21` | Output aspect ratio. Options: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9. |
| `num_images` | integer | optional | Any | Number of images to generate per request. Range: 1–4. Default: 1. |
| `guidance_scale` | float | optional | Any | How closely the model follows the prompt. Range: 1–20. Default: 3.5. |
| `output_format` | string | optional | `jpeg`, `png` | Output format. Options: "jpeg", "png". Default: "jpeg". |
| `safety_tolerance` | string | optional | Any | Content moderation strictness. 1 = most strict, 6 = most permissive. Default: 2. |
| `enhance_prompt` | boolean | optional | Any | Automatically enhance the prompt for better results. Default: false. |
| `seed` | integer | optional | Any | Random seed for reproducible outputs. |
| `sync_mode` | boolean | optional | Any | Return media as data URI without storing in request history. Default: false. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Seed of the generated Image. It will be the same value of the one passed in the             input or the randomly generated that was used in case none was passed. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/black-forest-labs/flux-pro/kontext)
- [API Reference](https://app.runflow.io/models/black-forest-labs/flux-pro/kontext?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Bria Background Remove
<!-- https://docs.runflow.io/models/bria/background/remove -->

Pricing: **$0.018/request**. Endpoint: `POST /v1/models/bria/background/remove/runs`.


Bria RMBG 2.0 enables seamless removal of backgrounds from images, ideal for professional editing tasks. Trained exclusively on licensed data for safe and risk-free commercial use.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/bria/background/remove/runs
- **Model ID**: bria/background/remove
- **Provider**: Bria AI
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.018/request
- **Note**: Usage-based, per generation

# Bria Background Remove API

**Endpoint:** `POST /v1/models/bria/background/remove/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/bria/background/remove/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "image_url": "https://public.runflow.io/images/models/alibaba/qwen-image-2/pro/text-to-image/example-output-0.webp",
            "sync_mode": True
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/bria/background/remove/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "image_url": "https://public.runflow.io/images/models/alibaba/qwen-image-2/pro/text-to-image/example-output-0.webp",
            "sync_mode": true
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/bria/background/remove/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "image_url": "https://public.runflow.io/images/models/alibaba/qwen-image-2/pro/text-to-image/example-output-0.webp",
        "sync_mode": true
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `image_url` | image | required | Any | Input Image to erase from |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/bria/background/remove)
- [API Reference](https://app.runflow.io/models/bria/background/remove?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Seedance 2.0 Fast Text to Video
<!-- https://docs.runflow.io/models/bytedance/seedance/2.0/fast/text-to-video -->

Pricing: **$0.2419/second**. Endpoint: `POST /v1/models/bytedance/seedance/2.0/fast/text-to-video/runs`.


Fast variant of Seedance 2.0 for quicker text-to-video generation with synchronized audio support.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/bytedance/seedance/2.0/fast/text-to-video/runs
- **Model ID**: bytedance/seedance/2.0/fast/text-to-video
- **Provider**: ByteDance
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.2419/second
- **Note**: Per second (720p)

# Seedance 2.0 Fast Text to Video API

**Endpoint:** `POST /v1/models/bytedance/seedance/2.0/fast/text-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/bytedance/seedance/2.0/fast/text-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A barista pours steaming latte art into a ceramic cup, close-up of milk swirling into a perfect rosetta pattern, espresso machine hissing, soft morning light through window"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/bytedance/seedance/2.0/fast/text-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A barista pours steaming latte art into a ceramic cup, close-up of milk swirling into a perfect rosetta pattern, espresso machine hissing, soft morning light through window"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/bytedance/seedance/2.0/fast/text-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A barista pours steaming latte art into a ceramic cup, close-up of milk swirling into a perfect rosetta pattern, espresso machine hissing, soft morning light through window"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt used to generate the video |
| `aspect_ratio` | string | optional | `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | The aspect ratio of the generated video. |
| `duration` | string | optional | `auto`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | Duration of the video in seconds. Supports 4 to 15 seconds, or auto. |
| `resolution` | string | optional | `480p`, `720p` | Video resolution - 480p for faster generation, 720p for balance. |
| `generate_audio` | boolean | optional | Any | Whether to generate synchronized audio for the video. |
| `seed` | integer | optional | Any | Random seed for reproducibility. |
| `end_user_id` | string | optional | Any | The unique user ID of the end user. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | The seed used for generation. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/bytedance/seedance/2.0/fast/text-to-video)
- [API Reference](https://app.runflow.io/models/bytedance/seedance/2.0/fast/text-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Seedance 2.0 Image to Video
<!-- https://docs.runflow.io/models/bytedance/seedance/2.0/image-to-video -->

Pricing: **$0.3024/second**. Endpoint: `POST /v1/models/bytedance/seedance/2.0/image-to-video/runs`.


Seedance 2.0 animates a starting frame image into video, with optional end frame for controlled transitions. Supports synchronized audio generation.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/bytedance/seedance/2.0/image-to-video/runs
- **Model ID**: bytedance/seedance/2.0/image-to-video
- **Provider**: ByteDance
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.3024/second
- **Note**: Per second (720p)

# Seedance 2.0 Image to Video API

**Endpoint:** `POST /v1/models/bytedance/seedance/2.0/image-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/bytedance/seedance/2.0/image-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Clouds moving slowly across the sky, light shifting across the mountain peaks, gentle breeze in the grass",
            "image_url": "https://public.runflow.io/images/models/_base/landscape-mountain.png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/bytedance/seedance/2.0/image-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Clouds moving slowly across the sky, light shifting across the mountain peaks, gentle breeze in the grass",
            "image_url": "https://public.runflow.io/images/models/_base/landscape-mountain.png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/bytedance/seedance/2.0/image-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Clouds moving slowly across the sky, light shifting across the mountain peaks, gentle breeze in the grass",
        "image_url": "https://public.runflow.io/images/models/_base/landscape-mountain.png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | The URL of the starting frame image to animate. Supported formats: JPEG, PNG, WebP. Max 30 MB. |
| `prompt` | string | required | Any | The text prompt describing the desired motion and action for the video. |
| `end_image_url` | image | optional | Any | The URL of the image to use as the last frame of the video. When provided, the generated video will transition from the starting image to this ending image. Supported formats: JPEG, PNG, WebP. Max 30 MB. |
| `aspect_ratio` | string | optional | `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | The aspect ratio of the generated video. Auto infers from the input image. |
| `duration` | string | optional | `auto`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | Duration of the video in seconds. Supports 4 to 15 seconds, or auto. |
| `resolution` | string | optional | `480p`, `720p`, `1080p` | Video resolution - 480p for faster generation, 720p for balance. |
| `generate_audio` | boolean | optional | Any | Whether to generate synchronized audio for the video. |
| `seed` | integer | optional | Any | Random seed for reproducibility. |
| `end_user_id` | string | optional | Any | The unique user ID of the end user. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | The seed used for generation. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/bytedance/seedance/2.0/image-to-video)
- [API Reference](https://app.runflow.io/models/bytedance/seedance/2.0/image-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Seedance 2.0 Text to Video
<!-- https://docs.runflow.io/models/bytedance/seedance/2.0/text-to-video -->

Pricing: **$0.3034/second**. Endpoint: `POST /v1/models/bytedance/seedance/2.0/text-to-video/runs`.


Seedance 2.0 generates high-quality videos from text prompts with synchronized audio including sound effects, ambient sounds, and lip-synced speech.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/bytedance/seedance/2.0/text-to-video/runs
- **Model ID**: bytedance/seedance/2.0/text-to-video
- **Provider**: ByteDance
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.3034/second
- **Note**: Per second (720p)

# Seedance 2.0 Text to Video API

**Endpoint:** `POST /v1/models/bytedance/seedance/2.0/text-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/bytedance/seedance/2.0/text-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A street musician plays violin on a cobblestone bridge in Prague at golden hour. Pedestrians stop to listen, a child drops a coin in the open case. Camera slowly orbits the musician, warm autumn light, falling leaves."
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/bytedance/seedance/2.0/text-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A street musician plays violin on a cobblestone bridge in Prague at golden hour. Pedestrians stop to listen, a child drops a coin in the open case. Camera slowly orbits the musician, warm autumn light, falling leaves."
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/bytedance/seedance/2.0/text-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A street musician plays violin on a cobblestone bridge in Prague at golden hour. Pedestrians stop to listen, a child drops a coin in the open case. Camera slowly orbits the musician, warm autumn light, falling leaves."
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt used to generate the video |
| `aspect_ratio` | string | optional | `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | The aspect ratio of the generated video. Use 16:9 for landscape, 9:16 for portrait/vertical, 1:1 for square, 21:9 for ultrawide cinematic, or auto to let the model decide. |
| `duration` | string | optional | `auto`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | Duration of the video in seconds. Supports 4 to 15 seconds, or auto to let the model decide based on the prompt. |
| `resolution` | string | optional | `480p`, `720p`, `1080p` | Video resolution - 480p for faster generation, 720p for balance. |
| `generate_audio` | boolean | optional | Any | Whether to generate synchronized audio for the video, including sound effects, ambient sounds, and lip-synced speech. The cost of video generation is the same regardless of whether audio is generated or not. |
| `seed` | integer | optional | Any | Random seed for reproducibility. Note that results may still vary slightly even with the same seed. |
| `end_user_id` | string | optional | Any | The unique user ID of the end user. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | The seed used for generation. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/bytedance/seedance/2.0/text-to-video)
- [API Reference](https://app.runflow.io/models/bytedance/seedance/2.0/text-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# ElevenLabs TTS v3
<!-- https://docs.runflow.io/models/elevenlabs/tts/eleven-v3 -->

Pricing: **$100/1m-tokens**. Endpoint: `POST /v1/models/elevenlabs/tts/eleven-v3/runs`.


Generate text-to-speech audio using Eleven-v3 from ElevenLabs.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/elevenlabs/tts/eleven-v3/runs
- **Model ID**: elevenlabs/tts/eleven-v3
- **Provider**: ElevenLabs
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $100/1m-tokens
- **Note**: Usage-based, per 1000 characters

# ElevenLabs TTS v3 API

**Endpoint:** `POST /v1/models/elevenlabs/tts/eleven-v3/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/elevenlabs/tts/eleven-v3/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "text": "Welcome to the Runflow Lab! This week we shipped five new models and honestly, the hardest part was naming them. Turns out, all the good AI names are taken."
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/elevenlabs/tts/eleven-v3/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "text": "Welcome to the Runflow Lab! This week we shipped five new models and honestly, the hardest part was naming them. Turns out, all the good AI names are taken."
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/elevenlabs/tts/eleven-v3/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "text": "Welcome to the Runflow Lab! This week we shipped five new models and honestly, the hardest part was naming them. Turns out, all the good AI names are taken."
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `text` | string | required | Any | The text to convert to speech |
| `voice` | string | optional | Any | The voice to use for speech generation |
| `language_code` | string | optional | Any | Language code (ISO 639-1) used to enforce a language for the model. |
| `stability` | float | optional | Any | Voice stability (0-1) |
| `apply_text_normalization` | string | optional | `auto`, `on`, `off` | This parameter controls text normalization with three modes: 'auto', 'on', and 'off'. When set to 'auto', the system will automatically decide whether to apply text normalization (e.g., spelling out numbers). With 'on', text normalization will always be applied, while with 'off', it will be skipped. |
| `timestamps` | boolean | optional | Any | Whether to return timestamps for each word in the generated speech |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/elevenlabs/tts/eleven-v3)
- [API Reference](https://app.runflow.io/models/elevenlabs/tts/eleven-v3?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Gemini TTS
<!-- https://docs.runflow.io/models/google/gemini-tts -->

Pricing: **$10/1m-tokens**. Endpoint: `POST /v1/models/google/gemini-tts/runs`.


Google's Gemini TTS converts text to realistic audio. 30 voice presets, multi-speaker synthesis (up to 10 speakers), 24+ languages, and inline style markers for expressive control.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/gemini-tts/runs
- **Model ID**: google/gemini-tts
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $10/1m-tokens
- **Note**: Per 1M tokens (flash, output-dominated)

# Gemini TTS API

**Endpoint:** `POST /v1/models/google/gemini-tts/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/gemini-tts/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {},
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/gemini-tts/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {},
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/gemini-tts/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {},
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text to convert to speech. Gemini TTS supports natural-language prompting for style, pace, accent, and emotional expression - include delivery instructions inline with the text (e.g. 'Say cheerfully: Have a wonderful day!'). For multi-speaker synthesis, prefix lines with speaker aliases defined in the speakers field (e.g. 'Alice: Hello!\nBob: Hi!'). Supports inline pace/style markers like [slowly], [whispering], [excited], [extremely fast]. |
| `speakers` | json | optional | Any | Multi-speaker voice configuration. When set, enables multi-speaker synthesis where different parts of the text are spoken by different voices. Each speaker needs a voice and a speaker_id (alias) that matches prefixes in the prompt. Requires gemini-2.5-pro-tts or gemini-2.5-flash-tts model. Not supported with gemini-2.5-flash-lite-preview-tts. |
| `output_format` | string | optional | `wav`, `mp3`, `ogg_opus` | Audio output format. mp3: compressed, small file size (recommended). wav: uncompressed PCM wrapped in WAV (24 kHz, 16-bit mono). ogg_opus: Ogg container with Opus codec, good quality-to-size ratio. |
| `model` | string | optional | `gemini-2.5-flash-tts`, `gemini-2.5-pro-tts` | Which Gemini TTS model to use. gemini-2.5-flash-tts: low latency, cost-efficient for everyday applications (recommended). gemini-2.5-pro-tts: highest quality, best for structured workflows like podcasts, audiobooks, and customer support. |
| `voice` | string | optional | `Achernar`, `Achird`, `Algenib`, `Algieba`, `Alnilam`, `Aoede`, `Autonoe`, `Callirrhoe`, `Charon`, `Despina`, `Enceladus`, `Erinome`, `Fenrir`, `Gacrux`, `Iapetus`, `Kore`, `Laomedeia`, `Leda`, `Orus`, `Pulcherrima`, `Puck`, `Rasalgethi`, `Sadachbia`, `Sadaltager`, `Schedar`, `Sulafat`, `Umbriel`, `Vindemiatrix`, `Zephyr`, `Zubenelgenubi` | Voice preset for single-speaker synthesis. 30 distinct voices are available. Ignored when speakers is set. Popular choices: Kore (strong, firm female), Puck (upbeat, lively male), Charon (calm, professional male), Zephyr (bright, clear female), Aoede (warm, melodic female). |
| `language_code` | string | optional | Any | Language for multilingual synthesis. When set, steers the model to speak in the specified language. Supports 24 GA languages and 60+ Preview languages. If not set, the model auto-detects the language from the text. |
| `temperature` | float | optional | Any | Controls the randomness of the speech output. Higher values produce more creative and varied delivery, while lower values make the output more predictable and focused. |
| `style_instructions` | string | optional | Any | Optional style and delivery instructions prepended to the prompt. Controls expressiveness, accent, pace, tone, and emotional expression using natural language. Use this to separate style control from the text content. Examples: 'Speak warmly and slowly', 'Read this as a dramatic newscast', 'Use a British accent with a cheerful tone', 'Whisper mysteriously'. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/gemini-tts)
- [API Reference](https://app.runflow.io/models/google/gemini-tts?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Nano Banana 2
<!-- https://docs.runflow.io/models/google/nano-banana-2 -->

Pricing: **$0.08/image**. Endpoint: `POST /v1/models/google/nano-banana-2/runs`.


Nano Banana 2 is Google's new state-of-the-art fast image generation and editing model

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/nano-banana-2/runs
- **Model ID**: google/nano-banana-2
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-13

## Pricing

- **Base price**: $0.08/image
- **Note**: Per image (1K default)

# Nano Banana 2 API

**Endpoint:** `POST /v1/models/google/nano-banana-2/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/nano-banana-2/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A bioluminescent treehouse hotel suspended between ancient redwood trees at twilight. Three geodesic glass pods connected by vine-wrapped rope bridges, each pod glowing turquoise from within. Orchids and phosphorescent mushrooms grow on the bark. A narrow wooden staircase spirals up the trunk. Mist drifts through the canopy."
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/nano-banana-2/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A bioluminescent treehouse hotel suspended between ancient redwood trees at twilight. Three geodesic glass pods connected by vine-wrapped rope bridges, each pod glowing turquoise from within. Orchids and phosphorescent mushrooms grow on the bark. A narrow wooden staircase spirals up the trunk. Mist drifts through the canopy."
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/nano-banana-2/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A bioluminescent treehouse hotel suspended between ancient redwood trees at twilight. Three geodesic glass pods connected by vine-wrapped rope bridges, each pod glowing turquoise from within. Orchids and phosphorescent mushrooms grow on the bark. A narrow wooden staircase spirals up the trunk. Mist drifts through the canopy."
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the image. 3–50,000 characters. |
| `resolution` | string | optional | `0.5K`, `1K`, `2K`, `4K` | Output resolution. Options: "0.5K", "1K", "2K", "4K". Default: "1K". Price varies by tier. |
| `aspect_ratio` | string | optional | `auto`, `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `4:1`, `1:4`, `8:1`, `1:8` | Image aspect ratio. Options: "21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16", "4:1", "1:4", "8:1", "1:8". Use "auto" to let the model decide. Default: "auto". |
| `enable_web_search` | boolean | optional | Any | Enable web search to ground generation in current information. +$0.015/image. Default: false. |
| `thinking_level` | string | optional | `minimal`, `high` | Enable model thinking. Options: "minimal", "high". Adds +$0.002/image at high level. Omit to disable. |
| `num_images` | integer | optional | Any | Number of images to generate. Range: 1–4. Default: 1. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | Output format. Options: "jpeg", "png", "webp". Default: "png". |
| `safety_tolerance` | string | optional | Any | Content moderation level. 1 = most strict, 6 = least strict. Default: 4. |
| `seed` | integer | optional | Any | Random seed for reproducible outputs. |
| `limit_generations` | boolean | optional | Any | Limit to 1 image per prompt round regardless of prompt instructions. Default: true. |
| `sync_mode` | boolean | optional | Any | Return media as data URI without storing in history. Default: false. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/nano-banana-2)
- [API Reference](https://app.runflow.io/models/google/nano-banana-2?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Nano Banana 2 - Edit
<!-- https://docs.runflow.io/models/google/nano-banana-2/edit -->

Pricing: **$0.08/image**. Endpoint: `POST /v1/models/google/nano-banana-2/edit/runs`.


Nano Banana 2 is Google's new state-of-the-art image generation and editing model

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/nano-banana-2/edit/runs
- **Model ID**: google/nano-banana-2/edit
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.08/image
- **Note**: Usage-based, per image

# Nano Banana 2 - Edit API

**Endpoint:** `POST /v1/models/google/nano-banana-2/edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/nano-banana-2/edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Transform this stained glass window into a massive underwater aquarium...",
            "image_urls": [
                "https://public.runflow.io/images/models/google/nano-banana-pro/example-output-0.webp"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/nano-banana-2/edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Transform this stained glass window into a massive underwater aquarium...",
            "image_urls": [
                "https://public.runflow.io/images/models/google/nano-banana-pro/example-output-0.webp"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/nano-banana-2/edit/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Transform this stained glass window into a massive underwater aquarium...",
        "image_urls": [
            "https://public.runflow.io/images/models/google/nano-banana-pro/example-output-0.webp"
        ]
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The prompt for image editing. |
| `aspect_ratio` | string | optional | Any | The aspect ratio of the generated image. Supports extreme ratios: 4:1, 1:4, 8:1, 1:8. |
| `enable_web_search` | boolean | optional | Any | Enable web search for the image generation task. This will allow the model to use the latest information from the web to generate the image. |
| `resolution` | string | optional | `0.5K`, `1K`, `2K`, `4K` | The resolution of the image to generate. |
| `num_images` | integer | optional | Any | The number of images to generate. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | The format of the generated image. |
| `thinking_level` | string | optional | Any | When set, enables model thinking with the given level ('minimal' or 'high') and includes thoughts in the generation. Omit to disable. |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `image_urls` | image_list | required | Any | The URLs of the images to use for image-to-image generation or image editing. |
| `limit_generations` | boolean | optional | Any | Experimental parameter to limit the number of generations from each round of prompting to 1. Set to `True` to to disregard any instructions in the prompt regarding the number of images to generate and ignore any intermediate images generated by the model. This may affect generation quality. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/nano-banana-2/edit)
- [API Reference](https://app.runflow.io/models/google/nano-banana-2/edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Nano Banana Pro
<!-- https://docs.runflow.io/models/google/nano-banana-pro -->

Pricing: **$0.15/image**. Endpoint: `POST /v1/models/google/nano-banana-pro/runs`.


Nano Banana Pro is Google's new state-of-the-art image generation and editing model

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/nano-banana-pro/runs
- **Model ID**: google/nano-banana-pro
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-13

## Pricing

- **Base price**: $0.15/image
- **Note**: Usage-based, per image

# Nano Banana Pro API

**Endpoint:** `POST /v1/models/google/nano-banana-pro/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/nano-banana-pro/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A cathedral made entirely of stained glass, viewed from inside looking up at the rose window ceiling. Sunlight streams through panels depicting vineyard scenes with grapes and golden wheat. The floor reflects rainbow light patterns. Photorealistic, shot on medium format camera, golden hour"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/nano-banana-pro/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A cathedral made entirely of stained glass, viewed from inside looking up at the rose window ceiling. Sunlight streams through panels depicting vineyard scenes with grapes and golden wheat. The floor reflects rainbow light patterns. Photorealistic, shot on medium format camera, golden hour"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/nano-banana-pro/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A cathedral made entirely of stained glass, viewed from inside looking up at the rose window ceiling. Sunlight streams through panels depicting vineyard scenes with grapes and golden wheat. The floor reflects rainbow light patterns. Photorealistic, shot on medium format camera, golden hour"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt to generate an image from. |
| `aspect_ratio` | string | optional | Any | The aspect ratio of the generated image. |
| `enable_web_search` | boolean | optional | Any | Enable web search for the image generation task. This will allow the model to use the latest information from the web to generate the image. |
| `resolution` | string | optional | `1K`, `2K`, `4K` | The resolution of the image to generate. |
| `num_images` | integer | optional | Any | The number of images to generate. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | The format of the generated image. |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `limit_generations` | boolean | optional | Any | Experimental parameter to limit the number of generations from each round of prompting to 1. Set to `True` to to disregard any instructions in the prompt regarding the number of images to generate. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/nano-banana-pro)
- [API Reference](https://app.runflow.io/models/google/nano-banana-pro?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Nano Banana Pro - Edit
<!-- https://docs.runflow.io/models/google/nano-banana-pro/edit -->

Pricing: **$0.15/image**. Endpoint: `POST /v1/models/google/nano-banana-pro/edit/runs`.


Nano Banana Pro is Google's new state-of-the-art image generation and editing model

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/nano-banana-pro/edit/runs
- **Model ID**: google/nano-banana-pro/edit
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.15/image
- **Note**: Usage-based, per image

# Nano Banana Pro - Edit API

**Endpoint:** `POST /v1/models/google/nano-banana-pro/edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/nano-banana-pro/edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Convert to Studio Ghibli anime style: soft watercolor textures, warm pastel lighting, the woman becomes an anime character with large expressive eyes, the monitors show hand-drawn code, the lamp glows with magical warmth, keep the same pose and composition",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/nano-banana-pro/edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Convert to Studio Ghibli anime style: soft watercolor textures, warm pastel lighting, the woman becomes an anime character with large expressive eyes, the monitors show hand-drawn code, the lamp glows with magical warmth, keep the same pose and composition",
            "image_urls": [
                "https://public.runflow.io/images/models/_shared/base-engineer.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/nano-banana-pro/edit/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Convert to Studio Ghibli anime style: soft watercolor textures, warm pastel lighting, the woman becomes an anime character with large expressive eyes, the monitors show hand-drawn code, the lamp glows with magical warmth, keep the same pose and composition",
        "image_urls": [
            "https://public.runflow.io/images/models/_shared/base-engineer.png"
        ]
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The prompt for image editing. |
| `aspect_ratio` | string | optional | Any | The aspect ratio of the generated image. |
| `enable_web_search` | boolean | optional | Any | Enable web search for the image generation task. This will allow the model to use the latest information from the web to generate the image. |
| `resolution` | string | optional | `1K`, `2K`, `4K` | The resolution of the image to generate. |
| `num_images` | integer | optional | Any | The number of images to generate. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | The format of the generated image. |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `image_urls` | image_list | required | Any | The URLs of the images to use for image-to-image generation or image editing. |
| `limit_generations` | boolean | optional | Any | Experimental parameter to limit the number of generations from each round of prompting to 1. Set to `True` to to disregard any instructions in the prompt regarding the number of images to generate. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/nano-banana-pro/edit)
- [API Reference](https://app.runflow.io/models/google/nano-banana-pro/edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Veo 3.1
<!-- https://docs.runflow.io/models/google/veo3.1 -->

Pricing: **$0.2/second**. Endpoint: `POST /v1/models/google/veo3.1/runs`.


Veo 3.1 by Google, the most advanced AI video generation model in the world. With sound on!

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/veo3.1/runs
- **Model ID**: google/veo3.1
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.2/second
- **Note**: Without audio

# Veo 3.1 API

**Endpoint:** `POST /v1/models/google/veo3.1/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/veo3.1/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "An astronaut in a white spacesuit with gold visor steps off a lander's bottom rung onto the surface of Mars. Their boot presses slowly into fine rust-red Martian dust, leaving a crisp bootprint. Red dust particles float upward in the low gravity, suspended in the thin atmosphere. The astronaut straightens up and looks toward the horizon - a vast, barren landscape of red-orange sand dunes and distant mountains under a butterscotch-pink sky. The small irregular moon Phobos is visible near the horizon. The astronaut's radio crackles and a voice says with emotion: 'Houston... it is even more beautiful than we imagined.' Wind-blown dust drifts past. 4K cinematic, anamorphic lens flare from the distant sun. Epic, historic moment.",
            "duration": "8s",
            "resolution": "4k",
            "aspect_ratio": "16:9",
            "generate_audio": True
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/veo3.1/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "An astronaut in a white spacesuit with gold visor steps off a lander's bottom rung onto the surface of Mars. Their boot presses slowly into fine rust-red Martian dust, leaving a crisp bootprint. Red dust particles float upward in the low gravity, suspended in the thin atmosphere. The astronaut straightens up and looks toward the horizon - a vast, barren landscape of red-orange sand dunes and distant mountains under a butterscotch-pink sky. The small irregular moon Phobos is visible near the horizon. The astronaut's radio crackles and a voice says with emotion: 'Houston... it is even more beautiful than we imagined.' Wind-blown dust drifts past. 4K cinematic, anamorphic lens flare from the distant sun. Epic, historic moment.",
            "duration": "8s",
            "resolution": "4k",
            "aspect_ratio": "16:9",
            "generate_audio": true
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/veo3.1/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "An astronaut in a white spacesuit with gold visor steps off a lander's bottom rung onto the surface of Mars. Their boot presses slowly into fine rust-red Martian dust, leaving a crisp bootprint. Red dust particles float upward in the low gravity, suspended in the thin atmosphere. The astronaut straightens up and looks toward the horizon - a vast, barren landscape of red-orange sand dunes and distant mountains under a butterscotch-pink sky. The small irregular moon Phobos is visible near the horizon. The astronaut's radio crackles and a voice says with emotion: 'Houston... it is even more beautiful than we imagined.' Wind-blown dust drifts past. 4K cinematic, anamorphic lens flare from the distant sun. Epic, historic moment.",
        "duration": "8s",
        "resolution": "4k",
        "aspect_ratio": "16:9",
        "generate_audio": true
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt describing the video you want to generate |
| `auto_fix` | boolean | optional | Any | Whether to automatically attempt to fix prompts that fail content policy or other validation checks by rewriting them. |
| `duration` | string | optional | `4s`, `6s`, `8s` | The duration of the generated video. |
| `generate_audio` | boolean | optional | Any | Whether to generate audio for the video. |
| `resolution` | string | optional | `720p`, `1080p`, `4k` | The resolution of the generated video. |
| `aspect_ratio` | string | optional | `16:9`, `9:16` | Aspect ratio of the generated video |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `negative_prompt` | string | optional | Any | A negative prompt to guide the video generation. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/veo3.1)
- [API Reference](https://app.runflow.io/models/google/veo3.1?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Veo 3.1 Fast
<!-- https://docs.runflow.io/models/google/veo3.1/fast -->

Pricing: **$0.1/second**. Endpoint: `POST /v1/models/google/veo3.1/fast/runs`.


Faster and more cost effective version of Google's Veo 3.1!

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/veo3.1/fast/runs
- **Model ID**: google/veo3.1/fast
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.1/second
- **Note**: Without audio

# Veo 3.1 Fast API

**Endpoint:** `POST /v1/models/google/veo3.1/fast/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/veo3.1/fast/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "First-person POV looking down at a pair of hands opening a premium matte black box on a clean white marble surface. Fingers lift the magnetic lid, revealing layers of black tissue paper. Hands carefully part the tissue paper to reveal a sleek titanium watch with a dark blue dial nestled in a velvet cushion. The brushed titanium case catches overhead light as the hands lift the watch out - you can see the weight of it. Fingers operate the butterfly clasp, then buckle the watch onto the left wrist. ASMR sounds: the soft click of the box lid, rustling tissue paper, the satisfying clasp click. Close-up, warm lighting, luxurious feel. Product commercial quality.",
            "duration": "8s",
            "resolution": "1080p",
            "aspect_ratio": "9:16",
            "generate_audio": True
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/veo3.1/fast/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "First-person POV looking down at a pair of hands opening a premium matte black box on a clean white marble surface. Fingers lift the magnetic lid, revealing layers of black tissue paper. Hands carefully part the tissue paper to reveal a sleek titanium watch with a dark blue dial nestled in a velvet cushion. The brushed titanium case catches overhead light as the hands lift the watch out - you can see the weight of it. Fingers operate the butterfly clasp, then buckle the watch onto the left wrist. ASMR sounds: the soft click of the box lid, rustling tissue paper, the satisfying clasp click. Close-up, warm lighting, luxurious feel. Product commercial quality.",
            "duration": "8s",
            "resolution": "1080p",
            "aspect_ratio": "9:16",
            "generate_audio": true
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/veo3.1/fast/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "First-person POV looking down at a pair of hands opening a premium matte black box on a clean white marble surface. Fingers lift the magnetic lid, revealing layers of black tissue paper. Hands carefully part the tissue paper to reveal a sleek titanium watch with a dark blue dial nestled in a velvet cushion. The brushed titanium case catches overhead light as the hands lift the watch out - you can see the weight of it. Fingers operate the butterfly clasp, then buckle the watch onto the left wrist. ASMR sounds: the soft click of the box lid, rustling tissue paper, the satisfying clasp click. Close-up, warm lighting, luxurious feel. Product commercial quality.",
        "duration": "8s",
        "resolution": "1080p",
        "aspect_ratio": "9:16",
        "generate_audio": true
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt describing the video you want to generate |
| `auto_fix` | boolean | optional | Any | Whether to automatically attempt to fix prompts that fail content policy or other validation checks by rewriting them. |
| `duration` | string | optional | `4s`, `6s`, `8s` | The duration of the generated video. |
| `generate_audio` | boolean | optional | Any | Whether to generate audio for the video. |
| `resolution` | string | optional | `720p`, `1080p`, `4k` | The resolution of the generated video. |
| `aspect_ratio` | string | optional | `16:9`, `9:16` | Aspect ratio of the generated video |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `negative_prompt` | string | optional | Any | A negative prompt to guide the video generation. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/veo3.1/fast)
- [API Reference](https://app.runflow.io/models/google/veo3.1/fast?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Veo 3.1 Fast - Image to Video
<!-- https://docs.runflow.io/models/google/veo3.1/fast/image-to-video -->

Pricing: **$0.1/second**. Endpoint: `POST /v1/models/google/veo3.1/fast/image-to-video/runs`.


Generate videos from your image prompts using Veo 3.1 fast.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/veo3.1/fast/image-to-video/runs
- **Model ID**: google/veo3.1/fast/image-to-video
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.1/second
- **Note**: Without audio

# Veo 3.1 Fast - Image to Video API

**Endpoint:** `POST /v1/models/google/veo3.1/fast/image-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/veo3.1/fast/image-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "The woman walks slowly down the cathedral aisle, her footsteps echoing softly against the marble floor. Shafts of rainbow light from the rose window sweep across her path as clouds move outside. She pauses to look up at the vaulted ceiling, dust motes dancing in the colored beams. Ambient cathedral reverb, distant organ notes.",
            "image_url": "https://public.runflow.io/images/models/black-forest-labs/flux-2-max/example-output-0.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/veo3.1/fast/image-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "The woman walks slowly down the cathedral aisle, her footsteps echoing softly against the marble floor. Shafts of rainbow light from the rose window sweep across her path as clouds move outside. She pauses to look up at the vaulted ceiling, dust motes dancing in the colored beams. Ambient cathedral reverb, distant organ notes.",
            "image_url": "https://public.runflow.io/images/models/black-forest-labs/flux-2-max/example-output-0.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/veo3.1/fast/image-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "The woman walks slowly down the cathedral aisle, her footsteps echoing softly against the marble floor. Shafts of rainbow light from the rose window sweep across her path as clouds move outside. She pauses to look up at the vaulted ceiling, dust motes dancing in the colored beams. Ambient cathedral reverb, distant organ notes.",
        "image_url": "https://public.runflow.io/images/models/black-forest-labs/flux-2-max/example-output-0.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt describing the video you want to generate |
| `auto_fix` | boolean | optional | Any | Whether to automatically attempt to fix prompts that fail content policy or other validation checks by rewriting them. |
| `duration` | string | optional | `4s`, `6s`, `8s` | The duration of the generated video. |
| `generate_audio` | boolean | optional | Any | Whether to generate audio for the video. |
| `resolution` | string | optional | `720p`, `1080p`, `4k` | The resolution of the generated video. |
| `aspect_ratio` | string | optional | `auto`, `16:9`, `9:16` | The aspect ratio of the generated video. Only 16:9 and 9:16 are supported. |
| `image_url` | image | required | Any | URL of the input image to animate. Should be 720p or higher resolution in 16:9 or 9:16 aspect ratio. If the image is not in 16:9 or 9:16 aspect ratio, it will be cropped to fit. |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `negative_prompt` | string | optional | Any | A negative prompt to guide the video generation. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/veo3.1/fast/image-to-video)
- [API Reference](https://app.runflow.io/models/google/veo3.1/fast/image-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Veo 3.1 - Image to Video
<!-- https://docs.runflow.io/models/google/veo3.1/image-to-video -->

Pricing: **$0.2/second**. Endpoint: `POST /v1/models/google/veo3.1/image-to-video/runs`.


Veo 3.1 is the latest state-of-the art video generation model from Google DeepMind

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/veo3.1/image-to-video/runs
- **Model ID**: google/veo3.1/image-to-video
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.2/second
- **Note**: Without audio

# Veo 3.1 - Image to Video API

**Endpoint:** `POST /v1/models/google/veo3.1/image-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/veo3.1/image-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Shafts of colored light from the stained glass windows slowly sweep across the marble floor as the sun moves, dust motes drift through the rainbow beams, the light shifts from warm amber to cool blue as it passes through different panels, echoing footsteps of an unseen visitor reverberate through the vast space, candle flames along the aisles flicker in a gentle draft",
            "duration": "8s",
            "image_url": "https://public.runflow.io/images/models/black-forest-labs/flux-2-max/example-output-0.webp",
            "resolution": "4k",
            "aspect_ratio": "16:9",
            "generate_audio": True
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/veo3.1/image-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Shafts of colored light from the stained glass windows slowly sweep across the marble floor as the sun moves, dust motes drift through the rainbow beams, the light shifts from warm amber to cool blue as it passes through different panels, echoing footsteps of an unseen visitor reverberate through the vast space, candle flames along the aisles flicker in a gentle draft",
            "duration": "8s",
            "image_url": "https://public.runflow.io/images/models/black-forest-labs/flux-2-max/example-output-0.webp",
            "resolution": "4k",
            "aspect_ratio": "16:9",
            "generate_audio": true
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/veo3.1/image-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Shafts of colored light from the stained glass windows slowly sweep across the marble floor as the sun moves, dust motes drift through the rainbow beams, the light shifts from warm amber to cool blue as it passes through different panels, echoing footsteps of an unseen visitor reverberate through the vast space, candle flames along the aisles flicker in a gentle draft",
        "duration": "8s",
        "image_url": "https://public.runflow.io/images/models/black-forest-labs/flux-2-max/example-output-0.webp",
        "resolution": "4k",
        "aspect_ratio": "16:9",
        "generate_audio": true
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text prompt describing the video you want to generate |
| `auto_fix` | boolean | optional | Any | Whether to automatically attempt to fix prompts that fail content policy or other validation checks by rewriting them. |
| `duration` | string | optional | `4s`, `6s`, `8s` | The duration of the generated video. |
| `generate_audio` | boolean | optional | Any | Whether to generate audio for the video. |
| `resolution` | string | optional | `720p`, `1080p`, `4k` | The resolution of the generated video. |
| `aspect_ratio` | string | optional | `auto`, `16:9`, `9:16` | The aspect ratio of the generated video. Only 16:9 and 9:16 are supported. |
| `image_url` | image | required | Any | URL of the input image to animate. Should be 720p or higher resolution in 16:9 or 9:16 aspect ratio. If the image is not in 16:9 or 9:16 aspect ratio, it will be cropped to fit. |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` | The safety tolerance level for content moderation. 1 is the most strict (blocks most content), 6 is the least strict. |
| `seed` | integer | optional | Any | The seed for the random number generator. |
| `negative_prompt` | string | optional | Any | A negative prompt to guide the video generation. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/veo3.1/image-to-video)
- [API Reference](https://app.runflow.io/models/google/veo3.1/image-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Veo 3.1 Lite
<!-- https://docs.runflow.io/models/google/veo3.1/lite -->

Pricing: **$0.03/second**. Endpoint: `POST /v1/models/google/veo3.1/lite/runs`.


Veo 3.1 Lite balances practical utility with professional capabilities.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/google/veo3.1/lite/runs
- **Model ID**: google/veo3.1/lite
- **Provider**: Google
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.03/second
- **Note**: 720p without audio (base)

# Veo 3.1 Lite API

**Endpoint:** `POST /v1/models/google/veo3.1/lite/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/google/veo3.1/lite/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Time-lapse of a single flower blooming in a sunlit garden, macro lens close-up, golden hour light, dewdrops visible on petals, smooth accelerated motion",
            "duration": "6s",
            "resolution": "720p"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/google/veo3.1/lite/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Time-lapse of a single flower blooming in a sunlit garden, macro lens close-up, golden hour light, dewdrops visible on petals, smooth accelerated motion",
            "duration": "6s",
            "resolution": "720p"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/google/veo3.1/lite/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Time-lapse of a single flower blooming in a sunlit garden, macro lens close-up, golden hour light, dewdrops visible on petals, smooth accelerated motion",
        "duration": "6s",
        "resolution": "720p"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any |  |
| `aspect_ratio` | string | optional | `16:9`, `9:16` |  |
| `duration` | string | optional | `4s`, `6s`, `8s` |  |
| `negative_prompt` | string | optional | Any |  |
| `resolution` | string | optional | `720p`, `1080p` |  |
| `generate_audio` | boolean | optional | Any |  |
| `seed` | integer | optional | Any |  |
| `auto_fix` | boolean | optional | Any |  |
| `safety_tolerance` | string | optional | `1`, `2`, `3`, `4`, `5`, `6` |  |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/google/veo3.1/lite)
- [API Reference](https://app.runflow.io/models/google/veo3.1/lite?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# HeyGen Video Agent V3
<!-- https://docs.runflow.io/models/heygen/v3/video-agent -->

Pricing: **$0.034/second**. Endpoint: `POST /v1/models/heygen/v3/video-agent/runs`.


Generate videos with a single prompt. Describe what you want in plain text, and the agent handles avatar selection, scripting, scene composition - all in one.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/heygen/v3/video-agent/runs
- **Model ID**: heygen/v3/video-agent
- **Provider**: HeyGen
- **License**: commercial
- **Last Updated**: 2026-04-21

## Pricing

- **Base price**: $0.034/second
- **Note**: Usage-based, per second of generated video

# HeyGen Video Agent V3 API

**Endpoint:** `POST /v1/models/heygen/v3/video-agent/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/heygen/v3/video-agent/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Create a 20-second professional product announcement video from a CTO introducing a new AI video platform to prospective customers. Modern office backdrop, warm professional lighting, confident tone, medium shot, minimal graphics. End with call-to-action."
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/heygen/v3/video-agent/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Create a 20-second professional product announcement video from a CTO introducing a new AI video platform to prospective customers. Modern office backdrop, warm professional lighting, confident tone, medium shot, minimal graphics. End with call-to-action."
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/heygen/v3/video-agent/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Create a 20-second professional product announcement video from a CTO introducing a new AI video platform to prospective customers. Modern office backdrop, warm professional lighting, confident tone, medium shot, minimal graphics. End with call-to-action."
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Natural language prompt describing the video to generate. The agent handles avatar selection, script, and production automatically. |
| `orientation` | string | optional | `landscape`, `portrait` | Video orientation. Auto-detected from the prompt if omitted. |
| `avatar` | string | optional | Any | Avatar to use in the video. Set to 'auto' to let the agent auto-select based on the prompt. |
| `file_urls` | file_list | optional | Any | URLs of files to include as assets in the video (images, videos, audio, PDFs). Maximum 20 files. |
| `incognito_mode` | boolean | optional | Any | When enabled, disables the agent's memory functions. |
| `style_id` | string | optional | Any | Style template ID from the /v3/video-agent/styles endpoint. |
| `voice` | string | optional | Any | Voice for narration. Set to 'auto' to let the agent auto-select. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array. |
| `seed` | json | Seed used for generation, or null. |
| `timing` | json | Provider timing info, or null. |
| `nsfw_detected` | json | NSFW flag, or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/heygen/v3/video-agent)
- [API Reference](https://app.runflow.io/models/heygen/v3/video-agent?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Ideogram v3
<!-- https://docs.runflow.io/models/ideogram/v3 -->

Pricing: **$0.06/image**. Endpoint: `POST /v1/models/ideogram/v3/runs`.


Generate high-quality images, posters, and logos with Ideogram V3. Features exceptional typography handling and realistic outputs optimized for commercial and creative use.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/ideogram/v3/runs
- **Model ID**: ideogram/v3
- **Provider**: Ideogram
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.06/image
- **Note**: Balanced (default)

# Ideogram v3 API

**Endpoint:** `POST /v1/models/ideogram/v3/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/ideogram/v3/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Product packaging design for an artisan coffee bag, front label featuring the brand name 'ALTITUDE COFFEE CO.' in bold vintage slab-serif at the top, a detailed woodcut-style illustration of a mountain coffee plantation in the center, origin text 'SINGLE ORIGIN - COLOMBIAN SUPREMO' in smaller caps below the illustration, tasting notes 'NOTES: DARK CHOCOLATE, CARAMEL, TOASTED WALNUT' in elegant thin serif at the bottom, roast level indicator showing 'MEDIUM-DARK ROAST', net weight '340g / 12oz' in the corner, kraft paper texture background with deep burgundy and gold ink, premium specialty coffee aesthetic",
            "image_size": "portrait_4_3",
            "expand_prompt": False,
            "negative_prompt": "blurry text, misspelled, low quality, generic",
            "rendering_speed": "QUALITY"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/ideogram/v3/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Product packaging design for an artisan coffee bag, front label featuring the brand name 'ALTITUDE COFFEE CO.' in bold vintage slab-serif at the top, a detailed woodcut-style illustration of a mountain coffee plantation in the center, origin text 'SINGLE ORIGIN - COLOMBIAN SUPREMO' in smaller caps below the illustration, tasting notes 'NOTES: DARK CHOCOLATE, CARAMEL, TOASTED WALNUT' in elegant thin serif at the bottom, roast level indicator showing 'MEDIUM-DARK ROAST', net weight '340g / 12oz' in the corner, kraft paper texture background with deep burgundy and gold ink, premium specialty coffee aesthetic",
            "image_size": "portrait_4_3",
            "expand_prompt": false,
            "negative_prompt": "blurry text, misspelled, low quality, generic",
            "rendering_speed": "QUALITY"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/ideogram/v3/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Product packaging design for an artisan coffee bag, front label featuring the brand name 'ALTITUDE COFFEE CO.' in bold vintage slab-serif at the top, a detailed woodcut-style illustration of a mountain coffee plantation in the center, origin text 'SINGLE ORIGIN - COLOMBIAN SUPREMO' in smaller caps below the illustration, tasting notes 'NOTES: DARK CHOCOLATE, CARAMEL, TOASTED WALNUT' in elegant thin serif at the bottom, roast level indicator showing 'MEDIUM-DARK ROAST', net weight '340g / 12oz' in the corner, kraft paper texture background with deep burgundy and gold ink, premium specialty coffee aesthetic",
        "image_size": "portrait_4_3",
        "expand_prompt": false,
        "negative_prompt": "blurry text, misspelled, low quality, generic",
        "rendering_speed": "QUALITY"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any |  |
| `num_images` | integer | optional | Any | Number of images to generate. |
| `image_size` | string | optional | Any | The resolution of the generated image |
| `style` | string | optional | Any | The style type to generate with. Cannot be used with style_codes. |
| `style_preset` | string | optional | Any | Style preset for generation. The chosen style preset will guide the generation. |
| `expand_prompt` | boolean | optional | Any | Determine if MagicPrompt should be used in generating the request or not. |
| `rendering_speed` | string | optional | `TURBO`, `BALANCED`, `QUALITY` | The rendering speed to use. |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `color_palette` | json | optional | Any | A color palette for generation, must EITHER be specified via one of the presets (name) or explicitly via hexadecimal representations of the color with optional weights (members) |
| `style_codes` | json | optional | Any | A list of 8 character hexadecimal codes representing the style of the image. Cannot be used in conjunction with style_reference_images or style |
| `seed` | integer | optional | Any | Seed for the random number generator |
| `image_urls` | image_list | optional | Any | A set of images to use as style references (maximum total size 10MB across all style references). The images should be in JPEG, PNG or WebP format |
| `negative_prompt` | string | optional | Any | Description of what to exclude from an image. Descriptions in the prompt take precedence to descriptions in the negative prompt. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `seed` | json | Seed used for the random number generator |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/ideogram/v3)
- [API Reference](https://app.runflow.io/models/ideogram/v3?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Models
<!-- https://docs.runflow.io/models -->

50 active models across 6 categories. Each model is one HTTP endpoint: `POST /v1/models/{provider}/{slug}/runs`. Auth: `Authorization: Bearer $RUNFLOW_API_KEY`.

## Image to image

| Model | Provider | Pricing |
|---|---|---|
| [Qwen Image Edit 2511](/models/alibaba/qwen-image-edit-2511) | Alibaba | `$0.03/megapixel` |
| [Wan 2.7 Pro Edit](/models/alibaba/wan/v2.7/pro/edit) | Alibaba | `$0.075/image` |
| [FLUX.2 [klein] 9B - Edit](/models/black-forest-labs/flux-2-klein-9b/edit) | Black Forest Labs | `$0.011/megapixel` |
| [FLUX Kontext](/models/black-forest-labs/flux-pro/kontext) | Black Forest Labs | `$0.04/image` |
| [Bria Background Remove](/models/bria/background/remove) | Bria AI | `$0.018/request` |
| [Nano Banana 2](/models/google/nano-banana-2) | Google | `$0.08/image` |
| [Nano Banana 2 - Edit](/models/google/nano-banana-2/edit) | Google | `$0.08/image` |
| [Nano Banana Pro](/models/google/nano-banana-pro) | Google | `$0.15/image` |
| [Nano Banana Pro - Edit](/models/google/nano-banana-pro/edit) | Google | `$0.15/image` |
| [SAM 3](/models/meta/sam-3/image) | Meta | `$0.005/image` |
| [GPT Image 1.5](/models/openai/gpt-image-1.5) | OpenAI | `$0.133/image` |
| [GPT Image 2 Edit](/models/openai/gpt-image-2/edit) | OpenAI | `$0.133/image` |
| [Reve Edit](/models/reve/edit) | Reve | `$0.04/image` |
| [Background Color](/models/runflow/background-color) | Runflow | `$0.12/request` |
| [Background Removal](/models/runflow/background-removal) | Runflow | `$0.045/request` |
| [Background Replace](/models/runflow/background-replace) | Runflow | `$0.35/request` |
| [Eye Color](/models/runflow/eye-color) | Runflow | `$0.29/request` |
| [Model Removal](/models/runflow/model-removal) | Runflow | `$0.27/request` |
| [Object Removal](/models/runflow/object-removal) | Runflow | `$0.48/request` |
| [Outpaint (Expand)](/models/runflow/outpaint) | Runflow | `$0.55/request` |
| [Outpaint (Aspect Ratio)](/models/runflow/outpaint/aspect-ratio) | Runflow | `$0.55/request` |
| [Product Isolation](/models/runflow/product-isolation) | Runflow | `$0.27/request` |
| [Reference Inpaint](/models/runflow/reference-inpaint) | Runflow | `$0.55/request` |
| [Skin Fix](/models/runflow/skin-fix) | Runflow | `$0.12/request` |
| [Smart Resize](/models/runflow/smart-resize) | Runflow | `$0.55/request` |
| [Tag Removal](/models/runflow/tag-removal) | Runflow | `$0.14/request` |
| [Topaz Upscale - Image](/models/topaz/upscale/image) | Topaz Labs | `$0.08/image` |

## Text to video

| Model | Provider | Pricing |
|---|---|---|
| [Happy Horse Text-to-Video](/models/alibaba/happy-horse/text-to-video) | Alibaba | `$0.14/second` |
| [Wan 2.7 Text to Video](/models/alibaba/wan/v2.7/text-to-video) | Alibaba | `$0.1/second` |
| [Seedance 2.0 Fast Text to Video](/models/bytedance/seedance/2.0/fast/text-to-video) | ByteDance | `$0.2419/second` |
| [Seedance 2.0 Text to Video](/models/bytedance/seedance/2.0/text-to-video) | ByteDance | `$0.3034/second` |
| [Veo 3.1](/models/google/veo3.1) | Google | `$0.2/second` |
| [Veo 3.1 Fast](/models/google/veo3.1/fast) | Google | `$0.1/second` |
| [Veo 3.1 Lite](/models/google/veo3.1/lite) | Google | `$0.03/second` |
| [HeyGen Video Agent V3](/models/heygen/v3/video-agent) | HeyGen | `$0.034/second` |
| [Kling v3 Pro - Text to Video](/models/kuaishou/kling-video/v3/pro/text-to-video) | Kuaishou | `$0.112/second` |

## Image to video

| Model | Provider | Pricing |
|---|---|---|
| [Happy Horse Image-to-Video](/models/alibaba/happy-horse/image-to-video) | Alibaba | `$0.14/second` |
| [Happy Horse Reference-to-Video](/models/alibaba/happy-horse/reference-to-video) | Alibaba | `$0.14/second` |
| [Wan 2.7 - Image to Video](/models/alibaba/wan/v2.7/image-to-video) | Alibaba | `$0.1/second` |
| [Seedance 2.0 Image to Video](/models/bytedance/seedance/2.0/image-to-video) | ByteDance | `$0.3024/second` |
| [Veo 3.1 Fast - Image to Video](/models/google/veo3.1/fast/image-to-video) | Google | `$0.1/second` |
| [Veo 3.1 - Image to Video](/models/google/veo3.1/image-to-video) | Google | `$0.2/second` |
| [Kling v3 Pro - Image to Video](/models/kuaishou/kling-video/v3/pro/image-to-video) | Kuaishou | `$0.112/second` |

## Text to image

| Model | Provider | Pricing |
|---|---|---|
| [FLUX.2 [klein] 4B](/models/black-forest-labs/flux-2-klein-4b) | Black Forest Labs | `$0.005/megapixel` |
| [FLUX.2 [klein] 9B](/models/black-forest-labs/flux-2-klein-9b) | Black Forest Labs | `$0.006/megapixel` |
| [Ideogram v3](/models/ideogram/v3) | Ideogram | `$0.06/image` |
| [GPT Image 2](/models/openai/gpt-image-2) | OpenAI | `$0.133/image` |

## Text to audio

| Model | Provider | Pricing |
|---|---|---|
| [ElevenLabs TTS v3](/models/elevenlabs/tts/eleven-v3) | ElevenLabs | `$100/1m-tokens` |
| [Gemini TTS](/models/google/gemini-tts) | Google | `$10/1m-tokens` |

## Video to video

| Model | Provider | Pricing |
|---|---|---|
| [Happy Horse Video Edit](/models/alibaba/happy-horse/video-edit) | Alibaba | `$0.28/second` |

---

# Kling v3 Pro - Image to Video
<!-- https://docs.runflow.io/models/kuaishou/kling-video/v3/pro/image-to-video -->

Pricing: **$0.112/second**. Endpoint: `POST /v1/models/kuaishou/kling-video/v3/pro/image-to-video/runs`.


Kling 3.0 Pro: Top-tier image-to-video with cinematic visuals, fluid motion, and native audio generation, with custom element support.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/image-to-video/runs
- **Model ID**: kuaishou/kling-video/v3/pro/image-to-video
- **Provider**: Kuaishou
- **License**: commercial
- **Last Updated**: 2026-04-05

## Pricing

- **Base price**: $0.112/second
- **Note**: Without audio

# Kling v3 Pro - Image to Video API

**Endpoint:** `POST /v1/models/kuaishou/kling-video/v3/pro/image-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/image-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Gentle head turn with a warm smile, hair blowing slightly in a soft breeze, cinematic portrait",
            "start_image_url": "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/image-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Gentle head turn with a warm smile, hair blowing slightly in a soft breeze, cinematic portrait",
            "start_image_url": "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/image-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Gentle head turn with a warm smile, hair blowing slightly in a soft breeze, cinematic portrait",
        "start_image_url": "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | optional | Any | Text prompt for video generation. Either prompt or multi_prompt must be provided, but not both. |
| `elements` | json | optional | Any | Elements (characters/objects) to include in the video. Each example can either be an image set (frontal + reference images) or a video. Reference in prompt as @Element1, @Element2, etc. |
| `multi_prompt` | json | optional | See nested fields below | List of prompts for multi-shot video generation. If provided, divides the video into multiple shots. |
| `generate_audio` | boolean | optional | Any | Whether to generate native audio for the video. Supports Chinese and English voice output. Other languages are automatically translated to English. For English speech, use lowercase letters; for acronyms or proper nouns, use uppercase. |
| `duration` | string | optional | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | The duration of the generated video in seconds |
| `shot_type` | string | optional | Any | The type of multi-shot video generation. Required when multi_prompt is provided. |
| `start_image_url` | image | required | Any | URL of the image to be used for the video |
| `end_image_url` | image | optional | Any | URL of the image to be used for the end of the video |
| `negative_prompt` | string | optional | Any |  |
| `cfg_scale` | float | optional | Any | The CFG (Classifier Free Guidance) scale is a measure of how close you want             the model to stick to your prompt. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/kuaishou/kling-video/v3/pro/image-to-video)
- [API Reference](https://app.runflow.io/models/kuaishou/kling-video/v3/pro/image-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Kling v3 Pro - Text to Video
<!-- https://docs.runflow.io/models/kuaishou/kling-video/v3/pro/text-to-video -->

Pricing: **$0.112/second**. Endpoint: `POST /v1/models/kuaishou/kling-video/v3/pro/text-to-video/runs`.


Kling 3.0 Pro: Top-tier text-to-video with cinematic visuals, fluid motion, and native audio generation, with multi-shot support.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/text-to-video/runs
- **Model ID**: kuaishou/kling-video/v3/pro/text-to-video
- **Provider**: Kuaishou
- **License**: commercial
- **Last Updated**: 2026-04-06

## Pricing

- **Base price**: $0.112/second
- **Note**: Without audio

# Kling v3 Pro - Text to Video API

**Endpoint:** `POST /v1/models/kuaishou/kling-video/v3/pro/text-to-video/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/text-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Time-lapse of a flower blooming in a sunlit garden, macro lens, smooth motion, warm tones"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/text-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Time-lapse of a flower blooming in a sunlit garden, macro lens, smooth motion, warm tones"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/kuaishou/kling-video/v3/pro/text-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Time-lapse of a flower blooming in a sunlit garden, macro lens, smooth motion, warm tones"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | optional | Any | Text prompt for video generation. Either prompt or multi_prompt must be provided, but not both. |
| `aspect_ratio` | string | optional | `16:9`, `9:16`, `1:1` | The aspect ratio of the generated video frame |
| `generate_audio` | boolean | optional | Any | Whether to generate native audio for the video. Supports Chinese and English voice output. Other languages are automatically translated to English. For English speech, use lowercase letters; for acronyms or proper nouns, use uppercase. |
| `multi_prompt` | json | optional | See nested fields below | List of prompts for multi-shot video generation. If provided, overrides the single prompt and divides the video into multiple shots with specified prompts and durations. |
| `duration` | string | optional | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | The duration of the generated video in seconds |
| `shot_type` | string | optional | `customize`, `intelligent` | The type of multi-shot video generation |
| `negative_prompt` | string | optional | Any |  |
| `cfg_scale` | float | optional | Any | The CFG (Classifier Free Guidance) scale is a measure of how close you want             the model to stick to your prompt. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/kuaishou/kling-video/v3/pro/text-to-video)
- [API Reference](https://app.runflow.io/models/kuaishou/kling-video/v3/pro/text-to-video?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# SAM 3
<!-- https://docs.runflow.io/models/meta/sam-3/image -->

Pricing: **$0.005/image**. Endpoint: `POST /v1/models/meta/sam-3/image/runs`.


SAM 3 is a unified foundation model for promptable segmentation in images and videos.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/meta/sam-3/image/runs
- **Model ID**: meta/sam-3/image
- **Provider**: Meta
- **License**: commercial
- **Last Updated**: 2026-04-05

## Pricing

- **Base price**: $0.005/image
- **Note**: Usage-based, per image

# SAM 3 API

**Endpoint:** `POST /v1/models/meta/sam-3/image/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/meta/sam-3/image/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "keyboard",
            "image_url": "https://v3b.fal.media/files/b/0a92a995/fV5oYdcCV3NAmgWJISpIP_tmpdddcks4v.png",
            "apply_mask": False,
            "return_multiple_masks": True
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/meta/sam-3/image/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "keyboard",
            "image_url": "https://v3b.fal.media/files/b/0a92a995/fV5oYdcCV3NAmgWJISpIP_tmpdddcks4v.png",
            "apply_mask": false,
            "return_multiple_masks": true
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/meta/sam-3/image/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "keyboard",
        "image_url": "https://v3b.fal.media/files/b/0a92a995/fV5oYdcCV3NAmgWJISpIP_tmpdddcks4v.png",
        "apply_mask": false,
        "return_multiple_masks": true
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | optional | Any | Text prompt for segmentation |
| `include_boxes` | boolean | optional | Any | Whether to include bounding boxes for each mask (when available). |
| `include_scores` | boolean | optional | Any | Whether to include mask confidence scores. |
| `return_multiple_masks` | boolean | optional | Any | If True, upload and return multiple generated masks as defined by `max_masks`. |
| `image_url` | image | required | Any | URL of the image to be segmented |
| `sync_mode` | boolean | optional | Any | If True, the media will be returned as a data URI. |
| `point_prompts` | json | optional | Any | List of point prompts |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | The format of the generated image. |
| `max_masks` | integer | optional | Any | Maximum number of masks to return when `return_multiple_masks` is enabled. |
| `box_prompts` | json | optional | Any | Box prompt coordinates (x_min, y_min, x_max, y_max). Multiple boxes supported - use object_id to group boxes for the same object or leave empty for separate objects. |
| `apply_mask` | boolean | optional | Any | Apply the mask on the image. |
| `text_prompt` | string | optional | Any | [DEPRECATED] Use 'prompt' instead. Kept for backward compatibility. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `model_data` | json | Model-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/meta/sam-3/image)
- [API Reference](https://app.runflow.io/models/meta/sam-3/image?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# GPT Image 1.5
<!-- https://docs.runflow.io/models/openai/gpt-image-1.5 -->

Pricing: **$0.133/image**. Endpoint: `POST /v1/models/openai/gpt-image-1.5/runs`.


GPT Image 1.5 generates high-fidelity images with strong prompt adherence, preserving composition, lighting, and fine-grained detail.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/openai/gpt-image-1.5/runs
- **Model ID**: openai/gpt-image-1.5
- **Provider**: OpenAI
- **License**: commercial
- **Last Updated**: 2026-04-13

## Pricing

- **Base price**: $0.133/image
- **Note**: High quality (default)

# GPT Image 1.5 API

**Endpoint:** `POST /v1/models/openai/gpt-image-1.5/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/openai/gpt-image-1.5/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "An underwater coral reef tea house at the bottom of a crystal-clear tropical ocean. Bamboo replaced by swaying kelp and sea fans, fish swim where birds would fly, jellyfish provide the lantern light, a sea turtle approaches the entrance. Warm bioluminescent glow, caustic light patterns on the sandy floor."
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/openai/gpt-image-1.5/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "An underwater coral reef tea house at the bottom of a crystal-clear tropical ocean. Bamboo replaced by swaying kelp and sea fans, fish swim where birds would fly, jellyfish provide the lantern light, a sea turtle approaches the entrance. Warm bioluminescent glow, caustic light patterns on the sandy floor."
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/openai/gpt-image-1.5/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "An underwater coral reef tea house at the bottom of a crystal-clear tropical ocean. Bamboo replaced by swaying kelp and sea fans, fish swim where birds would fly, jellyfish provide the lantern light, a sea turtle approaches the entrance. Warm bioluminescent glow, caustic light patterns on the sandy floor."
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | Text prompt describing the image to generate. 2–32,000 characters. |
| `quality` | string | optional | `low`, `medium`, `high` | Output quality tier. Options: "low", "medium", "high". Default: "high". Affects price. |
| `image_size` | string | optional | `1024x1024`, `1536x1024`, `1024x1536` | Image dimensions. Options: "1024x1024", "1536x1024", "1024x1536", "auto". Default: "1024x1024". Use "auto" to let the model pick the best size. |
| `background` | string | optional | `auto`, `transparent`, `opaque` | Background type. Options: "auto", "transparent", "opaque". Default: "auto". |
| `num_images` | integer | optional | Any | Number of images to generate. Range: 1–4. Default: 1. |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | Output format. Options: "jpeg", "png", "webp". Default: "png". |
| `sync_mode` | boolean | optional | Any | Return media as data URI without storing in history. Default: false. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/openai/gpt-image-1.5)
- [API Reference](https://app.runflow.io/models/openai/gpt-image-1.5?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# GPT Image 2
<!-- https://docs.runflow.io/models/openai/gpt-image-2 -->

Pricing: **$0.133/image**. Endpoint: `POST /v1/models/openai/gpt-image-2/runs`.


GPT Image 2.0, OpenAI's latest image model, is capable of creating extremely detailed images with fine typography.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/openai/gpt-image-2/runs
- **Model ID**: openai/gpt-image-2
- **Provider**: OpenAI
- **License**: commercial
- **Last Updated**: 2026-04-21

## Pricing

- **Base price**: $0.133/image
- **Note**: High quality (default)

# GPT Image 2 API

**Endpoint:** `POST /v1/models/openai/gpt-image-2/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/openai/gpt-image-2/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "A hand-drawn storefront sign reading 'CIRCUIT & GRAIN - specialty coffee' on polished brass, warm morning sunlight, shallow depth of field, the shop window visible behind with pastry trays, cinematic photograph"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/openai/gpt-image-2/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "A hand-drawn storefront sign reading 'CIRCUIT & GRAIN - specialty coffee' on polished brass, warm morning sunlight, shallow depth of field, the shop window visible behind with pastry trays, cinematic photograph"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/openai/gpt-image-2/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "A hand-drawn storefront sign reading 'CIRCUIT & GRAIN - specialty coffee' on polished brass, warm morning sunlight, shallow depth of field, the shop window visible behind with pastry trays, cinematic photograph"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The prompt for image generation |
| `num_images` | integer | optional | Any | Number of images to generate |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | Output format for the images |
| `image_size` | string | optional | `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9` | The size of the generated image. Supports preset names or explicit {width, height}. Both dimensions must be multiples of 16, max edge 3840px, aspect ratio &lt;= 3:1, total pixels between 655,360 and 8,294,400. |
| `quality` | string | optional | `low`, `medium`, `high` | Quality for the generated image |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array. |
| `seed` | json | Seed used for generation, or null. |
| `timing` | json | Provider timing info, or null. |
| `nsfw_detected` | json | NSFW flag, or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/openai/gpt-image-2)
- [API Reference](https://app.runflow.io/models/openai/gpt-image-2?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# GPT Image 2 Edit
<!-- https://docs.runflow.io/models/openai/gpt-image-2/edit -->

Pricing: **$0.133/image**. Endpoint: `POST /v1/models/openai/gpt-image-2/edit/runs`.


GPT Image 2.0, OpenAI's latest image model, is capable of making fine-grained, detailed edits to images.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/openai/gpt-image-2/edit/runs
- **Model ID**: openai/gpt-image-2/edit
- **Provider**: OpenAI
- **License**: commercial
- **Last Updated**: 2026-04-21

## Pricing

- **Base price**: $0.133/image
- **Note**: High quality (default)

# GPT Image 2 Edit API

**Endpoint:** `POST /v1/models/openai/gpt-image-2/edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/openai/gpt-image-2/edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Replace the background with a sunlit seaside cafe at golden hour, keep the subject's pose, outfit, and lighting on the face intact",
            "image_urls": [
                "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/openai/gpt-image-2/edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Replace the background with a sunlit seaside cafe at golden hour, keep the subject's pose, outfit, and lighting on the face intact",
            "image_urls": [
                "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
            ]
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
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" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Replace the background with a sunlit seaside cafe at golden hour, keep the subject's pose, outfit, and lighting on the face intact",
        "image_urls": [
            "https://public.runflow.io/images/models/_base/portrait-woman-studio.png"
        ]
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The prompt for image generation |
| `image_urls` | image_list | required | Any | The URLs of the images to use as a reference for the generation. |
| `num_images` | integer | optional | Any | Number of images to generate |
| `output_format` | string | optional | `jpeg`, `png`, `webp` | Output format for the images |
| `image_size` | string | optional | `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9`, `auto` | The size of the generated image. Use 'auto' to infer from input images. |
| `mask_url` | image | optional | Any | The URL of the mask image to use for the generation. This indicates what part of the image to edit. |
| `quality` | string | optional | `low`, `medium`, `high` | Quality for the generated image |
| `sync_mode` | boolean | optional | Any | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array. |
| `seed` | json | Seed used for generation, or null. |
| `timing` | json | Provider timing info, or null. |
| `nsfw_detected` | json | NSFW flag, or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/openai/gpt-image-2/edit)
- [API Reference](https://app.runflow.io/models/openai/gpt-image-2/edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Reve Edit
<!-- https://docs.runflow.io/models/reve/edit -->

Pricing: **$0.04/image**. Endpoint: `POST /v1/models/reve/edit/runs`.


Reve's edit model lets you upload an existing image and then transform it via a text prompt.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/reve/edit/runs
- **Model ID**: reve/edit
- **Provider**: Reve
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.04/image
- **Note**: Per image

# Reve Edit API

**Endpoint:** `POST /v1/models/reve/edit/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/reve/edit/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Move this entire scene to a rooftop terrace in Tokyo at sunset: the desk is now outdoors on a wooden deck, Tokyo Tower and neon skyscrapers visible in the background, cherry blossom petals floating in the air, warm golden hour light, string lights overhead",
            "image_url": "https://public.runflow.io/images/models/_shared/base-engineer.png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/reve/edit/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Move this entire scene to a rooftop terrace in Tokyo at sunset: the desk is now outdoors on a wooden deck, Tokyo Tower and neon skyscrapers visible in the background, cherry blossom petals floating in the air, warm golden hour light, string lights overhead",
            "image_url": "https://public.runflow.io/images/models/_shared/base-engineer.png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/reve/edit/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Move this entire scene to a rooftop terrace in Tokyo at sunset: the desk is now outdoors on a wooden deck, Tokyo Tower and neon skyscrapers visible in the background, cherry blossom petals floating in the air, warm golden hour light, string lights overhead",
        "image_url": "https://public.runflow.io/images/models/_shared/base-engineer.png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | required | Any | The text description of how to edit the provided image. |
| `image_url` | image | required | Any | URL of the reference image to edit. Must be publicly accessible or base64 data URI. Supports PNG, JPEG, WebP, AVIF, and HEIF formats. |
| `num_images` | integer | optional | Any | Number of images to generate |
| `output_format` | string | optional | `png`, `jpeg`, `webp` | Output format for the generated image. |
| `sync_mode` | boolean | optional | Any | If True, the media will be returned as a data URI and the output data won't be available in the request history. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/reve/edit)
- [API Reference](https://app.runflow.io/models/reve/edit?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Background Color
<!-- https://docs.runflow.io/models/runflow/background-color -->

Pricing: **$0.12/request**. Endpoint: `POST /v1/models/runflow/background-color/runs`.


Replace the background of a portrait or product shot with a flat color. Pick any RGB value; shading_percent baked at 30% for soft falloff.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/background-color/runs
- **Model ID**: runflow/background-color
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.12/request
- **Note**: Per image - background color replacement

# Background Color API

**Endpoint:** `POST /v1/models/runflow/background-color/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/background-color/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "color_red": 245,
            "image_url": "https://public.runflow.io/images/models/runflow/background-color/examples/1/before.webp",
            "color_blue": 200,
            "color_green": 220
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/background-color/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "color_red": 245,
            "image_url": "https://public.runflow.io/images/models/runflow/background-color/examples/1/before.webp",
            "color_blue": 200,
            "color_green": 220
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/background-color/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "color_red": 245,
        "image_url": "https://public.runflow.io/images/models/runflow/background-color/examples/1/before.webp",
        "color_blue": 200,
        "color_green": 220
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. HTTPS required. |
| `color_red` | integer | required | Any | Red channel 0–255. |
| `color_green` | integer | required | Any | Green channel 0–255. |
| `color_blue` | integer | required | Any | Blue channel 0–255. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/background-color)
- [API Reference](https://app.runflow.io/models/runflow/background-color?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Background Removal
<!-- https://docs.runflow.io/models/runflow/background-removal -->

Pricing: **$0.045/request**. Endpoint: `POST /v1/models/runflow/background-removal/runs`.


Remove the background from an image and return a clean cutout with a transparent alpha channel. Built for e-commerce product shots, portraits, and batch cleanup pipelines.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/background-removal/runs
- **Model ID**: runflow/background-removal
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-04-21

## Pricing

- **Base price**: $0.045/request
- **Note**: Per image - background removal

# Background Removal API

**Endpoint:** `POST /v1/models/runflow/background-removal/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/background-removal/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "config": {},
            "image_url": "https://public.runflow.io/images/models/runflow/background-removal/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/background-removal/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "config": {},
            "image_url": "https://public.runflow.io/images/models/runflow/background-removal/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/background-removal/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "config": {},
        "image_url": "https://public.runflow.io/images/models/runflow/background-removal/examples/1/before.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. |
| `config` | json | optional | See nested fields below | Optional per-image config (aspect_ratio). |

### `config` - nested fields

Optional per-image config (aspect_ratio).

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `aspect_ratio` | string | optional | Suggested: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `2:3` |  |

```json
{}
```

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `image_urls` | image_list | Processed image URLs. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/background-removal)
- [API Reference](https://app.runflow.io/models/runflow/background-removal?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Background Replace
<!-- https://docs.runflow.io/models/runflow/background-replace -->

Pricing: **$0.35/request**. Endpoint: `POST /v1/models/runflow/background-replace/runs`.


Swap the background of any product photo for a new scene defined by a reference image and a short prompt. The model preserves the foreground subject while matching camera angle and lighting to the new background.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/background-replace/runs
- **Model ID**: runflow/background-replace
- **Provider**: Runflow
- **Last Updated**: 2026-05-06

## Pricing

- **Base price**: $0.35/request
- **Note**: Per image - background replace

# Background Replace API

**Endpoint:** `POST /v1/models/runflow/background-replace/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/background-replace/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Replace the white area on Image 1 with Image 2 as the background. Keep the perfume bottle perfectly intact and match the soft window light from Image 2.",
            "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
            "file_image": "image.webp",
            "file_reference": "reference.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/background-replace/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Replace the white area on Image 1 with Image 2 as the background. Keep the perfume bottle perfectly intact and match the soft window light from Image 2.",
            "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
            "file_image": "image.webp",
            "file_reference": "reference.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Replace the white area on Image 1 with Image 2 as the background. Keep the perfume bottle perfectly intact and match the soft window light from Image 2.",
        "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
        "file_image": "image.webp",
        "file_reference": "reference.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `zip_url` | file | required | Any | URL of a zip archive containing the foreground photo and the background reference image. Set file_image and file_reference to the filenames inside the zip. |
| `file_image` | string | required | Any | Filename of the foreground/product photo inside the zip (e.g. `image.png`). The model keeps this subject and replaces only the background. |
| `file_reference` | string | required | Any | Filename of the background reference image inside the zip (e.g. `reference.png`). The model uses it as the new scene behind the foreground. |
| `prompt` | string | optional | Any | Optional override for the scene description. Leave empty to use the default: replace the white area on Image 1 with Image 2 as the background, matching camera angle and lighting. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `image_urls` | image_list | Background-replaced image URLs. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/background-replace)
- [API Reference](https://app.runflow.io/models/runflow/background-replace?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Eye Color
<!-- https://docs.runflow.io/models/runflow/eye-color -->

Pricing: **$0.29/request**. Endpoint: `POST /v1/models/runflow/eye-color/runs`.


Recolor the irises in a portrait. The customer describes the target eye color (e.g. "blue", "emerald green", "amber") - that drives the inpaint guidance. Optional RGB lets you tint the overlay precisely.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/eye-color/runs
- **Model ID**: runflow/eye-color
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-05-03

## Pricing

- **Base price**: $0.29/request
- **Note**: Per image - eye color change

# Eye Color API

**Endpoint:** `POST /v1/models/runflow/eye-color/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/eye-color/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "color_red": 50,
            "eye_color": "forest green",
            "image_url": "https://public.runflow.io/images/models/runflow/eye-color/examples/1/before.webp",
            "color_blue": 60,
            "color_green": 110
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/eye-color/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "color_red": 50,
            "eye_color": "forest green",
            "image_url": "https://public.runflow.io/images/models/runflow/eye-color/examples/1/before.webp",
            "color_blue": 60,
            "color_green": 110
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/eye-color/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "color_red": 50,
        "eye_color": "forest green",
        "image_url": "https://public.runflow.io/images/models/runflow/eye-color/examples/1/before.webp",
        "color_blue": 60,
        "color_green": 110
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. HTTPS required. |
| `eye_color` | string | required | Any | Target eye color, e.g. "blue", "emerald green", "amber", "deep brown". |
| `color_red` | integer | required | Any | Red channel 0–255. |
| `color_green` | integer | required | Any | Green channel 0–255. |
| `color_blue` | integer | required | Any | Blue channel 0–255. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/eye-color)
- [API Reference](https://app.runflow.io/models/runflow/eye-color?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Model Removal
<!-- https://docs.runflow.io/models/runflow/model-removal -->

Pricing: **$0.27/request**. Endpoint: `POST /v1/models/runflow/model-removal/runs`.


Remove the human model from a garment or apparel photo and recover a clean flat-lay or ghost-mannequin view. Designed for fashion catalogs and PDP hero shots.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/model-removal/runs
- **Model ID**: runflow/model-removal
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-04-21

## Pricing

- **Base price**: $0.27/request
- **Note**: Per image - model removal

# Model Removal API

**Endpoint:** `POST /v1/models/runflow/model-removal/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/model-removal/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "config": {},
            "image_url": "https://public.runflow.io/images/models/runflow/model-removal/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/model-removal/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "config": {},
            "image_url": "https://public.runflow.io/images/models/runflow/model-removal/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/model-removal/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "config": {},
        "image_url": "https://public.runflow.io/images/models/runflow/model-removal/examples/1/before.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. |
| `config` | json | optional | See nested fields below | Optional per-image config (aspect_ratio). |

### `config` - nested fields

Optional per-image config (aspect_ratio).

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `aspect_ratio` | string | optional | Suggested: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `2:3` |  |

```json
{}
```

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `image_urls` | image_list | Processed image URLs. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/model-removal)
- [API Reference](https://app.runflow.io/models/runflow/model-removal?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Object Removal
<!-- https://docs.runflow.io/models/runflow/object-removal -->

Pricing: **$0.48/request**. Endpoint: `POST /v1/models/runflow/object-removal/runs`.


Remove an unwanted object or region from a photo. Mark the area to remove with a black-and-white mask. The model rebuilds the background using surrounding context.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/object-removal/runs
- **Model ID**: runflow/object-removal
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-05-05

## Pricing

- **Base price**: $0.48/request
- **Note**: Per image: object removal

# Object Removal API

**Endpoint:** `POST /v1/models/runflow/object-removal/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/object-removal/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "zip_url": "https://public.runflow.io/images/models/runflow/object-removal/examples/1/inputs.zip",
            "file_mask": "mask.png",
            "file_input": "photo.png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/object-removal/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "zip_url": "https://public.runflow.io/images/models/runflow/object-removal/examples/1/inputs.zip",
            "file_mask": "mask.png",
            "file_input": "photo.png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/object-removal/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "zip_url": "https://public.runflow.io/images/models/runflow/object-removal/examples/1/inputs.zip",
        "file_mask": "mask.png",
        "file_input": "photo.png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `zip_url` | file | required | Any | URL of a zip archive containing the input photo and mask. Use file_input + file_mask to name the files inside. |
| `file_input` | string | required | Any | Filename inside `zip_url` (e.g. `photo.png` if the zip contains `photo.png`). Frontend should set this to match the inner filename when composing the zip. |
| `file_mask` | string | required | Any | Filename of the B&W mask inside the URL/zip (white = remove, black = keep). Same shape as `file_input` but for the mask file. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/object-removal)
- [API Reference](https://app.runflow.io/models/runflow/object-removal?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Outpaint (Expand)
<!-- https://docs.runflow.io/models/runflow/outpaint -->

Pricing: **$0.55/request**. Endpoint: `POST /v1/models/runflow/outpaint/runs`.


Expand the canvas of an image with AI-generated content that matches the existing scene. Specify percent expand on each side - required so the customer is intentional.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/outpaint/runs
- **Model ID**: runflow/outpaint
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.55/request
- **Note**: Per image - outpainting / canvas expand

# Outpaint (Expand) API

**Endpoint:** `POST /v1/models/runflow/outpaint/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/outpaint/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/outpaint/examples/1/before.webp",
            "expand_top": 10,
            "expand_left": 70,
            "expand_right": 0,
            "expand_bottom": 30
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/outpaint/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/outpaint/examples/1/before.webp",
            "expand_top": 10,
            "expand_left": 70,
            "expand_right": 0,
            "expand_bottom": 30
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/outpaint/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "image_url": "https://public.runflow.io/images/models/runflow/outpaint/examples/1/before.webp",
        "expand_top": 10,
        "expand_left": 70,
        "expand_right": 0,
        "expand_bottom": 30
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. HTTPS required. |
| `expand_top` | integer | required | Any | 0–80% expand on the top edge. |
| `expand_bottom` | integer | required | Any | 0–80% expand on the bottom edge. |
| `expand_left` | integer | required | Any | 0–80% expand on the left edge. |
| `expand_right` | integer | required | Any | 0–80% expand on the right edge. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/outpaint)
- [API Reference](https://app.runflow.io/models/runflow/outpaint?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Outpaint (Aspect Ratio)
<!-- https://docs.runflow.io/models/runflow/outpaint/aspect-ratio -->

Pricing: **$0.55/request**. Endpoint: `POST /v1/models/runflow/outpaint/aspect-ratio/runs`.


Expand the canvas of an image to a target aspect ratio (e.g. 16:9, 1:1, 9:16). The model decides where to add content - no need to specify per-side expand percentages.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs
- **Model ID**: runflow/outpaint/aspect-ratio
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-05-03

## Pricing

- **Base price**: $0.55/request
- **Note**: Per image - outpainting to target aspect ratio

# Outpaint (Aspect Ratio) API

**Endpoint:** `POST /v1/models/runflow/outpaint/aspect-ratio/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/outpaint/aspect-ratio/examples/2/before.png",
            "aspect_ratio": "9:16"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/outpaint/aspect-ratio/examples/2/before.png",
            "aspect_ratio": "9:16"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "image_url": "https://public.runflow.io/images/models/runflow/outpaint/aspect-ratio/examples/2/before.png",
        "aspect_ratio": "9:16"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the inputs to process - typically a `.zip` produced by the frontend. bg-brain downloads it to /tmp/inputs/ and unzips with filenames preserved. HTTPS required. |
| `justification` | string | optional | `center`, `manual`, `top-left`, `bottom-right`, `expand-all` | Where to anchor the source image inside the expanded aspect ratio. "center" pads all sides equally. "top-left" pins the top-left corner and pads bottom-right. "bottom-right" pins the bottom-right corner and pads top-left. "expand-all" pads all sides. "manual" uses the explicit top/bottom/left/right percentages on the workflow. |
| `aspect_ratio` | string | required | Any | Target output aspect ratio. Examples: "1:1" (square), "16:9" (widescreen), "9:16" (portrait), "4:3", "3:4", "21:9" (cinematic). |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/outpaint/aspect-ratio)
- [API Reference](https://app.runflow.io/models/runflow/outpaint/aspect-ratio?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Product Isolation
<!-- https://docs.runflow.io/models/runflow/product-isolation -->

Pricing: **$0.27/request**. Endpoint: `POST /v1/models/runflow/product-isolation/runs`.


Isolate the main product from a busy scene onto a clean background, using an optional text prompt to disambiguate the subject. Built for studio-grade product photography at scale.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/product-isolation/runs
- **Model ID**: runflow/product-isolation
- **Provider**: Runflow
- **Last Updated**: 2026-05-05

## Pricing

- **Base price**: $0.27/request
- **Note**: Per image - product isolation

# Product Isolation API

**Endpoint:** `POST /v1/models/runflow/product-isolation/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/product-isolation/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "the terracotta ribbed tank midi dress and black ankle boots",
            "image_url": "https://public.runflow.io/images/models/runflow/product-isolation/examples/1/before.webp",
            "resolution": "1K",
            "aspect_ratio": "1:1"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/product-isolation/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "the terracotta ribbed tank midi dress and black ankle boots",
            "image_url": "https://public.runflow.io/images/models/runflow/product-isolation/examples/1/before.webp",
            "resolution": "1K",
            "aspect_ratio": "1:1"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/product-isolation/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "the terracotta ribbed tank midi dress and black ankle boots",
        "image_url": "https://public.runflow.io/images/models/runflow/product-isolation/examples/1/before.webp",
        "resolution": "1K",
        "aspect_ratio": "1:1"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the source photo. HTTPS required. |
| `aspect_ratio` | string | required | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | Output aspect ratio. Examples: "1:1" (square), "16:9" (widescreen), "9:16" (portrait), "4:3", "3:4", "21:9". |
| `resolution` | string | required | `1K`, `2K`, `4K` | Output resolution tier. "1K" ≈ 1024px, "2K" ≈ 2048px, "4K" ≈ 4096px on the long side. |
| `prompt` | string | optional | Any | Optional text describing what to isolate. If omitted, the model decides automatically. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `image_urls` | image_list | Processed image URLs. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/product-isolation)
- [API Reference](https://app.runflow.io/models/runflow/product-isolation?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Reference Inpaint
<!-- https://docs.runflow.io/models/runflow/reference-inpaint -->

Pricing: **$0.55/request**. Endpoint: `POST /v1/models/runflow/reference-inpaint/runs`.


Inpaint a region of a target photo using a reference image as the visual guide. Provide the target, a black-and-white mask of the area to fill, and a reference image. The model paints the masked region with content matching the reference.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/reference-inpaint/runs
- **Model ID**: runflow/reference-inpaint
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-05-05

## Pricing

- **Base price**: $0.55/request
- **Note**: Per image: reference inpaint

# Reference Inpaint API

**Endpoint:** `POST /v1/models/runflow/reference-inpaint/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/reference-inpaint/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "zip_url": "https://public.runflow.io/images/models/runflow/reference-inpaint/examples/1/inputs.zip",
            "file_mask": "mask.png",
            "file_input": "photo.png",
            "file_reference": "reference.png"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/reference-inpaint/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "zip_url": "https://public.runflow.io/images/models/runflow/reference-inpaint/examples/1/inputs.zip",
            "file_mask": "mask.png",
            "file_input": "photo.png",
            "file_reference": "reference.png"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/reference-inpaint/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "zip_url": "https://public.runflow.io/images/models/runflow/reference-inpaint/examples/1/inputs.zip",
        "file_mask": "mask.png",
        "file_input": "photo.png",
        "file_reference": "reference.png"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `zip_url` | file | required | Any | URL of a zip archive containing the target image, mask, and reference image. Use file_input + file_mask + file_reference to name the files inside. |
| `file_input` | string | required | Any | Filename inside `zip_url` of the photo to edit (e.g. `photo.png`). |
| `file_mask` | string | required | Any | Filename inside `zip_url` of the black-and-white mask. White pixels mark the area to inpaint, black pixels mark what to keep. |
| `file_reference` | string | required | Any | Filename inside `zip_url` of the reference image whose visual content should fill the masked area. |
| `prompt` | string | optional | Any | Optional override for the scene description. Leave empty to use the default. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/reference-inpaint)
- [API Reference](https://app.runflow.io/models/runflow/reference-inpaint?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Skin Fix
<!-- https://docs.runflow.io/models/runflow/skin-fix -->

Pricing: **$0.12/request**. Endpoint: `POST /v1/models/runflow/skin-fix/runs`.


Cleanup pass for portrait photography. Smoothes skin texture, fixes blemishes, preserves natural detail.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/skin-fix/runs
- **Model ID**: runflow/skin-fix
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-04-28

## Pricing

- **Base price**: $0.12/request
- **Note**: Per image - skin retouch

# Skin Fix API

**Endpoint:** `POST /v1/models/runflow/skin-fix/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/skin-fix/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/skin-fix/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/skin-fix/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/skin-fix/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/skin-fix/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "image_url": "https://public.runflow.io/images/models/runflow/skin-fix/examples/1/before.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. HTTPS required. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/skin-fix)
- [API Reference](https://app.runflow.io/models/runflow/skin-fix?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Smart Resize
<!-- https://docs.runflow.io/models/runflow/smart-resize -->

Pricing: **$0.55/request**. Endpoint: `POST /v1/models/runflow/smart-resize/runs`.


Resize an image to a target aspect ratio + resolution (1K, 2K, 4K) without distortion or cropping. Uses generative reframing to recompose the subject into the new frame.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/smart-resize/runs
- **Model ID**: runflow/smart-resize
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-05-03

## Pricing

- **Base price**: $0.55/request
- **Note**: Per image - smart resize (aspect ratio + resolution)

# Smart Resize API

**Endpoint:** `POST /v1/models/runflow/smart-resize/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/smart-resize/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/smart-resize/examples/6/before.png",
            "resolution": "1K",
            "aspect_ratio": "4:3"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/smart-resize/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/smart-resize/examples/6/before.png",
            "resolution": "1K",
            "aspect_ratio": "4:3"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/smart-resize/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "image_url": "https://public.runflow.io/images/models/runflow/smart-resize/examples/6/before.png",
        "resolution": "1K",
        "aspect_ratio": "4:3"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the inputs to process - typically a `.zip` produced by the frontend. bg-brain downloads it to /tmp/inputs/ and unzips with filenames preserved. HTTPS required. |
| `aspect_ratio` | string | required | Any | Target output aspect ratio. Examples: "1:1" (square), "16:9" (widescreen), "9:16" (portrait), "4:3", "3:4", "21:9" (cinematic), "2:3", "3:2". |
| `resolution` | string | required | `1K`, `2K`, `4K` | Target output resolution tier. "1K" ≈ 1024px, "2K" ≈ 2048px, "4K" ≈ 4096px on the long side. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Array of result items, each with at minimum a `url` field. |
| `seed` | json | Random seed used (null if N/A). |
| `timing` | json | Provider timing breakdown (null if not surfaced). |
| `nsfw_detected` | json | Provider NSFW flag (null if not surfaced). |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/smart-resize)
- [API Reference](https://app.runflow.io/models/runflow/smart-resize?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Tag Removal
<!-- https://docs.runflow.io/models/runflow/tag-removal -->

Pricing: **$0.14/request**. Endpoint: `POST /v1/models/runflow/tag-removal/runs`.


Remove price tags, stickers, and labels from product images while preserving the underlying material and lighting. Ideal for re-listing inventory or cleaning up user-submitted photography.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/runflow/tag-removal/runs
- **Model ID**: runflow/tag-removal
- **Provider**: Runflow
- **License**: commercial
- **Last Updated**: 2026-04-21

## Pricing

- **Base price**: $0.14/request
- **Note**: Per image - tag removal

# Tag Removal API

**Endpoint:** `POST /v1/models/runflow/tag-removal/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/tag-removal/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "config": {},
            "image_url": "https://public.runflow.io/images/models/runflow/tag-removal/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/tag-removal/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "config": {},
            "image_url": "https://public.runflow.io/images/models/runflow/tag-removal/examples/1/before.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/runflow/tag-removal/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "config": {},
        "image_url": "https://public.runflow.io/images/models/runflow/tag-removal/examples/1/before.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `image_url` | image | required | Any | URL of the image to process. |
| `config` | json | optional | See nested fields below | Optional per-image config (aspect_ratio). |

### `config` - nested fields

Optional per-image config (aspect_ratio).

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `aspect_ratio` | string | optional | Suggested: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `2:3` |  |

```json
{}
```

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `image_urls` | image_list | Processed image URLs. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/runflow/tag-removal)
- [API Reference](https://app.runflow.io/models/runflow/tag-removal?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Topaz Upscale - Image
<!-- https://docs.runflow.io/models/topaz/upscale/image -->

Pricing: **$0.08/image**. Endpoint: `POST /v1/models/topaz/upscale/image/runs`.


Use the powerful and accurate topaz image enhancer to enhance your images.

## Overview

- **Endpoint**: https://api.runflow.io/v1/models/topaz/upscale/image/runs
- **Model ID**: topaz/upscale/image
- **Provider**: Topaz Labs
- **License**: commercial
- **Last Updated**: 2026-04-08

## Pricing

- **Base price**: $0.08/image
- **Note**: Up to 24MP

# Topaz Upscale - Image API

**Endpoint:** `POST /v1/models/topaz/upscale/image/runs`

## Run the model

### Python

```python
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/topaz/upscale/image/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "model": "Standard V2",
            "image_url": "https://public.runflow.io/images/models/photalabs/phota/example-output-0.webp",
            "autoprompt": True,
            "output_format": "png",
            "upscale_factor": 4,
            "face_enhancement": True,
            "subject_detection": "Foreground",
            "face_enhancement_strength": 0.8,
            "face_enhancement_creativity": 0.1
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript
const response = await fetch(
  "https://api.runflow.io/v1/models/topaz/upscale/image/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "model": "Standard V2",
            "image_url": "https://public.runflow.io/images/models/photalabs/phota/example-output-0.webp",
            "autoprompt": true,
            "output_format": "png",
            "upscale_factor": 4,
            "face_enhancement": true,
            "subject_detection": "Foreground",
            "face_enhancement_strength": 0.8,
            "face_enhancement_creativity": 0.1
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl -X POST https://api.runflow.io/v1/models/topaz/upscale/image/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "model": "Standard V2",
        "image_url": "https://public.runflow.io/images/models/photalabs/phota/example-output-0.webp",
        "autoprompt": true,
        "output_format": "png",
        "upscale_factor": 4,
        "face_enhancement": true,
        "subject_detection": "Foreground",
        "face_enhancement_strength": 0.8,
        "face_enhancement_creativity": 0.1
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | object | required | Model input parameters. See "Input schema" below. |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata` | object \| null | optional | Arbitrary key-value pairs attached to the run. |

## Input schema

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | optional | Any | Text prompt to guide generative upscaling (max 1024 chars). Applies to Redefine model only. |
| `face_enhancement_creativity` | float | optional | Any | Creativity level for face enhancement. 0.0 means no creativity, 1.0 means maximum creativity. Ignored if face enhancement is disabled. |
| `face_enhancement` | boolean | optional | Any | Whether to apply face enhancement to the image. Applies to standard enhance and Recovery V2 models. |
| `model` | string | optional | `Low Resolution V2`, `Standard V2`, `CGI`, `High Fidelity V2`, `Text Refine`, `Recovery`, `Redefine`, `Recovery V2`, `Standard MAX`, `Wonder` | Model to use for image enhancement. |
| `crop_to_fill` | boolean | optional | Any |  |
| `upscale_factor` | float | optional | Any | Factor to upscale the image by (e.g. 2.0 doubles width and height) |
| `face_enhancement_strength` | float | optional | Any | Strength of the face enhancement. 0.0 means no enhancement, 1.0 means maximum enhancement. Ignored if face enhancement is disabled. |
| `sharpen` | float | optional | Any | Sharpening level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models. |
| `detail` | float | optional | Any | Detail recovery level (0.0-1.0). Applies to Recovery V2 model only. |
| `denoise` | float | optional | Any | Denoising level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models. |
| `output_format` | string | optional | `jpeg`, `png` | Output format of the upscaled image. |
| `subject_detection` | string | optional | `All`, `Foreground`, `Background` | Subject detection mode for the image enhancement. Applies to standard enhance and Recovery V2 models. |
| `strength` | float | optional | Any | Enhancement strength (0.01-1.0). Applies to Text Refine model only. |
| `texture` | integer | optional | Any | Texture detail level for generative upscaling (1-5). Applies to Redefine model only. |
| `image_url` | image | required | Any | Url of the image to be upscaled |
| `autoprompt` | boolean | optional | Any | Enable automatic prompt generation for generative upscaling. Applies to Redefine model only. |
| `creativity` | integer | optional | Any | Creativity level for generative upscaling (1-6). Higher values produce more creative/hallucinated details. Applies to Redefine model only. |
| `fix_compression` | float | optional | Any | Compression artifact removal level (0.0-1.0). Applies to Standard V2, Low Resolution V2, High Fidelity V2, and Text Refine models. |

## Output schema

| Field | Type | Description |
| --- | --- | --- |
| `outputs` | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked. |
| `seed` | json | Deterministic seed used for generation, or null if the provider doesn't return one. |
| `timing` | json | Provider timing info (inference_ms etc.), or null. |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id` | string | The unique identifier of the run. |
| `status` | string | Terminal status: "succeeded", "failed", or "cancelled". |
| `output` | object \| null | The run output. Null if the run failed or was cancelled. |
| `duration_ms` | number \| null | Total run duration in milliseconds. |
| `created_at` | string \| null | ISO 8601 timestamp when the run was created. |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state. |
| `metadata` | object \| null | The metadata object passed at run creation, if any. |

- **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
- **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

- [Playground](https://app.runflow.io/models/topaz/upscale/image)
- [API Reference](https://app.runflow.io/models/topaz/upscale/image?tab=api)
- [Documentation](https://docs.runflow.io)
- [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related


  Browse the catalog.
  Callbacks, polling, statuses.
  Handle async results.
  How requests bill out.

---

# Quickstart
<!-- https://docs.runflow.io/quickstart -->

Start an AI model run with one HTTP call, then receive the result by callback or polling. This quickstart uses [Background Replace](/models/runflow/background-replace) (`$0.35/request`).

## 1. Get a key

Sign in at [app.runflow.io/settings/api-keys](https://app.runflow.io/settings/api-keys), create a key, and export it:

```bash
export RUNFLOW_API_KEY="your_api_key_here"
```

## 2. Run the model



```bash cURL
curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Replace the white area on Image 1 with Image 2 as the background.",
      "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
      "file_image": "image.webp",
      "file_reference": "reference.webp"
    },
    "callback_url": "https://your-server.com/webhook"
  }'
```

```python Python
import os, requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/background-replace/runs",
    headers={"Authorization": f"Bearer {os.environ['RUNFLOW_API_KEY']}"},
    json={
        "input": {
            "prompt": "Replace the white area on Image 1 with Image 2 as the background.",
            "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
            "file_image": "image.webp",
            "file_reference": "reference.webp",
        },
        "callback_url": "https://your-server.com/webhook",
    },
)
print(response.json())
```

```javascript Node.js
const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/background-replace/runs",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.RUNFLOW_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: {
        prompt: "Replace the white area on Image 1 with Image 2 as the background.",
        zip_url: "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
        file_image: "image.webp",
        file_reference: "reference.webp",
      },
      callback_url: "https://your-server.com/webhook",
    }),
  },
);
console.log(await response.json());
```



## 3. Read the response

The API returns the run record immediately:

```json
{
  "id": "01J0...",
  "status_code": "queued",
  "model": "runflow/background-replace"
}
```

Use the `id` to either poll [`GET /v1/runs/{id}`](/api-reference/runs/get-run) or wait for the callback at `callback_url`. See [Callbacks](/concepts/callbacks) for the async pattern.

Got an `id`? You're done.

## What's next


  Browse the full catalog.
  Bearer tokens, key rotation.
  Handle the async result.
  Status codes and the error envelope.