Skip to main content
VVela
Try the API

Jobs & Webhooks

All compute endpoints in ImagePipeline are asynchronous. A request returns immediately with a job_id and status: queued; you retrieve the result by polling or via a webhook.

The job lifecycle​

The ImagePipeline job lifecycle: queued, pending, processing, then completed or failed/cancelled

status is one of: queued, pending, processing, completed, failed, cancelled.

The queued response​

Every compute POST returns a JobQueuedResponse:

{
  "job_id": "job_a1b2c3",
  "status": "queued",
  "endpoint": "/generate/image/v1",
  "estimated_time_seconds": 8,
  "queued_at": "2026-05-30T12:00:00Z"
}

Option A — Poll​

Each compute endpoint has a matching status endpoint: GET /{endpoint}/status/{job_id}. Poll it until status is terminal.

curl https://api.imagepipeline.io/generate/image/v1/status/job_a1b2c3 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY"

The JobStatusResponse carries progress, timing, credits, and — on success — the result:

{
  "job_id": "job_a1b2c3",
  "status": "completed",
  "progress": 100,
  "result_url": "https://cdn.imagepipeline.io/...signed...",
  "result_mime_type": "image/webp",
  "queue_wait_seconds": 1.1,
  "inference_time_seconds": 6.2,
  "total_elapsed_seconds": 7.3,
  "credits_charged": true,
  "credits_amount": 1
}

On failure you get an error, a machine-readable failure_reason_code, and a retryable flag — see Errors.

tip

Use polling for development. Poll at a sensible interval (e.g. every 1–2s) rather than in a tight loop.

Option B — Webhooks​

Pass a callback_url in any compute request body and ImagePipeline POSTs a WebhookEvent to it when the job reaches a terminal state. Recommended for production.

{
  "job_id": "job_a1b2c3",
  "user_id": "usr_123",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/...signed...",
  "result_mime_type": "image/webp",
  "result_size_bytes": 184320,
  "timestamp": 1769774400
}

status in a webhook is always completed or failed. Retrieve the canonical schema any time:

curl https://api.imagepipeline.io/webhooks/event-schema \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY"

Result URL lifecycle​

Result URLs expire within 24 hours

result_url is a temporary pre-signed download link. Download and store the file in your own storage immediately after the job completes — do not persist the URL itself, it will stop working.

Some webhook payloads can also include result_base64 for small assets, avoiding a second download round-trip.