Flows - Run a flow

curl --request POST \
  --url https://api.magnific.com/v1/ai/flows/{flow-id}/run \
  --header 'Content-Type: application/json' \
  --header 'x-magnific-api-key: <api-key>' \
  --data '
{
  "inputs": {
    "image": "car in the forest"
  },
  "webhook": "https://www.example.com/webhook"
}
'

import requests

url = "https://api.magnific.com/v1/ai/flows/{flow-id}/run"

payload = {
    "inputs": { "image": "car in the forest" },
    "webhook": "https://www.example.com/webhook"
}
headers = {
    "x-magnific-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-magnific-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inputs: {image: 'car in the forest'},
    webhook: 'https://www.example.com/webhook'
  })
};

fetch('https://api.magnific.com/v1/ai/flows/{flow-id}/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magnific.com/v1/ai/flows/{flow-id}/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'inputs' => [
        'image' => 'car in the forest'
    ],
    'webhook' => 'https://www.example.com/webhook'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-magnific-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.magnific.com/v1/ai/flows/{flow-id}/run"

	payload := strings.NewReader("{\n  \"inputs\": {\n    \"image\": \"car in the forest\"\n  },\n  \"webhook\": \"https://www.example.com/webhook\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-magnific-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.magnific.com/v1/ai/flows/{flow-id}/run")
  .header("x-magnific-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {\n    \"image\": \"car in the forest\"\n  },\n  \"webhook\": \"https://www.example.com/webhook\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.magnific.com/v1/ai/flows/{flow-id}/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-magnific-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": {\n    \"image\": \"car in the forest\"\n  },\n  \"webhook\": \"https://www.example.com/webhook\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "running",
  "workflow_run_identifier": "vCrK3Aa47y"
}

Flows API

Flows - Run a flow

Triggers the execution of a flow. Provide values for all required inputs defined in the flow’s definition (see the GET endpoint).

The inputs object maps each input’s api_key (recommended) or its id (UUID, legacy) to its value:

Input Type	Accepted Values
`creation`	Image URL (`https://...`), base64-encoded image string, or existing creation identifier
`text`	Plain text string
`number`	Numeric value
`select`	Value from allowed options

This endpoint is asynchronous. It returns immediately with status: "running" and a workflow_run_identifier. Provide a webhook URL to receive notifications when the execution completes. The webhook receives two events: initialized (run started) and finished/failed (run completed).

The webhook payload for a completed run includes a result object containing images, videos, and audios arrays with download URLs for the generated assets.

POST

flows

{flow-id}

run

Flows - Run a flow

curl --request POST \
  --url https://api.magnific.com/v1/ai/flows/{flow-id}/run \
  --header 'Content-Type: application/json' \
  --header 'x-magnific-api-key: <api-key>' \
  --data '
{
  "inputs": {
    "image": "car in the forest"
  },
  "webhook": "https://www.example.com/webhook"
}
'

import requests

url = "https://api.magnific.com/v1/ai/flows/{flow-id}/run"

payload = {
    "inputs": { "image": "car in the forest" },
    "webhook": "https://www.example.com/webhook"
}
headers = {
    "x-magnific-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-magnific-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inputs: {image: 'car in the forest'},
    webhook: 'https://www.example.com/webhook'
  })
};

fetch('https://api.magnific.com/v1/ai/flows/{flow-id}/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magnific.com/v1/ai/flows/{flow-id}/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'inputs' => [
        'image' => 'car in the forest'
    ],
    'webhook' => 'https://www.example.com/webhook'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-magnific-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.magnific.com/v1/ai/flows/{flow-id}/run"

	payload := strings.NewReader("{\n  \"inputs\": {\n    \"image\": \"car in the forest\"\n  },\n  \"webhook\": \"https://www.example.com/webhook\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-magnific-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.magnific.com/v1/ai/flows/{flow-id}/run")
  .header("x-magnific-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {\n    \"image\": \"car in the forest\"\n  },\n  \"webhook\": \"https://www.example.com/webhook\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.magnific.com/v1/ai/flows/{flow-id}/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-magnific-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": {\n    \"image\": \"car in the forest\"\n  },\n  \"webhook\": \"https://www.example.com/webhook\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "running",
  "workflow_run_identifier": "vCrK3Aa47y"
}

Authorizations

x-magnific-api-key

string

header

required

Your Magnific API key. Required for authentication. Learn how to obtain an API key

Path Parameters

flow-id

string

required

Short unique identifier (sqid) of the flow to execute. Discover flow identifiers via GET /v1/ai/flows.

Example:

"uqzQLDr2Aw"

Body

application/json

inputs

object

required

Map of input identifier to value. Use each input's api_key (recommended) or its id (UUID, legacy) as the key — both are accepted.

Value types by input type:

creation (image/media): URL string, base64-encoded string, or existing creation sqid
text: Plain text string
number: Numeric value
select: Value from allowed options

Show child attributes

webhook

string<uri>

Optional callback URL that receives status notifications during execution. The webhook receives POST requests with the event payload (see webhook event schema). Events are sent when the run starts (initialized) and when it finishes (finished or failed).

Example:

"https://www.example.com/webhook"

Response

Accepted - Flow execution started. Use the webhook to receive results.

status

enum<string>

required

Current execution status.

Available options:

running

Example:

"running"

workflow_run_identifier

string

required

Unique identifier for this flow execution run. Matches the run_id in webhook events.

Example:

"vCrK3Aa47y"

Flows - Get flow definition

Flows - Get run status

⌘I

Get started

APIs

Flows - Run a flow

Authorizations

Path Parameters

Body

Response