Getting Started
Authentication
Authentication model for legacy and public API endpoints.
Current State
Public API routes under /v1 require X-Api-Key and enforce per-key rate limit.
Legacy routes under /api/* are kept for backward compatibility and do not require X-Api-Key.
Required Headers
| Route Group | Header | Required |
|---|---|---|
| /v1/* | X-Api-Key | Yes |
| /api/* | None | No (legacy compatibility) |
Server-side Only
- Never expose X-Api-Key in browser code.
- Call /v1 endpoints from backend routes or workers.
- Use separate API keys per environment and integration.
Common Auth Errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | X-Api-Key header missing |
| 401 | invalid_api_key | Key not recognized |
| 404 | Job not found | Job id is invalid or not owned by this key |
Production Readiness
- Pin SDK/API versions in deployment manifests and release notes.
- Record request_id/job_id in logs for every API interaction.
- Run smoke tests after each deploy using a known short test video.
- Separate dev/staging/prod keys and rotate keys regularly.
Tip: Treat docs examples as baseline templates; finalize payload defaults in your own backend policy layer.
Acceptance Checklist
- Validate one success path and one failure path end-to-end.
- Confirm credits, usage metrics, and output links are consistent.
- Set retry and timeout policy for 429/5xx response handling.
- Document rollback procedure for integration incidents.
Key Rotation Policy
- Create new key and deploy it in parallel.
- Shift traffic gradually to the new key.
- Monitor usage and errors for 24h.
- Disable old key only after stable verification.