Webhooks

Pass callback_url when creating a task and the API will POST the task to it once the task reaches a terminal status (completed, failed or canceled). The body is exactly the shape GET /api/v1/tasks/:id returns — one handler serves both.

Delivery is attempted twice with an 8-second timeout and is best-effort. Treat the webhook as a wake-up signal: on receipt (and as a fallback if it never arrives), confirm the state by fetching GET /api/v1/tasks/:id. Responses are not signed — re-fetching is the verification.

The URL must be HTTPS and publicly reachable — localhost and private-network addresses are rejected. Sandbox (test-key) tasks fire the same callback about 35 seconds after creation, so you can develop your handler for free.

Create the task with a callback_url, then handle the POST — the body is the same shape GET /api/v1/tasks/:id returns:

// e.g. a Next.js / TanStack Start route handler
export async function POST(request) {
  const task = await request.json();

  if (task.status === 'completed') {
    const urls = task.data.results;   // download / store promptly
  }
  if (task.status === 'failed') {
    console.error(task.failed_reason); // credits were refunded
  }

  // Recommended: confirm via GET /api/v1/tasks/:id before acting.
  return new Response(null, { status: 200 });
}