{"openapi":"3.1.0","info":{"title":"Vidixa API","version":"1.0.0","description":"Asynchronous video conversion API. Create a Bearer token in the user account. POST creation endpoints accept an optional Idempotency-Key header."},"servers":[{"url":"https://vidixa.ru"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/usage":{"get":{"summary":"Get plan features and current API quota","x-required-scope":"usage:read","responses":{"200":{"description":"Usage and limits"},"401":{"description":"Missing or invalid Bearer token"}}}},"/api/v1/credits":{"get":{"summary":"Get credit balance and available one-off packages","x-required-scope":"usage:read","responses":{"200":{"description":"Credit balance and packages"},"401":{"description":"Missing or invalid Bearer token"}}}},"/api/v1/jobs":{"post":{"summary":"Create conversion job","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/VideoJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/jobs/{id}":{"get":{"summary":"Get job status","x-required-scope":"jobs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"404":{"description":"Job not found"}}}},"/api/v1/jobs/{id}/download":{"get":{"summary":"Download completed result","x-required-scope":"files:download","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Binary result","content":{"application/octet-stream":{"schema":{"type":"string","contentEncoding":"binary"}}}},"404":{"description":"Result not available"}}}},"/api/v1/jobs/{id}/cancel":{"post":{"summary":"Cancel queued or running job","x-required-scope":"jobs:cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancellation status"},"404":{"description":"Job not found"}}}},"/api/v1/jobs/{id}/reprocess":{"post":{"summary":"Create a new job from a retained source file","x-required-scope":"jobs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/ReprocessJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/batches":{"post":{"summary":"Create batch conversion","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/BatchJob"},"responses":{"202":{"description":"Batch accepted"},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/batches/{id}":{"get":{"summary":"Get batch status","x-required-scope":"jobs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Batch status"},"404":{"description":"Batch not found"}}}},"/api/v1/batches/{id}/download":{"get":{"summary":"Download successful batch results as ZIP","x-required-scope":"files:download","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ZIP archive"},"404":{"description":"Batch result not available"}}}},"/api/v1/merge":{"post":{"summary":"Merge 2–10 videos","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/MergeJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/split":{"post":{"summary":"Split video","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/SplitJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/subtitles":{"post":{"summary":"Burn SRT/ASS/VTT subtitles into video","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/SubtitleJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/watermark":{"post":{"summary":"Overlay image watermark","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/WatermarkJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/frames":{"post":{"summary":"Extract video frames to ZIP","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/FramesJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}},"/api/v1/thumbnail":{"post":{"summary":"Create thumbnail from video","x-required-scope":"jobs:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/ThumbnailJob"},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid input"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Bearer token does not include the required scope"},"409":{"description":"Idempotency-Key conflict"},"429":{"description":"Plan API rate limit exceeded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque token","description":"Token scopes: usage:read, jobs:read, jobs:write, jobs:cancel, files:download. Legacy tokens created before scopes retain all scopes."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-generated key (max 128 chars). Repeating the same request with the same key returns the original response without consuming quota again.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}},"schemas":{"JobAccepted":{"type":"object","required":["id","operation","status","statusUrl"],"properties":{"id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string"},"creditCost":{"type":"integer","minimum":0},"statusUrl":{"type":"string","format":"uri"}}},"JobStatus":{"type":"object","properties":{"id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"queue":{"type":["string","null"]},"priority":{"type":"integer"},"queuePosition":{"type":["integer","null"],"minimum":0},"etaSeconds":{"type":["integer","null"],"minimum":0},"etaConfidence":{"type":"string","enum":["low","medium","high","actual"]},"creditCost":{"type":"integer","minimum":0},"inputSize":{"type":"integer"},"outputSize":{"type":["integer","null"]},"download":{"type":["string","null"],"format":"uri"},"expiresAt":{"type":["string","null"]},"error":{"type":["string","null"]}}}},"requestBodies":{"VideoJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"format":{"type":"string","enum":["mp4","webm","mov","mkv","avi","gif","mp3","aac","wav","flac"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9","copy"],"default":"h264"},"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1},"start":{"type":"integer","minimum":1},"duration":{"type":"integer","minimum":1},"targetSizeMb":{"type":"number","minimum":1},"quality":{"type":"integer","minimum":0,"maximum":51},"speed":{"type":"number","minimum":0.25,"maximum":4},"normalizeAudio":{"type":"boolean"},"mute":{"type":"boolean"}},"required":["file"]}}}},"ReprocessJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["mp4","webm","mov","mkv","avi","gif","mp3","aac","wav","flac"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9","copy"],"default":"h264"},"width":{"type":"integer"},"height":{"type":"integer"},"targetSizeMb":{"type":"number"},"quality":{"type":"integer"}}}}}},"BatchJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"binary"}},"format":{"type":"string","enum":["mp4","webm","mov","mkv","avi","gif","mp3","aac","wav","flac"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9","copy"],"default":"h264"},"width":{"type":"integer"},"height":{"type":"integer"},"fit":{"type":"string","enum":["contain","cover","stretch"],"default":"contain"},"quality":{"type":"integer","minimum":0,"maximum":51}},"required":["files"]}}}},"MergeJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"string","format":"binary"}},"format":{"type":"string","enum":["mp4","webm","mov","mkv"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9"],"default":"h264"}},"required":["files"]}}}},"SplitJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"format":{"type":"string","enum":["mp4","webm","mov","mkv"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9","copy"],"default":"h264"},"splitMode":{"type":"string","enum":["duration","parts","size"],"default":"duration"},"segmentDuration":{"type":"integer"},"partsCount":{"type":"integer"},"partSizeMb":{"type":"number"},"quality":{"type":"integer","minimum":0,"maximum":51}},"required":["file"]}}}},"SubtitleJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"subtitle":{"type":"string","format":"binary"},"format":{"type":"string","enum":["mp4","webm","mov","mkv"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9"],"default":"h264"},"quality":{"type":"integer","minimum":0,"maximum":51},"fontSize":{"type":"integer","minimum":10,"maximum":96},"marginV":{"type":"integer","minimum":0,"maximum":400}},"required":["file","subtitle"]}}}},"WatermarkJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"watermark":{"type":"string","format":"binary"},"format":{"type":"string","enum":["mp4","webm","mov","mkv"],"default":"mp4"},"codec":{"type":"string","enum":["h264","h265","vp9"],"default":"h264"},"quality":{"type":"integer","minimum":0,"maximum":51},"position":{"type":"string","enum":["top-left","top-right","bottom-left","bottom-right","center"],"default":"bottom-right"},"opacity":{"type":"number","minimum":0.050000000000000003,"maximum":1},"widthPercent":{"type":"integer","minimum":5,"maximum":80},"margin":{"type":"integer","minimum":0,"maximum":400}},"required":["file","watermark"]}}}},"FramesJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"mode":{"type":"string","enum":["interval","count"],"default":"interval"},"intervalSeconds":{"type":"integer","minimum":1},"count":{"type":"integer","maximum":200},"imageFormat":{"type":"string","enum":["jpg","png"],"default":"jpg"},"width":{"type":"integer"}},"required":["file"]}}}},"ThumbnailJob":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"timestamp":{"type":"number","minimum":0},"imageFormat":{"type":"string","enum":["jpg","png"],"default":"jpg"},"width":{"type":"integer"}},"required":["file"]}}}}}}}