# Quickstart

URL: https://neattrim.com/docs/quickstart

Make your first Neattrim API call, then run a job on a sample file and download the result.

You need an account and an API key. Every account can use the API, free accounts included, within its allowance. A free account gets 1 hour of subtitle time and 5 minutes of voice and AI time each month, and API calls draw from the same allowance as the website.

## 1. Get a key

[Sign in and create a key](https://neattrim.com/signin?next=%2Faccount%2Fkeys), then put it in an environment variable. Every example in these docs reads it from there.

```bash
export NEATTRIM_API_KEY="km_live_..."
```

A key that starts with `km_live_` runs real jobs. An account can hold 10 live keys. Keep the key on a server, never in a web page.

## 2. Make your first call

This call estimates what compressing a short video would draw from your allowance. It needs no file and draws nothing.

```bash
curl -X POST https://api.neattrim.com/v1/estimate \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "compress_video", "duration_seconds": 6}'
```

The answer shows the subtitle time and the voice and AI time the job would draw and whether it fits your allowance. `GET /v1/capabilities` lists the tools, the per-file limits for your plan and how much allowance is left.

## 3. Upload a sample file

A tool reads an uploaded file. Download the 6-second sample clip, then upload it in three calls: create the upload, send the bytes to the address it returns, and complete it. Uploads draw nothing.

```bash
curl -sO https://neattrim.com/samples/sample.mp4
UPLOAD=$(curl -s -X POST https://api.neattrim.com/v1/uploads \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"file_name\": \"sample.mp4\", \"size_bytes\": $(wc -c < sample.mp4), \"mime_type\": \"video/mp4\"}")
curl -s -X PUT --upload-file sample.mp4 -H "Content-Type: video/mp4" "$(echo "$UPLOAD" | jq -r .put_url)"
curl -s -X POST "https://api.neattrim.com/v1/uploads/$(echo "$UPLOAD" | jq -r .upload_id)/complete" \
  -H "Authorization: Bearer $NEATTRIM_API_KEY"
export VIDEO_FILE_ID=$(echo "$UPLOAD" | jq -r .file_id)
```

`jq` reads fields from the JSON answers; without it, copy `put_url`, `upload_id` and `file_id` by hand.

## 4. Run a job

Every tool is one `POST` to `/v1/tools/<tool>`. This one reports the clip's length, size and streams, and draws nothing.

```bash
JOB_ID=$(curl -s -X POST https://api.neattrim.com/v1/tools/probe_media \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"$VIDEO_FILE_ID\"}" | jq -r .job_id)
curl -s "https://api.neattrim.com/v1/jobs/$JOB_ID?wait=45" \
  -H "Authorization: Bearer $NEATTRIM_API_KEY"
```

The first call answers `202` with a job. The second holds the request open for up to 45 seconds and answers as soon as the job ends. When `status` is `completed`, the job holds the result: `text` for a report like this one, and `outputs` with a `download_url` for each file a tool makes. To be told instead of waiting, register a [webhook](https://neattrim.com/docs/webhooks).

## 5. Make a file

The same two calls run any tool. This one makes the clip smaller and draws about 6 seconds of voice and AI time.

```bash
JOB_ID=$(curl -s -X POST https://api.neattrim.com/v1/tools/compress_video \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"$VIDEO_FILE_ID\", \"quality\": \"smaller\"}" | jq -r .job_id)
curl -s "https://api.neattrim.com/v1/jobs/$JOB_ID?wait=45" \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" | jq -r '.outputs[0].download_url'
```

Open the printed link to download the result. The examples on the tool pages read the same variables: `VIDEO_FILE_ID`, `AUDIO_FILE_ID`, `IMAGE_FILE_ID`, `SUBTITLES_FILE_ID` and `TRANSLATION_FILE_ID` for uploaded copies of the sample files below (upload each the same way, with its own name, size and type).

## Sample files

These files were made for these docs (a test pattern with a synthetic voice) and are free to use for anything. Every example in the docs uses them.

| File | What it is |
| --- | --- |
| [https://neattrim.com/samples/sample.mp4](https://neattrim.com/samples/sample.mp4) | 6-second MP4 video, 640x360, with speech |
| [https://neattrim.com/samples/sample.mp3](https://neattrim.com/samples/sample.mp3) | The same speech as MP3 |
| [https://neattrim.com/samples/sample.jpg](https://neattrim.com/samples/sample.jpg) | One frame as JPEG |
| [https://neattrim.com/samples/sample.srt](https://neattrim.com/samples/sample.srt) | The speech as SRT captions |
| [https://neattrim.com/samples/sample.es.srt](https://neattrim.com/samples/sample.es.srt) | The captions in Spanish |

## Use a client library

The [TypeScript SDK, the Python SDK and the command line tool](https://neattrim.com/docs/sdks) wrap uploads, polling and webhook checks. They are not on npm or PyPI yet; until the first client release, use the REST API as above.

## Next steps

- [Authentication](https://neattrim.com/docs/authentication): keys, scopes and OAuth.
- [Files](https://neattrim.com/docs/files): upload a file from your computer.
- [Usage and limits](https://neattrim.com/docs/usage-and-limits): what a job costs and what happens at the limit.
- [API reference](https://neattrim.com/docs/api): every endpoint, with examples.
