Finalize a media upload (step 3 of 3)

POST 
/media/:id/complete

Call after uploading the file to the presigned upload_url. Verifies the file actually exists (400 file_not_uploaded when it does not) and that its magic bytes match the declared content type (400 file_type_mismatch — the media is then marked failed). Videos get a thumbnail generated in the background. Idempotent: calling on already-ready media returns 200. 400 upload_failed when the media was previously marked failed. No request body is required.

Request

Responses

200

Media finalized (or already ready)

400

Validation error — see error.code and error.details

401

Missing/invalid/revoked/expired API key (codes invalid_api_key, api_key_revoked, api_key_expired, api_key_required, auth_failed). Auth-layer 401s omit error.retryable and meta.request_id.

402

No active subscription (code subscription_required — the error object also carries subscription_status), or insufficient AI credits (insufficient_credits) / paid plan required (upgrade_required).

403

API key missing the required scope (insufficient_scope), storage quota exceeded (storage_quota_exceeded), or account limit reached (account_limit_reached)

404

Resource not found in your organization/workspace (not_found)

429

Rate limit exceeded (rate_limit_exceeded, or plan budgets post_limit_reached / daily_limit_reached on schedulePost). All 429s carry Retry-After. The API-key limiter additionally sets the X-RateLimit-* headers and error.details {limit, remaining, reset_at}.

Response Headers

Retry-After

Seconds to wait before retrying

X-RateLimit-Limit

Requests allowed in the window (API-key limiter only)

X-RateLimit-Remaining

Requests remaining (API-key limiter only)

X-RateLimit-Reset

Unix seconds when the window resets (API-key limiter only)

500

Internal error (internal_error and endpoint-specific 5xx codes). Retryable.