SegmindSegmind / Docs

Workflow API Reference

Call a published PixelFlow workflow over REST: submit to POST /workflows/v2/{slug}, poll the status URL, and fetch results — with cURL, Python, and JavaScript examples.

Published workflows are served from Segmind's async API. The lifecycle is submit → poll → fetch: submitting returns immediately with a request ID and URLs to poll; the result is ready when status reaches COMPLETED.

This is the same async contract used by Segmind's async model inference. Authentication uses your Segmind API key — see authentication.

Submit a request

POST https://api.segmind.com/workflows/v2/{slug}
Authorization: Bearer SG_xxxxxxxxxxxxxxxx
Content-Type: application/json

The body is a JSON object with the key names you gave your workflow's input nodes when publishing:

{
  "prompt": "a lighthouse at dusk, dramatic sky",
  "style": "photographic"
}

Response — the request is queued and you get back where to check on it:

{
  "request_id": "0b7f1d9c-...",
  "status": "QUEUED",
  "poll_url": "https://api.segmind.com/v2/requests/0b7f1d9c-.../status",
  "status_url": "https://api.segmind.com/v2/requests/0b7f1d9c-.../status",
  "response_url": "https://api.segmind.com/v2/requests/0b7f1d9c-..."
}

Poll for status

GET {poll_url}
Authorization: Bearer SG_xxxxxxxxxxxxxxxx
{
  "status": "PROCESSING",
  "request_id": "0b7f1d9c-...",
  "metrics": { "time_in_queue_ms": 312 }
}

status moves through QUEUEDPROCESSINGCOMPLETED (or FAILED). Poll every few seconds; longer-running workflows (video models, large fan-outs) warrant a longer interval.

Fetch the result

When status is COMPLETED, fetch the response:

GET {response_url}
Authorization: Bearer SG_xxxxxxxxxxxxxxxx
{
  "status": "COMPLETED",
  "output": "[{\"keyname\": \"image\", \"value\": {...}}]",
  "images": [
    { "url": "https://...", "content_type": "image/png", "file_size": "482133" }
  ],
  "timings": { "total_ms": 8421 },
  "metrics": {}
}
  • output — a JSON-stringified array of {keyname, value} pairs, one per named output node. Parse it to get your named outputs.
  • images / video / audio — generated media as hosted URLs with content types. Video outputs may include last_frame_url when the model supports returning the final frame.
  • timings / metrics — execution timings and usage metrics.
  • On failure, status is FAILED and error describes what went wrong.

Full example

# 1. Submit
curl -X POST "https://api.segmind.com/workflows/v2/<your-workflow-slug>" \
  -H "Authorization: Bearer $SEGMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse at dusk"}'

# 2. Poll until COMPLETED
curl -X GET "<poll_url>" \
  -H "Authorization: Bearer $SEGMIND_API_KEY"

# 3. Fetch the result
curl -X GET "<response_url>" \
  -H "Authorization: Bearer $SEGMIND_API_KEY"
import os, time, json, requests

api_key = os.environ["SEGMIND_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}

# 1. Submit
submit = requests.post(
    "https://api.segmind.com/workflows/v2/<your-workflow-slug>",
    headers=headers,
    json={"prompt": "a lighthouse at dusk"},
).json()

# 2. Poll until COMPLETED
while True:
    status = requests.get(submit["poll_url"], headers=headers).json()
    if status["status"] in ("COMPLETED", "FAILED"):
        break
    time.sleep(3)

# 3. Fetch the result
result = requests.get(submit["response_url"], headers=headers).json()
outputs = {o["keyname"]: o["value"] for o in json.loads(result["output"])}
print(outputs)
const apiKey = process.env.SEGMIND_API_KEY;
const headers = { Authorization: `Bearer ${apiKey}` };

// 1. Submit
const submit = await fetch(
  "https://api.segmind.com/workflows/v2/<your-workflow-slug>",
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ prompt: "a lighthouse at dusk" }),
  },
).then((r) => r.json());

// 2. Poll until COMPLETED
let status;
do {
  await new Promise((r) => setTimeout(r, 3000));
  status = await fetch(submit.poll_url, { headers }).then((r) => r.json());
} while (status.status !== "COMPLETED" && status.status !== "FAILED");

// 3. Fetch the result
const result = await fetch(submit.response_url, { headers }).then((r) =>
  r.json(),
);
const outputs = Object.fromEntries(
  JSON.parse(result.output).map((o) => [o.keyname, o.value]),
);
console.log(outputs);

Errors

CodeMeaning
401Missing or invalid API key — check the Authorization: Bearer header.
404Unknown workflow slug — confirm the slug from your publish dialog.
4xxInvalid input — a required key name is missing or a value has the wrong type.

See also

On this page