{"openapi":"3.1.0","info":{"title":"Video Subtitle & Transcript API","version":"1.0.0","description":"Transcribe video or audio and get SRT, VTT and ASS subtitles with Japanese and English line-breaking, a filler/silence cut list, and burned-in captions. Jobs are asynchronous: POST /v1/jobs returns 202, poll GET /v1/jobs/{id}. Processing failures are returned as HTTP 200 with status \"failed\" and are not billed. Billing (Minutes) is counted once, on the first GET that returns a completed result."},"servers":[{"url":"https://caption.yosuga.dev"}],"tags":[{"name":"Jobs"},{"name":"Captions"},{"name":"Meta"}],"paths":{"/v1/jobs":{"post":{"tags":["Jobs"],"operationId":"createJob","summary":"Create a transcription job from a URL or an upload_id","description":"Returns 202 immediately. Exactly one of source_url (public http/https URL, up to 2 GB) or upload_id (from POST /v1/uploads) is required. Plan limits per file: BASIC 30 min, PRO 120 min, ULTRA 240 min, MEGA 480 min.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"},"example":{"source_url":"https://caption.yosuga.dev/samples/video/sample-30s.mp4","language":"ja","mode":"clean","vocabulary":["Timothea"],"outputs":["json","srt","vtt","ass"],"orientation":"auto","caption_style":{"preset":"clean_outline","position":"bottom","max_lines":2},"cut_candidates":true,"burn_in":false}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"},"example":{"id":"job_PisXfKDcuOz1K7UnyUFKkc","status":"queued","poll_url":"/v1/jobs/job_PisXfKDcuOz1K7UnyUFKkc"}}}},"400":{"description":"Validation error or blocked URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"upload_id unknown or already used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/upload":{"post":{"tags":["Jobs"],"operationId":"createJobFromUpload","summary":"Upload a file (up to 20 MB) and create a job","description":"multipart/form-data with the media file and an optional JSON string of options (same fields as POST /v1/jobs without source_url).","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"options":{"type":"string","description":"JSON string of JobOptions","example":"{\"language\":\"ja\",\"outputs\":[\"json\",\"srt\"]}"}},"required":["file"]}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File larger than 20 MB; use POST /v1/uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/uploads":{"post":{"tags":["Jobs"],"operationId":"createUpload","summary":"Get a signed PUT URL for files up to 2 GB","description":"PUT the file to put_url with the returned headers within 1 hour, then create a job with upload_id. Each upload_id can be used once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequest"},"example":{"content_type":"video/mp4","size_bytes":734003200}}}},"responses":{"200":{"description":"Signed upload ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadTicket"},"example":{"upload_id":"upl_LTnnGqP4gthnfTRWW5Eiqn","put_url":"https://…signed","method":"PUT","headers":{"Content-Type":"video/mp4","Content-Length":"734003200"},"expires_in":3600}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["Jobs"],"operationId":"getJob","summary":"Get job status, progress and results","description":"Poll every 10-30 seconds. When status is completed, files contains signed URLs valid for 1 hour (re-issued on every call). The first response that returns a completed result carries X-RapidAPI-Billing: Minutes=N (N = ceil(duration_sec / 60)); later calls do not. Failed jobs return 200 with status failed and error, and are not billed. After 7 days the job returns 410.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"job_PisXfKDcuOz1K7UnyUFKkc"}],"responses":{"200":{"description":"Job","headers":{"X-RapidAPI-Billing":{"description":"Present only on the first completed read. Value: Minutes=N","schema":{"type":"string","example":"Minutes=11"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"},"example":{"id":"job_PisXfKDcuOz1K7UnyUFKkc","status":"completed","phase":"done","progress":100,"created_at":"2026-09-08T06:30:43.000Z","started_at":"2026-09-08T06:30:52.000Z","completed_at":"2026-09-08T06:31:05.000Z","expires_at":"2026-09-15T06:31:05.000Z","meta":{"duration_sec":20.034,"language_detected":"ja","engine":"gemini-3.5-transcribe","backend":"vertex","orientation":"landscape","preset":"clean_outline"},"transcript":{"segments":[{"start":0.3,"end":20,"text":"で単純にそのまま…","words":[{"word":"で","start":0.3,"end":0.4}]}]},"captions":{"cues":[{"index":1,"start":0.3,"end":2.9,"text":"で単純にそのまま","words":[]}]},"cut_candidates":[{"type":"filler","start":24.4,"end":25.2,"text":"えーと","confidence":0.92}],"warnings":[],"files":{"transcript":"https://…signed","srt":"https://…signed","vtt":"https://…signed"},"billing":{"minutes":1}}}}},"404":{"description":"Not found or not your job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired (7 days after completion)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/captions/format":{"post":{"tags":["Captions"],"operationId":"formatCaptions","summary":"Wrap timestamped text into cues and return SRT, VTT and ASS","description":"Synchronous. Uses the same line-breaking rules and presets as jobs. Send segments (with optional words), or words only, or two tracks (primary + secondary translation) for bilingual output. ASS applies the preset; SRT/VTT get the wrapping only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatRequest"},"example":{"language":"ja","orientation":"landscape","style":{"preset":"clean_outline"},"segments":[{"start":0,"end":4.15,"text":"設定画面を開いてから、右上のボタンを押してください。","words":[{"word":"設定","start":0,"end":0.4},{"word":"画面","start":0.4,"end":0.8}]}]}}}},"responses":{"200":{"description":"Formatted captions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormatResponse"},"example":{"cues":[{"index":1,"start":0,"end":1.85,"text":"設定画面を開いてから、","words":[]}],"srt":"1\n00:00:00,000 --> 00:00:01,850\n設定画面を開いてから、\n","vtt":"WEBVTT\n\n1\n00:00:00.000 --> 00:00:01.850\n設定画面を開いてから、\n","ass":"[Script Info]\nScriptType: v4.00+\n…","meta":{"preset":"clean_outline","language":"ja","orientation":"landscape","line_chars":24,"max_lines":2}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/caption-presets":{"get":{"tags":["Captions"],"operationId":"listCaptionPresets","summary":"List the caption presets with preview images","description":"All 12 presets are available on every plan. Overridable per job: position, margin_ratio, font_size_scale, line_chars, max_lines, colors.","parameters":[{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"Only affects ordering (ja puts manual_ud first)."}],"responses":{"200":{"description":"Presets","content":{"application/json":{"schema":{"type":"object","properties":{"presets":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}}}}}}},"/v1/captions/preview":{"post":{"tags":["Captions"],"operationId":"previewCaptionStyle","summary":"Render a 5-second MP4 or a PNG of a preset with your text","description":"Synchronous (up to 30 s). BASIC: 20 previews per day. On timeout returns 200 with error.code preview_timeout.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewRequest"},"example":{"preset":"karaoke_highlight","language":"en","orientation":"portrait","text":"Open the settings page","format":"png"}}}},"responses":{"200":{"description":"PNG or MP4 bytes, or a JSON error (preview_timeout / preview_limit / plan_required)","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/languages":{"get":{"tags":["Meta"],"operationId":"listLanguages","summary":"Supported languages with tier and caption profile","responses":{"200":{"description":"Languages","content":{"application/json":{"schema":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/Language"}}}}}}}}}},"/v1/health":{"get":{"tags":["Meta"],"operationId":"health","summary":"Health check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}},"example":{"ok":true}}}}}}}},"components":{"schemas":{"JobInput":{"type":"object","properties":{"source_url":{"type":"string","format":"uri"},"upload_id":{"type":"string","pattern":"^upl_[0-9A-Za-z]{22}$"},"language":{"default":"auto","type":"string","pattern":"^(auto|[a-z]{2,3})$"},"mode":{"default":"clean","type":"string","enum":["clean","verbatim","both"]},"vocabulary":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"outputs":{"default":["json","srt","vtt"],"minItems":1,"type":"array","items":{"type":"string","enum":["json","srt","vtt","ass"]}},"orientation":{"default":"auto","type":"string","enum":["auto","landscape","portrait"]},"caption_style":{"type":"object","properties":{"preset":{"default":"clean_outline","type":"string","minLength":1,"maxLength":64},"position":{"type":"string","enum":["bottom","center","top"]},"margin_ratio":{"type":"number","minimum":0,"maximum":0.5},"font_size_scale":{"type":"number","minimum":0.8,"maximum":1.3},"line_chars":{"nullable":true,"type":"integer","minimum":4,"maximum":80},"max_lines":{"type":"integer","minimum":1,"maximum":3},"colors":{"type":"object","additionalProperties":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"required":["text","outline","band","highlight"]},"custom_ass_style":{"type":"string","maxLength":2000},"title":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false},"cut_candidates":{"default":false,"type":"boolean"},"burn_in":{"default":false,"type":"boolean"},"callback_url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":{}}},"additionalProperties":false},"JobOptions":{"type":"object","properties":{"language":{"default":"auto","type":"string","pattern":"^(auto|[a-z]{2,3})$"},"mode":{"default":"clean","type":"string","enum":["clean","verbatim","both"]},"vocabulary":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"outputs":{"default":["json","srt","vtt"],"minItems":1,"type":"array","items":{"type":"string","enum":["json","srt","vtt","ass"]}},"orientation":{"default":"auto","type":"string","enum":["auto","landscape","portrait"]},"caption_style":{"type":"object","properties":{"preset":{"default":"clean_outline","type":"string","minLength":1,"maxLength":64},"position":{"type":"string","enum":["bottom","center","top"]},"margin_ratio":{"type":"number","minimum":0,"maximum":0.5},"font_size_scale":{"type":"number","minimum":0.8,"maximum":1.3},"line_chars":{"nullable":true,"type":"integer","minimum":4,"maximum":80},"max_lines":{"type":"integer","minimum":1,"maximum":3},"colors":{"type":"object","additionalProperties":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"required":["text","outline","band","highlight"]},"custom_ass_style":{"type":"string","maxLength":2000},"title":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false},"cut_candidates":{"default":false,"type":"boolean"},"burn_in":{"default":false,"type":"boolean"},"callback_url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":{}}},"additionalProperties":false},"CaptionStyle":{"type":"object","properties":{"preset":{"default":"clean_outline","type":"string","minLength":1,"maxLength":64},"position":{"type":"string","enum":["bottom","center","top"]},"margin_ratio":{"type":"number","minimum":0,"maximum":0.5},"font_size_scale":{"type":"number","minimum":0.8,"maximum":1.3},"line_chars":{"nullable":true,"type":"integer","minimum":4,"maximum":80},"max_lines":{"type":"integer","minimum":1,"maximum":3},"colors":{"type":"object","additionalProperties":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"required":["text","outline","band","highlight"]},"custom_ass_style":{"type":"string","maxLength":2000},"title":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false},"UploadRequest":{"type":"object","properties":{"content_type":{"type":"string","minLength":3,"maxLength":128},"size_bytes":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":2147483648}},"required":["content_type","size_bytes"],"additionalProperties":false},"FormatRequest":{"type":"object","properties":{"language":{"default":"ja","type":"string","pattern":"^[a-z]{2,3}$"},"orientation":{"default":"landscape","type":"string","enum":["landscape","portrait"]},"style":{"type":"object","properties":{"preset":{"default":"clean_outline","type":"string","minLength":1,"maxLength":64},"position":{"type":"string","enum":["bottom","center","top"]},"margin_ratio":{"type":"number","minimum":0,"maximum":0.5},"font_size_scale":{"type":"number","minimum":0.8,"maximum":1.3},"line_chars":{"nullable":true,"type":"integer","minimum":4,"maximum":80},"max_lines":{"type":"integer","minimum":1,"maximum":3},"colors":{"type":"object","additionalProperties":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"required":["text","outline","band","highlight"]},"custom_ass_style":{"type":"string","maxLength":2000},"title":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false},"segments":{"maxItems":5000,"type":"array","items":{"type":"object","properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"text":{"default":"","type":"string"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}},"required":["word","start","end"],"additionalProperties":false}}},"required":["start","end"],"additionalProperties":false}},"words":{"maxItems":50000,"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}},"required":["word","start","end"],"additionalProperties":false}},"tracks":{"maxItems":2,"type":"array","items":{"type":"object","properties":{"lang":{"type":"string","pattern":"^[a-z]{2,3}$"},"role":{"type":"string","enum":["primary","secondary"]},"segments":{"minItems":1,"type":"array","items":{"type":"object","properties":{"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0},"text":{"default":"","type":"string"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number","minimum":0},"end":{"type":"number","minimum":0}},"required":["word","start","end"],"additionalProperties":false}}},"required":["start","end"],"additionalProperties":false}}},"required":["lang","role","segments"],"additionalProperties":false}},"title":{"type":"string","maxLength":80},"keywords":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}}},"additionalProperties":false},"PreviewRequest":{"type":"object","properties":{"preset":{"type":"string","enum":["clean_outline","manual_ud","clean_shadow","band_dark","box_white","keyword_color","karaoke_highlight","bold_center","word_pop","double_outline","title_top","bilingual_stack"]},"language":{"type":"string","default":"en"},"orientation":{"type":"string","enum":["landscape","portrait"],"default":"landscape"},"text":{"type":"string","maxLength":200},"style":{"$ref":"#/components/schemas/CaptionStyle"},"format":{"type":"string","enum":["png","mp4"],"default":"png"}},"required":["preset"]},"JobAccepted":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","completed"]},"poll_url":{"type":"string"},"reused":{"type":"boolean"}},"required":["id","status","poll_url"]},"UploadTicket":{"type":"object","properties":{"upload_id":{"type":"string"},"put_url":{"type":"string","format":"uri"},"method":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"r2_key":{"type":"string"},"expires_in":{"type":"integer"},"max_bytes":{"type":"integer"}}},"Job":{"type":"object","properties":{"id":{"type":"string","example":"job_PisXfKDcuOz1K7UnyUFKkc"},"status":{"type":"string","enum":["queued","processing","completed","failed","expired"]},"phase":{"type":"string","nullable":true,"enum":["fetching","probing","transcribing","detecting_cuts","formatting","rendering","uploading","queued","done",null]},"progress":{"type":"integer","minimum":0,"maximum":100},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Result files are deleted after this time (7 days after completion)."},"meta":{"type":"object","properties":{"duration_sec":{"type":"number"},"language_detected":{"type":"string","nullable":true},"engine":{"type":"string"},"backend":{"type":"string"},"orientation":{"type":"string"},"preset":{"type":"string"},"preset_fallback":{"type":"object","properties":{"requested":{"type":"string"},"used":{"type":"string"}}}}},"transcript":{"type":"object","properties":{"segments":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"}},"required":["word","start","end"]}}}}}}},"transcript_verbatim":{"type":"object","description":"Present when mode is both."},"captions":{"type":"object","properties":{"cues":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string","description":"Line breaks are \\n"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"}},"required":["word","start","end"]}}},"required":["index","start","end","text"]}}}},"cut_candidates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["filler","silence","noise"]},"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"},"confidence":{"type":"number"}}}},"warnings":{"type":"array","items":{"type":"string"}},"files":{"type":"object","additionalProperties":{"type":"string","format":"uri"},"description":"Signed URLs valid for 1 hour, re-issued on every GET. Keys: transcript, srt, vtt, ass, burned_video."},"billing":{"type":"object","properties":{"minutes":{"type":"integer"}}},"error":{"type":"object","properties":{"code":{"type":"string","enum":["fetch_failed","unsupported_media","duration_limit","no_audio","transcribe_failed","render_failed","plan_required","internal"]},"message":{"type":"string"},"hint":{"type":"string"}}}},"required":["id","status","progress","created_at"]},"Cue":{"type":"object","properties":{"index":{"type":"integer"},"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string","description":"Line breaks are \\n"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"}},"required":["word","start","end"]}}},"required":["index","start","end","text"]},"FormatResponse":{"type":"object","properties":{"cues":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string","description":"Line breaks are \\n"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"}},"required":["word","start","end"]}}},"required":["index","start","end","text"]}},"tracks":{"type":"object","properties":{"secondary":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string","description":"Line breaks are \\n"},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"}},"required":["word","start","end"]}}},"required":["index","start","end","text"]}}}},"srt":{"type":"string"},"vtt":{"type":"string"},"ass":{"type":"string"},"meta":{"type":"object"}},"required":["cues","srt","vtt","ass","meta"]},"Preset":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"use_cases":{"type":"array","items":{"type":"string"}},"kind":{"type":"string"},"unit":{"type":"string"},"motion":{"type":"string"},"available_from":{"type":"string"},"supported_languages":{"type":"array","items":{"type":"string"}},"overridable":{"type":"array","items":{"type":"string"}},"preview":{"type":"object","properties":{"landscape":{"type":"string","format":"uri"},"portrait":{"type":"string","format":"uri"}}}}},"Language":{"type":"object","properties":{"code":{"type":"string"},"tier":{"type":"integer"},"beta":{"type":"boolean"},"wrap":{"type":"string"},"name":{"type":"string"},"font":{"type":"string"},"line_chars":{"type":"object","properties":{"landscape":{"type":"integer"},"portrait":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}},"required":["code","message"]}},"required":["error"]}}}}