Polling for Results

Generation tasks are async. After submitting you receive a taskId and choose one of three completion strategies.

Strategy comparison

Strategy	When to use	Cost
get-task-status (poll)	Cron jobs, batch scripts where latency doesn’t matter	1 request per poll
wait-for-task (single call)	Synchronous integrations, simple scripts	1 request total — server holds the connection
Webhooks	Production apps, agents, fan-out architectures	0 requests — Playcut POSTs to you

get-task-status — manual polling

curl -X POST https://api.playcut.ai/api/v1/tools/get-task-status/execute \
  -H "Authorization: Bearer $PLAYCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskId": "65f3a1b2c3d4e5f600000002"}'

{
  "data": {
    "taskId": "65f3a1b2c3d4e5f600000002",
    "type": "GEMINI_TEXT_TO_IMAGE",
    "status": "COMPLETED",
    "output": { "assetIds": ["asset_xyz"] },
    "processingInfo": { "progress": 100 }
  }
}

wait-for-task — server-side blocking

One call that returns when the task hits a terminal state. No client-side polling loop.

curl -X POST https://api.playcut.ai/api/v1/tools/wait-for-task/execute \
  -H "Authorization: Bearer $PLAYCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskId": "65f3a1b2c3d4e5f600000002"}'

Connection times out after the task’s hard deadline (image 5 min, video 10 min). Retry once on timeout — Playcut never charges for a timeout.

Status values

Status	Meaning
PENDING	Queued, not started
PROCESSING	Worker is running
COMPLETED	Output ready in output.assetIds
FAILED	See error field

Recommended poll intervals (if you must poll)

Task type	Typical latency	Poll every
Image	5–15 s	3 s
Video	60–120 s	5–10 s
TTS	3–10 s	2 s
Actor	15–30 s	5 s

Polling loop (TypeScript)

const BASE = "https://api.playcut.ai/api/v1/tools"

async function waitForTask(taskId: string, apiKey: string, intervalMs = 5000) {
  const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }
  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, intervalMs))
    const res = await fetch(`${BASE}/get-task-status/execute`, {
      method: "POST",
      headers,
      body: JSON.stringify({ taskId }),
    }).then((r) => r.json())

    if (res.data.status === "COMPLETED") return res.data.output
    if (res.data.status === "FAILED") throw new Error(res.data.error?.message ?? "Task failed")
  }
  throw new Error("Timed out waiting for task")
}

Tip

In production, prefer webhooks — zero wasted requests, instant notification, automatic retry.

MCP equivalent

When using the MCP server, call wait-for-task directly — it’s the same tool, just dispatched through the MCP protocol instead of REST.