API Reference

Responses & Errors

Error schema and recommended handling strategies.

Error Schema

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to process this video",
    "request_id": "req_123456"
  }
}

Endpoint	HTTP	Example Message	Action
/api/upload	400	Invalid file type	Use supported video MIME
/api/upload	400	File too large	Keep file <= 500MB
/v1/jobs/{job_id}	404	Job not found	Check job id and key ownership
/api/download/{job_id}	400	Job not completed	Poll status until completed
/v1/jobs	500	Processing failed	Retry with backoff

All clients should handle non-2xx responses as structured error payloads.
Use explicit JSON schema validation for request payloads on your side.
Treat output_url as an asynchronous artifact and not an immediate response contract.
Persist job lifecycle state transitions for auditing and support.

Check	How to Verify
Authentication	Call endpoint with valid and invalid key, confirm 200 vs 401
Rate limits	Burst test and confirm 429 handling with backoff
Idempotency	Retry same request and verify no duplicate side effects
Observability	Confirm request_id/job_id appears in logs and dashboards

Class	Examples	Action
Client Errors (4xx)	invalid_request, invalid_api_key	Fix payload/config
Capacity/Limit	rate_limited, insufficient_credits	Retry/backoff or top-up
Server Errors (5xx)	internal_error, timeout	Retry with fallback and alerting

Public API v1 Admin

Client