> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eversince.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Three complete exchanges over the REST API.

Every example uses the same headers:

```
Authorization: Bearer $EVERSINCE_API_KEY
Content-Type: application/json
```

## A file in, cut, rendered, delivered

**1. Upload.** Request an upload URL, PUT the bytes, confirm.

```bash theme={"dark"}
curl -X POST https://eversince.ai/api/v1/uploads \
  -d '{"file_name": "kitchen.mp4", "content_type": "video/mp4", "file_size": 48213344}'
# → { "upload_url": "…", "r2_key": "…", "expires_in": 3600 }

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @kitchen.mp4

curl -X POST https://eversince.ai/api/v1/uploads/confirm \
  -d '{"r2_key": "…", "file_name": "kitchen.mp4", "file_size": 48213344, "content_type": "video/mp4"}'
# → { "upload_id": "…", "type": "video" }
```

`upload_id` is the item's id from here on.

**2. Transcribe.** Media under five minutes is transcribed within the call. Longer media returns a job, and once `get_jobs` reports it done, the same call returns the stored words.

```bash theme={"dark"}
curl -X POST https://eversince.ai/api/v1/tools/transcribe_media \
  -d '{"ref": "<upload_id>"}'
```

**3. Build a timeline.** Create one, then add the clip. `source` is the stretch of the file in seconds. Leaving out `from` places the clip after the last one on that track, and a fresh timeline has one visual track, `visual-main`. A fresh document nobody has edited accepts a write without `if_revision`.

```bash theme={"dark"}
curl -X POST https://eversince.ai/api/v1/tools/manage_timelines \
  -d '{"create": {"name": "Kitchen reel"}}'
# → data.timeline_id, and data.created with its name

curl -X POST https://eversince.ai/api/v1/tools/edit_timeline \
  -d '{
    "timeline_id": "<timeline_id>",
    "operations": [
      {"type": "addClip", "trackId": "visual-main", "ref": "<upload_id>", "source": [12.0, 27.5]}
    ]
  }'
# the response names the clip's id and the new revision; later writes pass it as if_revision
```

**4. Check, then render.** `check_timeline` is free and reports what a render would show wrong. The render takes an idempotency key generated for this call.

```bash theme={"dark"}
curl -X POST https://eversince.ai/api/v1/tools/check_timeline -d '{"timeline_id": "<timeline_id>"}'

curl -X POST https://eversince.ai/api/v1/tools/render_timeline \
  -d '{"timeline_id": "<timeline_id>", "idempotency_key": "6f1c…"}'
# → a job: { "job_id": "…", … }
```

**5. Collect the result.** Poll for it, or receive it on a webhook.

```bash theme={"dark"}
curl -X POST https://eversince.ai/api/v1/tools/get_jobs \
  -d '{"ids": ["<job_id>"], "wait_seconds": 20}'
```

With a [webhook](/api/webhooks) registered, the same result arrives as a POST to your URL:

```json theme={"dark"}
{ "type": "job.succeeded", "data": { "job_id": "…", "kind": "render", "status": "succeeded", "item_id": "…", "output_url": "…" } }
```

## One call over many items

The CLI is the same API from a shell, and `--json` returns the full envelope. A read tool also answers `GET` with query parameters.

```bash theme={"dark"}
# every image in a folder, 30 per page
curl "https://eversince.ai/api/v1/tools/search_library?folder=campaigns/july&type=image&limit=30"

# tag them, 25 per call
eversince run search_library '{"folder": "campaigns/july", "type": "image", "limit": 25}' --json \
  | jq -c '{updates: [.data.items[] | {ref: .ref, add_tags: ["july-campaign"]}]}' \
  | eversince run update_items -
```

`update_items` applies item by item. A failure on one item is reported beside the results of the rest, and `set` names what changed on each. A page's `next_cursor`, passed back with the same filters, continues the list.

## A charged call, retried

A generation is charged when it is dispatched, so the idempotency key is what makes a retry safe.

```bash theme={"dark"}
KEY=$(uuidgen)
curl -X POST https://eversince.ai/api/v1/tools/generate_image \
  -d "{\"type\": \"text-to-image\", \"prompt\": \"a ceramic mug on a marble counter, morning light\", \"idempotency_key\": \"$KEY\"}"
```

A `503 unavailable` or a dropped connection is retried with the same body and the same key. The answer is the job already dispatched, and nothing is charged twice. A `402 insufficient_credits` is not retried. `get_balance` says what is left and where more can be added, and `get_checkout_link` returns a link where the user pays.

```bash theme={"dark"}
curl -X POST https://eversince.ai/api/v1/tools/get_jobs -d '{"ids": ["<job_id>"], "wait_seconds": 20}'
# a finished generation carries the item's id, its url, and cost_credits
```

`estimate_cost` quotes the same call before it runs, free, from the same rates.