API Reference

Errors

Failures use standard HTTP status codes and a small JSON envelope.

Error response shape

Example

{
  "statusCode": 400,
  "message": "script is required"
}

Status codes

400

Bad request

Malformed body, missing script, an unknown image style or voice provider, a folder from another workspace, no credits left, or a plan that does not allow the action.

401

Unauthorized

Missing or invalid Authorization header, or the token has been revoked.

404

Not found

The video does not exist, or it was not created with a key from this workspace.

500

Server error

Something on our end. Safe to retry reads; for writes (Create a video) check the video before retrying so you do not double-charge.

Retry guidance

Reads (GET) are safe to retry. Use exponential backoff for 5xx responses.
Video creation is not idempotent. If a POST /v1/ai-videos call times out, it may still have started a video and charged credits. Check before retrying.
401 will not become 200 by retrying. Check that the token is correct, hasn't been revoked, and is sent as Authorization: Bearer vp_....
A failed video is not an HTTP error. Generation problems surface as status: "failed" on the video, with the reason in error.