Async job pattern
All Pixii endpoints are asynchronous. Submit a job, get a job_id, then poll the Jobs API until the result is ready.
Every Pixii endpoint is asynchronous: Create listing, Create anything, Scale, Creative strategy and Download visuals. Generating a listing takes about two minutes, and rather than holding an open HTTP connection for two minutes, which times out in most environments, Pixii processes jobs in the background.
When you submit a request, you get a job_id back immediately. You then poll the Jobs API until the job is complete and your results are ready.
How it works
1. Submit a job → POST /v2/api/create_listing → { job_id: "abc123", status: "pending" }
2. Poll for status → GET /v2/api/jobs/abc123 → { status: "processing" }
3. Poll again → GET /v2/api/jobs/abc123 → { status: "processing" }
4. Job complete → GET /v2/api/jobs/abc123 → { status: "completed", output: {...} }Job statuses
| Status | Meaning |
|---|---|
pending | Job received and queued |
processing | Job is actively running |
completed | Job finished successfully, output is ready |
failed | Job failed, see the error field for details |
Polling for results
Call GET /v2/api/jobs/{job_id} repeatedly until the status is completed or failed. We recommend polling every 5 seconds, or every 30 seconds for Scale runs across many products.
If a job fails
When a job fails, the response includes an error code explaining what went wrong. Any credits consumed for a failed job are automatically refunded to your account. If a single visual fails inside a job that otherwise completes, that visual is refunded and the job reports the amount in credits_refunded.
Result URLs
The image and zip URLs in a completed job are signed links that expire. They are issued fresh each time you read the job, so if a link has expired, poll the job again to get a new one.
Webhooks
Webhook support is coming soon. When available, you’ll be able to register a URL that Pixii calls automatically when a job completes, eliminating the need to poll. Until then, polling the Jobs API is the recommended approach.