Use this endpoint to run a published workflow you authored. Credits are charged to the API key owner. Poll the same status endpoint as single-model Cook jobs.

Studio remains admin-gated. The Workflows API does not require admin.

Create Workflow Run

Request

POST /api/v1/workflows/:slug/runs

curl -X POST https://soup.video/api/v1/workflows/passport-id-photo/runs \
  -H "Authorization: Bearer sk_soup_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "photo": "https://example.com/face.jpg",
      "country_preset": "US"
    }
  }'

slug is the workflow slug from Workflow Studio. inputs is the same payload the workflow form would submit.

Response

{
  "job_id": "8f8b3c3d-1a2b-4c5d-6e7f-8a9b0c1d2e3f",
  "status": "processing",
  "check_url": "https://soup.video/api/v1/generations/8f8b3c3d-1a2b-4c5d-6e7f-8a9b0c1d2e3f"
}

Poll check_url with the same API key. See Status.

Access

• Authenticate with a Soup API key (sk_soup_…).
• You can only run workflows you published. Other slugs return 404.
• Draft / unpublished workflows return 403 until you publish.
• Runs are stored as private assets.

Python Example

import time
import requests

API_KEY = "sk_soup_your_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}

create = requests.post(
    "https://soup.video/api/v1/workflows/passport-id-photo/runs",
    headers=headers,
    json={"inputs": {"photo": "https://example.com/face.jpg"}},
)
create.raise_for_status()
job = create.json()

while True:
    status = requests.get(job["check_url"], headers=headers).json()
    if status["status"] != "processing":
        print(status)
        break
    time.sleep(8)