> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnific.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flows API

> Run visual AI pipelines via API. Chain together AI tools like upscale, generate, and edit into reusable Flows with dynamic inputs.

<Card title="Visual AI Pipelines" icon="diagram-project">
  Execute multi-step AI workflows with a single API call. Each Flow chains together AI tools into a reusable pipeline.
</Card>

Flows are visual AI pipelines created in [Magnific Spaces](https://www.magnific.com/spaces). Each Flow chains together multiple AI tools (upscale, generate, edit, transform, etc.) into a reusable pipeline. Once published, Flows can be executed programmatically via this API — you provide the required inputs (images, text prompts, etc.) and the Flow runs the entire pipeline, returning the final output.

### Key capabilities

* **Dynamic inputs**: Each Flow defines its own inputs — images, text prompts, numbers, or selections
* **Async execution**: Submit a run, then poll for status or receive a webhook notification
* **Multi-output**: Flows can produce images, videos, or audio depending on the workflow

### How it works

1. **List flows** to discover available workflows
2. **Get flow details** to see required inputs and their types
3. **Run the flow** by providing values for each input, keyed by its `api_key` (recommended) or `id` (legacy)
4. **Poll or webhook** to get the results when execution completes

<div className="my-11">
  <Columns cols={2}>
    <Card title="GET /v1/ai/flows" icon="list" href="/api-reference/flows/list-flows">
      List all available flows
    </Card>

    <Card title="GET /v1/ai/me/flows" icon="user" href="/api-reference/flows/list-my-flows">
      List flows you own, including drafts
    </Card>

    <Card title="GET /v1/ai/flows/{flow-id}" icon="magnifying-glass" href="/api-reference/flows/get-flow">
      Get a flow definition and its inputs
    </Card>

    <Card title="POST /v1/ai/flows/{flow-id}/run" icon="play" href="/api-reference/flows/run-flow">
      Run a flow with your inputs
    </Card>

    <Card title="GET /v1/ai/flows/runs/{run-id}" icon="clock-rotate-left" href="/api-reference/flows/get-run">
      Poll run status and results
    </Card>
  </Columns>
</div>

### Input types

| Input Type | Accepted Values                                         | Example                           |
| ---------- | ------------------------------------------------------- | --------------------------------- |
| `creation` | Image URL, base64-encoded image, or creation identifier | `"https://example.com/photo.jpg"` |
| `text`     | Plain text string                                       | `"A car in the forest"`           |
| `number`   | Numeric value                                           | `0.5`                             |
| `select`   | Value from predefined options                           | `"style_a"`                       |

### Example: Run a flow

```bash theme={null}
curl -X POST "https://api.magnific.com/v1/ai/flows/uqzQLDr2Aw/run" \
  -H "X-Magnific-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "image": "https://example.com/my-sketch.jpg"
    },
    "webhook": "https://your-server.com/webhook"
  }'
```

### Identifiers

Flows are identified by their SQID:

| Format   | Example      | Description                           |
| -------- | ------------ | ------------------------------------- |
| **SQID** | `uqzQLDr2Aw` | Short unique identifier for each flow |

<Note>
  Existing integrations that call the legacy `/v1/ai/apps` paths remain functional. New integrations should use the `/v1/ai/flows` endpoints documented here.
</Note>

## More about Spaces

<a href="https://www.magnific.com/spaces">
  <Frame>
    <img src="https://media.magnific.com/landing-api-playground/images/spaces-hero.png" alt="Magnific Spaces — node-based AI workflow canvas" />
  </Frame>
</a>

[Magnific Spaces](https://www.magnific.com/spaces) is the infinite canvas where you build and publish Flows. Connect AI nodes visually — image generation, upscaling, style transfer, text processing, and more — into reusable workflows. Collaborate with your team in real time, then publish your workflow as a Flow to make it available via this API.

<Columns cols={2}>
  <Card title="Open Magnific Spaces" icon="arrow-up-right-from-square" href="https://www.magnific.com/app/spaces">
    Start building your own AI workflows on the infinite canvas.
  </Card>

  <Card title="Manage your Flows" icon="diagram-project" href="https://www.magnific.com/app/tools/flows">
    View your published Flows and copy their IDs to use with this API.
  </Card>
</Columns>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What are Flows?">
    Flows are visual AI pipelines built in <a href="https://www.magnific.com/spaces">Magnific Spaces</a>. They chain together multiple AI tools (image generation, upscaling, style transfer, etc.) into a single reusable workflow. The API lets you execute these workflows programmatically.
  </Accordion>

  <Accordion title="How do I know what inputs a flow requires?">
    Call `GET /v1/ai/flows/{flow-id}` to get the full definition, including all required inputs with their types and labels. Use each input's `api_key` field (recommended) — a human-friendly identifier matching the node name — as the key in the `inputs` object when running the flow. The UUID-based `id` field is still accepted for backward compatibility (legacy).
  </Accordion>

  <Accordion title="How long do flow executions take?">
    Execution time depends on the workflow complexity and the AI tools involved. Simple single-tool workflows may complete in 10-30 seconds. Multi-step workflows with video generation can take 1-5 minutes. Use webhooks for production integrations.
  </Accordion>

  <Accordion title="What are the rate limits for Flows?">
    See the [Rate Limits](/ratelimits) page for current limits by subscription tier.
  </Accordion>

  <Accordion title="How much do Flows cost?">
    Each flow shows its credit cost in the `tool_metadata.total_cost` field. See the [Pricing page](/pricing) for credit rates.
  </Accordion>
</AccordionGroup>

## Related APIs

* **[Image Upscaler](/api-reference/image-upscaler-creative/image-upscaler)**: Upscale images with AI enhancement
* **[Text to Image](/api-reference/text-to-image/image-generation)**: Generate images from text prompts
* **[Image to Video](/api-reference/image-to-video/overview)**: Convert images into video clips