Async jobs
Some work takes longer than a request should: describing an image, transcoding a social-ready video copy, transcribing video or audio, and building an export archive. PixelVault runs these as background jobs. Every one follows the same pattern:
- Start the job with a
POST. The call returns immediately with the job state. - Poll the resource that owns the job (the image, video, audio or export job), not the start endpoint, until the status is terminal.
- Or subscribe to the job's webhook events and skip polling.
curl -i -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/enrich \
-H "Authorization: Bearer $PIXELVAULT_API_KEY"
HTTP/1.1 202 Accepted
{ "data": { "id": "vid_abc123", "enrichment": { "job_id": "ven_abc123", "status": "pending" } } } The jobs
| Job | Start | Poll | Status field | Job id |
|---|---|---|---|---|
| AI description | describe=true on upload, or POST /v1/images/:id/describe | GET /v1/images/:id | description.status | dsc_ (webhooks only) |
| Social-ready video | X-PixelVault-Social-Ready: true on upload, or POST /v1/videos/:id/optimize | GET /v1/videos/:id | social_optimization.status | vop_ (webhooks only) |
| Video transcript + storyboard | POST /v1/videos/:id/enrich | GET /v1/videos/:id | enrichment.status | enrichment.job_id, ven_ |
| Audio transcript | POST /v1/audio/:id/enrich | GET /v1/audio/:id | enrichment.status | enrichment.job_id, aen_ |
| Export archive | POST /v1/export | GET /v1/export-jobs/:id | status | job_id, exp_ |
Statuses
| Job | In progress | Terminal | Other values |
|---|---|---|---|
| Video optimization, video enrichment, audio enrichment | pending, processing | complete, failed | not_requested; optimization also not_needed when the original is already social-compatible |
| Export | pending, processing | complete, failed, expired (archive older than 24 hours) | |
| AI description | pending | done, failed | null when never requested; a pending older than 2 minutes is reported as failed with error: "describe_timeout" |
Failed video and audio jobs carry an error object with a safe code and message; a failed description carries an error string. Background workers retry video, audio and export jobs up to 3 times before marking them failed. Failed video and audio jobs return their reserved monthly seconds; a failed description is refunded unless it timed out.
200 vs 202
The video and audio start endpoints are idempotent and tell you where the job is by status code:
- 202: the job is queued or processing (newly queued, or already in flight). Poll.
- 200: the job is already complete, or (optimization only) the original is already compatible and no copy is needed. Read the result from the response.
Calling start again never queues a duplicate: it returns the current job. A failed job is retried by calling start again, which creates a new attempt with a new job id. POST /v1/images/:id/describe always answers 200: an image that is already described or in progress returns its current state and uses no allowance; a failed one is retried. POST /v1/export answers 202, or 409 export_in_progress (with the active job_id) while another export for the project is running.
Job failure codes
A job that fails in the background doesn't produce an HTTP error: the failure is stored on the resource you poll and sent in the .failed webhook. These codes therefore aren't on Errors, which lists HTTP responses (including the ones a start call can return, such as 402 enrichment_limit_reached or 503 optimization_unavailable).
| Job | Where | Code | Meaning |
|---|---|---|---|
| AI description | description.error | describe_timeout | The model didn't answer in time, or the job never reported back within 2 minutes. Not refunded. |
describe_failed | The model call failed. | ||
describe_invalid | The model answered with output that couldn't be parsed. | ||
| Social-ready video | social_optimization.error.code | optimization_unavailable | The transcoding service was temporarily unavailable. |
source_unavailable | The original was no longer available (also used by video and audio enrichment). | ||
storage_limit_reached | Storing the result would exceed the plan's storage quota (also used by enrichment). | ||
optimization_failed | Transcoding failed. | ||
invalid_optimized_video | The output was empty, incomplete, or failed H.264/AAC fast-start validation. | ||
| Video and audio enrichment | enrichment.error.code | enrichment_unavailable | The transcription service was temporarily unavailable. |
transcription_failed | Speech-to-text failed. | ||
storyboard_failed | Storyboard frames couldn't be extracted (video only). | ||
invalid_enrichment_output | The generated transcript or storyboard didn't validate. | ||
| Export | error on the export job; export.error.code in the webhook | export_failed | The archive couldn't be built. The job's error field carries a message; start a new export. |
Every code above can be retried by calling the start endpoint again, except source_unavailable (the original is gone) and storage_limit_reached (free storage or upgrade first). Video posters are generated during upload; if one is missing, POST /v1/videos/:id/poster retries it synchronously and answers 503 poster_unavailable (temporary), 422 poster_too_large, or 422 poster_generation_failed when it can't.
Poll with backoff and a deadline
Poll the owning resource with exponential backoff (start around 2 seconds, cap around 30), and give up locally after a deadline that suits your caller. A local timeout never cancels the server job: persist the asset id and job id and resume polling later. The CLI and SDK wait helpers implement exactly this (waitForEnrichment / wait_for_enrichment, enrich-video --timeout).
const API = "https://api.pixelvault.dev/v1";
const headers = { Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}` };
// Start (or resume) the job. 202 = queued or running, 200 = already complete.
await fetch(`${API}/videos/vid_abc123/enrich`, { method: "POST", headers });
// Poll the asset, not the start endpoint, with backoff and a local deadline.
async function waitForEnrichment(id, timeoutMs = 600_000) {
const deadline = Date.now() + timeoutMs;
for (let delay = 2_000; Date.now() < deadline; delay = Math.min(delay * 2, 30_000)) {
const res = await fetch(`${API}/videos/${id}`, { headers });
const { data } = await res.json();
const { status } = data.enrichment;
if (status === "complete" || status === "failed") return data.enrichment;
await new Promise((r) => setTimeout(r, delay));
}
return { status: "timeout" }; // the server job keeps running; poll again later
}
const enrichment = await waitForEnrichment("vid_abc123");
console.log(enrichment.status, enrichment.transcript?.vtt_url); Webhooks instead of polling
On Starter and Pro, subscribe an endpoint to the job's events and react when it finishes. Each job emits a .completed and a .failed event: image.description.*, video.optimization.*, video.enrichment.*, audio.enrichment.*, and export.*. Delivery is at least once, so keep polling as the fallback for a missed event. See Webhooks.
Next steps
- Video transcripts and audio transcription end to end.
- AI descriptions & search.
- Export all media.