KIKUAI

Developers / Automatic Subtitles

One API job from video to SRT and MP4.

Upload first, inspect a trusted duration quote, then explicitly approve the Kiku Credits charge. Transcription starts only after that approval.

Create API key OpenAPI 3.1

API keys are server-side credentials. Never place one in browser or mobile-app source code.

Request flow

Quote before charge. One idempotent start.

01

Create a private job

Send an account-owned API key from your server. The response contains a short-lived upload URL and authorization value. Protected Words are optional spelling guidance.

curl https://kikuai.dev/v1/auto-subtitles/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"protected_words":[]}'

02

Upload the video directly

POST the binary file to job.upload.url with job.upload.authorization. The Hetzner worker validates the media and measures duration; transcription does not start yet.

curl -X POST "$UPLOAD_URL" \
  -H "Authorization: $UPLOAD_AUTH" \
  -H "Content-Type: video/mp4" \
  --data-binary @video.mp4

03

Read and accept the exact quote

GET the job until its status is awaiting_payment. Copy job.credits_required into expected_credits so a changed quote can never be charged silently.

curl https://kikuai.dev/v1/auto-subtitles/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://kikuai.dev/v1/auto-subtitles/jobs/JOB_ID/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"expected_credits":40}'

04

Poll, review, and download

Poll no faster than job.poll_after_seconds until complete. Download the MP4 and SRT from job.downloads using the returned authorization header. All job files expire within 24 hours.

curl "$VIDEO_URL" -H "Authorization: $DOWNLOAD_AUTH" -o captioned.mp4
curl "$SRT_URL" -H "Authorization: $DOWNLOAD_AUTH" -o subtitles.srt

Service boundary

Price20 Kiku Credits per started minute; maximum 500 credits per video
Free APINo free transcription allowance; upload validation and the duration quote do not spend credits
InputOne video up to 30 minutes and 500 MB
LanguagesAutomatic detection across 99+ transcription languages; accuracy varies
OutputTimed SRT and captioned MP4
RetentionSource, audio, transcript artifacts, SRT, and MP4 are deleted within 24 hours
Rate limit20 new quote jobs per account per day; follow the returned polling interval

Errors you should handle

401API key is missing, invalid, revoked, or belongs to an inactive account.
402The shared Kiku Credits balance is too low for this action.
409The upload quote is not ready, changed, or the paid authorization should be retried.
410The private job and its artifacts have expired.
424The private media worker is temporarily unavailable.
429The daily quote-job limit has been reached.

Start requests are safe to retry with the same job ID and expected credit amount. A duplicate start does not spend credits twice. If a charged job cannot produce downloadable output, retry that same job first, then contact support.

Ready to wire the first job?

Create up to three revocable keys in the shared KikuAI account.

Open account