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

Idempotency

Networks fail after the server has done the work: the upload landed, but the response never reached you. Send an Idempotency-Key header on an upload and you can retry the exact same request without storing, counting, or billing a second copy. The retry returns the original asset.

Idempotency keys are supported on uploads that create media: POST /v1/images, POST /v1/videos, POST /v1/videos/uploads (resumable video), and POST /v1/audio. They need a key-authenticated request: keyless image uploads validate the header's format but ignore it, and batch uploads don't accept it (a batch is already idempotent per collection type + name).

Send a key

A key is 1–255 printable ASCII characters with no spaces (a malformed key is 400 validation_error). Use something derived from the work you're doing (release-notes-hero-v1, a job id, a UUID you persist before the first attempt), and send the same value on every retry.

Example
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Idempotency-Key: release-notes-hero-v1" \
  -F "file=@hero.png"

What a retry returns

SituationResponse
First request with this keyThe normal success response (201)
Same key, same inputs, original succeeded200 with the stored asset and "replayed": true
Same key, different inputs422 idempotency_key_reuse
Video/audio: same key while the first request is still uploading409 idempotency_in_progress (the error carries upload_id, asset_id, expires_at); retry later
Video/audio: the asset created with this key was deleted410 idempotency_result_deleted

A replay describes the asset as it was stored, not the parameters of the retry. Fields applied only to new assets (custom metadata, describe=true) are ignored on a replay: change metadata later with PATCH.

{
  "data": {
    "id": "img_abc123",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
    "replayed": true
  }
}

Conflicts: 422 idempotency_key_reuse

Reusing a key with different inputs returns 422 idempotency_key_reuse on images, videos and audio alike. That refusal is deliberate: returning a URL for the wrong asset would be worse than failing. Use a new key for a new upload.

HTTP/1.1 422 Unprocessable Content

{
  "error": {
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with different video inputs."
  }
}

What counts as "different" depends on the media type:

ImagesVideo and audio
Compared inputsImage bytes and visibility; also refused once a temporary image has passed its expires_inSource (bytes or URL), filename, size, visibility, social-ready flag, TTL, folder, collection, metadata
Key retentionAs long as the image exists24 hours: an unfinished upload session expires 24 hours after it starts, and a completed upload's replay marker is kept 24 hours after completion
Checksum headerNone: the server hashes the bytesDirect byte uploads with a key must send X-PixelVault-Content-SHA256 (64 hex chars). Missing: 400 idempotency_checksum_required; bytes don't match: 400 checksum_mismatch. URL imports need no checksum.
Concurrent duplicatesBoth run; the loser returns the winner's image as a replay409 idempotency_in_progress until the first finishes

Video and audio checksums

For direct byte uploads, compute the SHA-256 of the file once and send it with the key. PixelVault verifies it while streaming, so a corrupted retry can never be mistaken for the original:

SHA256=$(shasum -a 256 launch-demo.mp4 | awk '{print $1}')
curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: video/mp4" \
  -H "Content-Length: $(wc -c < launch-demo.mp4)" \
  -H "X-PixelVault-Filename: launch-demo.mp4" \
  -H "X-PixelVault-Content-SHA256: $SHA256" \
  -H "Idempotency-Key: release-demo-v1" \
  --data-binary @launch-demo.mp4

Resumable video uploads take the whole-file sha256 in the POST /v1/videos/uploads body instead of the header. Re-initiating an active session with the same key returns 200 with the same upload_id and replayed: true, so you can resume; once completed it returns the committed asset. Each part of a keyed session needs X-PixelVault-Part-SHA256 (400 part_checksum_required otherwise); re-sending a stored part with the same bytes returns replayed: true, different bytes return 409 part_already_uploaded. POST …/complete is naturally replayable after a lost success response. See the large-file walkthrough.

Idempotency is not deduplication

An idempotency key makes one logical request retry-safe; different keys always create distinct assets, and content is never deduplicated across owners or privacy boundaries. For images only, dedupe=true is the content-reuse option: an existing image with identical bytes, visibility, folder and at least the lifetime you ask for is returned (200, "deduplicated": true) and nothing is stored or counted. Dedup is best-effort (simultaneous uploads of the same bytes can each be stored), and dedupe cannot be combined with Idempotency-Key (400 validation_error). Video and audio have no dedupe option.

Next steps