Developers

Spoolfield API

Run Spoolfield from your own code: turn long videos into Shorts, burn in captions, get transcripts and convert files. The API uses the same credits, prices and queue as the Spoolfield web app.

1. Get an API key

  1. Sign in on your account page. Every account can make keys, including free accounts.
  2. Under API keys, give the key a name (for example “n8n” or “my server”) and press Create key.
  3. Copy the key straight away. It starts with sfk_ and is shown only once: we keep a scrambled copy, so we can’t show it again.

You can have up to 5 keys. Delete a key on the account page and it stops working within a few seconds.

Keep keys on your server. Anyone with your key can spend your credits. Don’t put it in a web page, a mobile app or a public repository. The API doesn’t allow calls from web browsers on other sites, so a key in a web page wouldn’t work anyway.

2. Sending requests

The base address is https://spoolfield.com/api/v1. Send your key in the Authorization header. If a tool already uses that header for something else, send it as X-Api-Key instead.

curl https://spoolfield.com/api/v1/account \
  -H "Authorization: Bearer sfk_your_key"

Requests and replies are JSON, except uploads (raw bytes) and result files (the file itself). Times are in seconds.

3. Quick start: three Shorts from a YouTube video

Check the price

curl https://spoolfield.com/api/v1/estimate \
  -H "Authorization: Bearer sfk_your_key" -H "Content-Type: application/json" \
  -d '{"tool": "short",
       "params": {"topic": "pricing", "count": 3, "seconds": 30, "style": "pop"},
       "source": {"link": "https://www.youtube.com/watch?v=..."}}'

The reply has credits (the most this job can cost), available (your credits) and enough.

Start the job

Send the same request to /jobs with max_credits. If the price is now higher than max_credits, the job doesn’t start and you get price_changed, so you’re never charged more than you agreed to.

curl https://spoolfield.com/api/v1/jobs \
  -H "Authorization: Bearer sfk_your_key" -H "Content-Type: application/json" \
  -d '{"tool": "short", "max_credits": 13,
       "params": {"topic": "pricing", "count": 3, "seconds": 30, "style": "pop"},
       "source": {"link": "https://www.youtube.com/watch?v=..."}}'

Wait for it, then download

Ask for the job every 5–10 seconds until state is done, failed or canceled. Each file in outputs has a url; download it with the same header.

curl https://spoolfield.com/api/v1/jobs/JOB_ID -H "Authorization: Bearer sfk_your_key"

curl -L -o short.mp4 "OUTPUT_URL" -H "Authorization: Bearer sfk_your_key"

4. Endpoints

GET /account
Your plan, the credits you can use now, and your plan’s limits (limits.height, limits.keep_days).
POST /links
{"url"} → the video’s title, length and site. Free.
POST /estimate
{"tool", "params", "source"} → the price in credits. Nothing starts.
POST /jobs
{"tool", "params", "source", "max_credits"} → the new job. Its credits are held until it finishes.
GET /jobs
Your jobs whose files haven’t expired yet.
GET /jobs/{id}
state (queued, running, done, failed, canceled), percent, queue_position, outputs, credits_used, error and expires_at.
POST /jobs/{id}/cancel
Stops the job and gives the held credits back.
DELETE /jobs/{id}
Deletes the job’s files from our servers now, instead of when they expire.
GET /jobs/{id}/files/{name}
Downloads a result file.
POST /uploads
{"name", "size"} → an upload id and the chunk size. See section 6.
POST /trending
{"topic", "period", "short_only"} → popular YouTube videos about a topic (period: today, week, month or year). Free.

5. Tools and their settings

Every setting is optional unless it says otherwise. Settings that don’t apply to a tool are ignored; values we can’t use return an error that says what to fix.

short
Vertical clips for Shorts, Reels and TikTok. Give neither topic nor clips and Spoolfield picks the moments most likely to hold attention, best first, each output with a score (0–100) and a reason; or give a topic and Spoolfield finds the moments about it (count 1–10, default 3; seconds 10–90, default 30); or give the times yourself in clips: [{"start": 12, "end": 41}], each up to 180 seconds. Also aspect (9:16, 1:1, 4:5, 16:9), fill (crop, blur, or speaker to move the crop with the person talking), caption style (pop, box, word, clean or none), position (bottom, middle, top) and lang.
captions
Burns word-by-word captions into the video. style, position, start, end, lang, and aspect / fill to change the shape at the same time.
transcript
The spoken words as a text file, SRT subtitles and JSON. lang (for example en or th) if you know the language.
convert
Changes the format (mp4, mov, mkv, webm, mp3, m4a, wav), cuts to start / end, changes the aspect, or fits the file under max_size_mb.
pack
A source pack for editing: the video, its transcript in two formats, subtitles and still frames. start, end, lang.

The source is either {"link": "https://..."} or {"upload": "up_..."}. Use only videos you have the right to use.

6. Uploading your own files

  1. POST /uploads with the file’s name and size in bytes. You get an id and a chunk size.
  2. Send the file in pieces no bigger than chunk: PUT /uploads/{id}?offset=N with the raw bytes as the body, where N is how many bytes you’ve sent so far. If a piece goes missing you get bad_offset with received, so carry on from there.
  3. POST /uploads/{id}/finish checks the file and returns its length. Then use {"upload": "ID"} as the source.

Videos (MP4, MOV, MKV, WebM, M4V, AVI) and audio (MP3, M4A, WAV, AAC, FLAC, OGG, Opus) only. Free accounts can upload files up to 500 MB, Starter up to 2 GB and Creator up to 5 GB.

7. Credits

8. Errors and limits

Errors come back as JSON with a short error code, an English message, and often a hint about what to do next:

{"error": "price_changed", "message": "The price changed.", "hint": "Check the new price and run again."}

Result files are deleted after your plan’s keep_days (see /account), or sooner if you delete the job.

9. Help

Questions, a bug, or something you’d like the API to do? Email [email protected] with the job ID if you have one. Using the API means you agree to our Terms of Service.