Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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:

  1. Start the job with a POST. The call returns immediately with the job state.
  2. Poll the resource that owns the job (the image, video, audio or export job), not the start endpoint, until the status is terminal.
  3. 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

JobStartPollStatus fieldJob id
AI descriptiondescribe=true on upload, or POST /v1/images/:id/describeGET /v1/images/:iddescription.statusdsc_ (webhooks only)
Social-ready videoX-PixelVault-Social-Ready: true on upload, or POST /v1/videos/:id/optimizeGET /v1/videos/:idsocial_optimization.statusvop_ (webhooks only)
Video transcript + storyboardPOST /v1/videos/:id/enrichGET /v1/videos/:idenrichment.statusenrichment.job_id, ven_
Audio transcriptPOST /v1/audio/:id/enrichGET /v1/audio/:idenrichment.statusenrichment.job_id, aen_
Export archivePOST /v1/exportGET /v1/export-jobs/:idstatusjob_id, exp_

Statuses

JobIn progressTerminalOther values
Video optimization, video enrichment, audio enrichmentpending, processingcomplete, failednot_requested; optimization also not_needed when the original is already social-compatible
Exportpending, processingcomplete, failed, expired (archive older than 24 hours)
AI descriptionpendingdone, failednull 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).

JobWhereCodeMeaning
AI descriptiondescription.errordescribe_timeoutThe model didn't answer in time, or the job never reported back within 2 minutes. Not refunded.
describe_failedThe model call failed.
describe_invalidThe model answered with output that couldn't be parsed.
Social-ready videosocial_optimization.error.codeoptimization_unavailableThe transcoding service was temporarily unavailable.
source_unavailableThe original was no longer available (also used by video and audio enrichment).
storage_limit_reachedStoring the result would exceed the plan's storage quota (also used by enrichment).
optimization_failedTranscoding failed.
invalid_optimized_videoThe output was empty, incomplete, or failed H.264/AAC fast-start validation.
Video and audio enrichmentenrichment.error.codeenrichment_unavailableThe transcription service was temporarily unavailable.
transcription_failedSpeech-to-text failed.
storyboard_failedStoryboard frames couldn't be extracted (video only).
invalid_enrichment_outputThe generated transcript or storyboard didn't validate.
Exporterror on the export job; export.error.code in the webhookexport_failedThe 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).

Example
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