flows

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 TypeAccepted Values
creationImage URL (https://...), base64-encoded image string, or existing creation identifier
textPlain text string
numberNumeric value
selectValue 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/v1/ai/flows/{flow-id}/run

Request

  • Base URL: https://api.magnific.com
  • URL: https://api.magnific.com/v1/ai/flows/{flow-id}/run
  • Auth: API key in header x-magnific-api-key

Path parameters

flow-idstring required
Example:uqzQLDr2Aw

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

Request body

inputsobject 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
webhookstring 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 request

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

Response

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

status'running' required

Current execution status.

workflow_run_identifierstring required

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

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.