{"openapi":"3.1.0","info":{"title":"VideoToText API","version":"1.0.0","description":"Submit audio/video and retrieve transcripts programmatically. Authenticate with an API key (`Authorization: Bearer vtt_…`). Transcription is asynchronous: create a job, then poll its status or receive a webhook on completion."},"servers":[{"url":"https://www.transcribevideototext.com/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/uploads":{"post":{"operationId":"createUpload","summary":"Create a signed upload URL","description":"Returns a short-lived signed URL. PUT your file bytes to it, then create a transcription with the returned `path` as `storagePath`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadRequest"}}}},"responses":{"200":{"description":"Signed upload URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions":{"post":{"operationId":"createTranscription","summary":"Create a transcription","description":"Submit by `storagePath` (from /uploads) or by a public `url` that we fetch directly. Returns immediately with a job id; the job runs asynchronously. Send an optional `Idempotency-Key` header so a retried call returns the same job instead of duplicating it.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Dedupes retried create calls per key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTranscriptionRequest"}}}},"responses":{"200":{"description":"Job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedTranscription"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listTranscriptions","summary":"List transcriptions","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"perPage","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"A page of transcriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionList"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions/{id}":{"get":{"operationId":"getTranscription","summary":"Get a transcription","description":"Returns the full result once `status` is `completed`. `locked` is true when the result exceeds the account's available minutes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The transcription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcription"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTranscription","summary":"Delete a transcription","description":"Deletes the transcription; cancels and refunds it if still in progress.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"vtt_…","description":"An API key from Settings → API. Send as `Authorization: Bearer vtt_…`."}},"schemas":{"CreateUploadRequest":{"type":"object","required":["fileName","contentType"],"properties":{"fileName":{"type":"string","minLength":1,"maxLength":255},"contentType":{"type":"string","minLength":1,"maxLength":150,"example":"audio/mpeg"}}},"CreateUploadResponse":{"type":"object","properties":{"path":{"type":"string","description":"Use as `storagePath` when creating the transcription."},"signedUrl":{"type":"string","description":"PUT the file bytes here (expires in 1 hour)."}}},"CreateTranscriptionRequest":{"type":"object","description":"Provide exactly one of `storagePath` or `url`.","properties":{"storagePath":{"type":"string","maxLength":500,"description":"Path from POST /uploads."},"url":{"type":"string","format":"uri","maxLength":2000,"description":"Public https URL we fetch directly."},"fileName":{"type":"string","maxLength":255},"fileSizeBytes":{"type":"integer","minimum":1},"mediaType":{"type":"string","maxLength":150},"language":{"type":"string","maxLength":20,"description":"ISO code or `auto` (default).","example":"auto"},"diarize":{"type":"boolean","description":"Separate speakers."}}},"CreatedTranscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]}}},"Segment":{"type":"object","properties":{"start":{"type":"integer","description":"Start time in ms."},"end":{"type":"integer","description":"End time in ms."},"text":{"type":"string"},"speaker":{"type":"string","nullable":true}}},"Transcription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"locked":{"type":"boolean","description":"True when the result exceeds available minutes (preview only)."},"language":{"type":"string","nullable":true},"durationSeconds":{"type":"integer","nullable":true},"fileName":{"type":"string"},"mediaType":{"type":"string","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"audioUrl":{"type":"string","nullable":true,"description":"Signed playback URL (upload jobs only)."},"isPublic":{"type":"boolean"},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"TranscriptionListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"durationSeconds":{"type":"integer","nullable":true},"language":{"type":"string","nullable":true},"mediaType":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"TranscriptionList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptionListItem"}},"total":{"type":"integer"}}},"Success":{"type":"object","properties":{"success":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","payment_required","conflict","invalid_request","rate_limited","internal_error"]},"message":{"type":"string"}}}}}}}}