{"openapi":"3.1.0","info":{"title":"KinoPipe API","version":"0.1.0","description":"A simple, agent-ready video editing API."},"servers":[{"url":"https://kinopipe.com"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/jobs":{"post":{"operationId":"createVideoEdit","summary":"Create a video editing job","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRequest"}}}},"responses":{"200":{"description":"An existing idempotent job was returned."},"202":{"description":"The edit was accepted for asynchronous processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedJob"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"503":{"$ref":"#/components/responses/QueueUnavailable"}}}},"/api/v1/jobs/{jobId}":{"get":{"operationId":"getVideoEdit","summary":"Read a video editing job","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current job state, including the output when it has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The job was not found for this account."}}}},"/api/v1/tools/{slug}":{"post":{"operationId":"runVideoTool","summary":"Run a ready-made video editing tool","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","enum":["compress-video","video-to-mp4","resize-video","extract-audio","video-thumbnail-generator","add-subtitles-to-video","trim-video","optimize-video-for-web"]}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolRequest"}}}},"responses":{"200":{"description":"An existing idempotent tool run was returned."},"202":{"description":"The tool run was accepted for asynchronous processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedJob"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"404":{"description":"The requested tool is not executable."},"503":{"$ref":"#/components/responses/QueueUnavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A KinoPipe API key beginning with kp_live_."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Reuse a stable value when retrying the same edit.","schema":{"type":"string","maxLength":160}}},"schemas":{"JobRequest":{"type":"object","required":["input"],"properties":{"name":{"type":"string","maxLength":120,"default":"Untitled job"},"input":{"$ref":"#/components/schemas/MediaInput"},"operations":{"type":"array","maxItems":12,"items":{"oneOf":[{"$ref":"#/components/schemas/TrimOperation"},{"$ref":"#/components/schemas/ResizeOperation"},{"$ref":"#/components/schemas/ThumbnailOperation"},{"$ref":"#/components/schemas/SubtitlesOperation"}]},"default":[]},"output":{"$ref":"#/components/schemas/Output"},"webhook":{"$ref":"#/components/schemas/Webhook"}}},"ToolRequest":{"type":"object","required":["input"],"properties":{"input":{"type":"string","format":"uri","description":"A public HTTP(S) video URL."},"options":{"type":"object","additionalProperties":true,"default":{}},"webhook":{"$ref":"#/components/schemas/Webhook"}}},"MediaInput":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"A public HTTP(S) video URL."},"filename":{"type":"string","maxLength":180}}},"TrimOperation":{"type":"object","required":["type","start"],"properties":{"type":{"const":"trim"},"start":{"type":"number","minimum":0,"maximum":86400},"end":{"type":"number","exclusiveMinimum":0,"maximum":86400}}},"ResizeOperation":{"type":"object","required":["type","width","height"],"properties":{"type":{"const":"resize"},"width":{"type":"integer","minimum":16,"maximum":4096},"height":{"type":"integer","minimum":16,"maximum":4096},"fit":{"type":"string","enum":["cover","contain"],"default":"cover"}}},"ThumbnailOperation":{"type":"object","required":["type"],"properties":{"type":{"const":"thumbnail"}}},"SubtitlesOperation":{"type":"object","required":["type","url"],"properties":{"type":{"const":"subtitles"},"url":{"type":"string","format":"uri","description":"A public HTTP(S) SRT or WebVTT URL."}}},"Output":{"type":"object","properties":{"format":{"type":"string","enum":["mp4","webm","mp3","wav","jpg","webp"],"default":"mp4"},"quality":{"type":"string","enum":["fast","balanced","quality"],"default":"balanced"}}},"Webhook":{"type":"object","required":["url","secret"],"properties":{"url":{"type":"string","format":"uri","description":"A public HTTPS endpoint using the default port."},"secret":{"type":"string","minLength":16,"maxLength":256,"writeOnly":true,"description":"Used to sign X-KinoPipe-Signature with HMAC-SHA256."},"events":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","enum":["job.succeeded","job.failed"]},"default":["job.succeeded","job.failed"]}}},"Job":{"type":"object","required":["id","status","progress"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"consumedCredits":{"type":"integer","minimum":0},"creditBalance":{"type":"integer","minimum":0},"error":{"$ref":"#/components/schemas/Error"}}},"AcceptedJob":{"type":"object","required":["ok","job","statusUrl"],"properties":{"ok":{"const":true},"reused":{"type":"boolean"},"job":{"$ref":"#/components/schemas/Job"},"statusUrl":{"type":"string","description":"Relative URL to poll with the same API key."}}},"JobStatus":{"type":"object","required":["ok","job"],"properties":{"ok":{"const":true},"job":{"$ref":"#/components/schemas/Job"},"result":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"A valid KinoPipe API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"The account does not have enough credits to start another edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QueueUnavailable":{"description":"The video edit could not be placed on the render queue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}