Getting started

1. Create an API key

Keys are created on the Developers page of the Crayo app. Every key starts with crayo_sk_ and acts as the whole account, so keep it on a server and read it from an environment variable rather than shipping it in a client app.

• An account can hold up to 5 active keys at once, each with its own name, so every app, environment or teammate can have one that is revoked on its own.
• Expiry is picked at creation: 1 day, 1 week, 1 month, 1 year, never. The dashboard defaults to 1 month. An expired key answers 401 exactly like a revoked one.
• Only a hash of the key is stored, so a lost key cannot be recovered. Create a new one, deploy it, then revoke the old one.

2. Send it as a bearer token

The base URL is https://api.crayo.ai. Every request carries the key in the Authorization header. There is nothing else to sign and no session to keep alive. POST and PATCH bodies are JSON with a Content-Type: application/json header, GET and DELETE take no body, and request bodies are capped at 512KB.

curl "https://api.crayo.ai/v1/account" \
  -H "Authorization: Bearer $CRAYO_API_KEY"

A good first call is GET /v1/account. It is free and returns your plan, credit balances, storage usage and the rate limits that apply to the key.

3. Understand credits

The API spends the same credits as the Crayo app, from the same balance. Reads are free. Anything that generates or renders media costs credits, and they are spent when a request is accepted rather than when it finishes well, so a failed render or an AutoClip job that finds fewer clips than requested leaves them spent. View Tracker is the exception: a lookup that fails on our side is refunded.

Storage is a separate budget. Uploads and imports cost no credits but count against your plan storage, and so does everything you generate or render. Going over returns 402 STORAGE_LIMIT_EXCEEDED.

4. Rate limits

Limits are per API key. Most endpoints share the default budget, while the expensive and the pollable endpoints get their own tiers.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Going over returns 429 with code RATE_LIMITED and a Retry-After header in seconds.

View Tracker has its own, higher limits that count per account rather than per key, so a busy tracker integration never eats the budget of your other calls.

5. Errors

Failures come back in one shape, with a stable code you can branch on and a message written for a human reading a log. Branch on the code: messages get clearer over time, codes do not change.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title is required"
  }
}

These four can come back from any endpoint.

Endpoint-specific codes are listed on each endpoint. The most common across the API are below, with the number of endpoints that can return each one.

6. Webhooks

Renders, AutoClip jobs, speech enhancements and tracker refreshes run in the background. Register an https endpoint with POST /v1/webhooks and we send one signed POST the moment the work is done. The signing secret starts with crayo_whsec_ and is returned exactly once.

Each delivery carries a crayo-signature header shaped like t=1755785271,v1=<hex>: an HMAC-SHA256 over <t>.<raw body> using your webhook secret. Deliveries are attempted up to 5 times, backing off exponentially from 30 seconds, and an endpoint that fails 20 times in a row is disabled. Read the Webhooks reference for the endpoints and payloads.

Next steps

• Clip a long video: AutoClip.
• Compose and render your own video: Projects and Exports.
• Generate a client from the OpenAPI specification at /docs/openapi.json.
• Missing an endpoint? Ask in Discord or email support@crayo.ai.