Skip to content
Neattrim

Quickstart

View as Markdown · Open in Claude Desktop

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, then put it in an environment variable. Every example in these docs reads it from there.

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.

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.

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.

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.

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.

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 6-second MP4 video, 640x360, with speech
https://neattrim.com/samples/sample.mp3 The same speech as MP3
https://neattrim.com/samples/sample.jpg One frame as JPEG
https://neattrim.com/samples/sample.srt The speech as SRT captions
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 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