{ "openapi": "3.1.0", "info": { "title": "Slice API", "version": "1.0.0", "summary": "Turn long videos into captioned vertical clips, and recordings into text.", "description": "The same tools as the Slice MCP server, over HTTP with an account key. Docs: https://tryslicemedia.com/developers. Test keys (slk_test_) return sample data and cost nothing. Live keys (slk_live_) do real work on your account.", "contact": { "name": "Slice", "email": "mediabyslice@gmail.com", "url": "https://tryslicemedia.com/developers" } }, "servers": [ { "url": "https://tryslicemedia.com/api/v1" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Account" }, { "name": "Episodes" }, { "name": "Clips" }, { "name": "Jobs" }, { "name": "Transcripts" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "summary": "The account, this key, this month's use and the limits", "operationId": "getMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/episodes": { "get": { "tags": [ "Episodes" ], "summary": "Recent episodes (up to 10)", "operationId": "listEpisodes", "x-scope": "clips.read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "episodes": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeSummary" } }, "message": { "type": "string" } } } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Episodes" ], "summary": "Start an episode", "operationId": "createEpisode", "x-scope": "clips.write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "description": "With source_url, Slice copies the file in from that https link (an RSS enclosure, a storage link). Without it, the answer carries a PUT upload url: upload the video, then POST /episodes/{id}/uploaded. Transcription and the clip search then start on their own. Video or audio: an audio file (MP3, M4A, AAC, WAV, OGG, Opus, FLAC) becomes an audio episode whose clips are drawn with an audio template.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source_url": { "type": "string", "format": "uri", "description": "A direct https link to the video or audio file, such as an RSS enclosure. Not a YouTube or other page." }, "file_name": { "type": "string", "description": "For an upload: the file name, used for its type (.mp4, .mov, .m4v, .webm, .mkv, .avi, .mp3, .m4a, .aac, .wav, .ogg, .opus, .flac)." }, "name": { "type": "string", "maxLength": 200 }, "content_type": { "type": "string", "enum": [ "podcast", "stream", "other" ] }, "target_seconds": { "type": "integer", "minimum": 15, "maximum": 180, "description": "How long each clip should be. Leave out for 30 to 150 seconds." } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeCreated" } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/episodes/{id}": { "get": { "tags": [ "Episodes" ], "summary": "An episode: status, and its found clips once ready", "operationId": "getEpisode", "x-scope": "clips.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The episode id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Episode" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/episodes/{id}/uploaded": { "post": { "tags": [ "Episodes" ], "summary": "Say the upload is done", "operationId": "markUploaded", "x-scope": "clips.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The episode id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "episode_id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/episodes/{id}/clips": { "post": { "tags": [ "Clips" ], "summary": "Make clips: cut and caption found clips", "operationId": "makeClips", "x-scope": "clips.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The episode id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clips" ], "properties": { "clips": { "type": "array", "maxItems": 10, "items": { "type": [ "integer", "string" ] }, "description": "Numbers or refs from GET /episodes/{id}." }, "style": { "type": "string", "description": "A caption style id or name from GET /styles, e.g. bold-punch." }, "caption_size": { "type": "string", "enum": [ "smaller", "bigger", "small", "medium", "large", "extra_large" ] }, "caption_position": { "type": "string", "enum": [ "up", "down", "top", "middle", "lower", "bottom" ] }, "hook_title": { "type": [ "boolean", "string" ], "description": "The title box at the top. false removes it, true uses the clip title, or give the words." }, "fit": { "type": "string", "enum": [ "fill", "whole" ], "description": "fill crops to fill the frame (default); whole shows the whole video." }, "background": { "type": "string", "enum": [ "black", "blur" ], "description": "Behind a whole video." } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MakeClips" } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/episodes/{id}/search": { "post": { "tags": [ "Clips" ], "summary": "Find clips about a topic", "operationId": "findClipsAbout", "x-scope": "clips.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The episode id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "description": "Searches the episode again with a brief. New clips are added to its list. Results arrive with the episode.ready webhook, or poll GET /episodes/{id}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "about": { "type": "string", "maxLength": 500 }, "target_seconds": { "type": "integer", "minimum": 15, "maximum": 180 } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "episode_id": { "type": "string" }, "status": { "type": "string", "enum": [ "searching", "done" ] }, "clips": { "type": "array", "items": { "$ref": "#/components/schemas/FoundClip" } }, "charged_cents": { "type": "integer" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}": { "get": { "tags": [ "Jobs" ], "summary": "A cut or a render, with the download link when done", "operationId": "getJob", "x-scope": "clips.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/clips/{id}": { "patch": { "tags": [ "Clips" ], "summary": "Restyle a made clip and render it again", "operationId": "restyleClip", "x-scope": "clips.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The clip id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "style": { "type": "string", "description": "A caption style id or name from GET /styles, e.g. bold-punch." }, "caption_size": { "type": "string", "enum": [ "smaller", "bigger", "small", "medium", "large", "extra_large" ] }, "caption_position": { "type": "string", "enum": [ "up", "down", "top", "middle", "lower", "bottom" ] }, "hook_title": { "type": [ "boolean", "string" ], "description": "The title box at the top. false removes it, true uses the clip title, or give the words." }, "fit": { "type": "string", "enum": [ "fill", "whole" ], "description": "fill crops to fill the frame (default); whole shows the whole video." }, "background": { "type": "string", "enum": [ "black", "blur" ], "description": "Behind a whole video." }, "save_as_default": { "type": "boolean" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "clip_id": { "type": "string" }, "job_id": { "type": "string" }, "status": { "type": "string" }, "changes": { "type": "array", "items": { "type": "string" } }, "charged_cents": { "type": "integer" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/clips/{id}/captions": { "get": { "tags": [ "Clips" ], "summary": "The captions on a clip", "operationId": "readCaptions", "x-scope": "clips.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The clip id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "at", "in": "query", "schema": { "type": "number" }, "description": "Seconds: what is on screen then." }, { "name": "from", "in": "query", "schema": { "type": "number" } }, { "name": "to", "in": "query", "schema": { "type": "number" } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Only captions containing this text." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 40 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "clip_id": { "type": "string" }, "name": { "type": "string" }, "total": { "type": "integer" }, "captions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "start_seconds": { "type": "number" }, "end_seconds": { "type": "number" }, "speaker": { "type": "string" }, "text": { "type": "string" } } } } } } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/styles": { "get": { "tags": [ "Clips" ], "summary": "Caption styles", "operationId": "listStyles", "x-scope": "clips.read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "styles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transcripts": { "post": { "tags": [ "Transcripts" ], "summary": "Transcribe a recording from a link", "operationId": "createTranscript", "x-scope": "transcripts", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "description": "Uses the account's 3 free transcripts a month (shared with the website), then Transcribe hours. Up to 90 minutes a file.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "A direct https link to an audio or video file." } } } } } }, "responses": { "200": { "description": "Already done", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcript" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcript" } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transcripts/{id}": { "get": { "tags": [ "Transcripts" ], "summary": "A transcript: status, text and downloads", "operationId": "getTranscript", "x-scope": "transcripts", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The transcript id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcript" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook addresses, with recent deliveries", "operationId": "listWebhooks", "x-scope": "webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Add a webhook address", "operationId": "createWebhook", "x-scope": "webhooks", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 255 characters, such as a UUID. A repeat with the same key and body within 24 hours gets the first answer and starts nothing new.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "description": "https only; private networks are refused." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "whsec_..., shown in this answer only." } } } ] } } } }, "400": { "description": "Invalid input. The message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs credit or the Slice plan (plan_or_credit_required, credit_required, plan_required), or the balance is below zero after a refunded credit pack (balance_below_zero). Numbers are in the error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Busy, or an Idempotency-Key still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Remove a webhook address", "operationId": "deleteWebhook", "x-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The webhook id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a signed sample event now", "operationId": "testWebhook", "x-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The webhook id.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/EventType" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "event": { "type": "string" }, "delivered": { "type": "boolean" }, "status": { "type": [ "integer", "null" ] } } } } } }, "401": { "description": "Missing, unknown, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission (scope) this needs, or the account is under billing review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. See retry_after and the RateLimit-* headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "episode.ready": { "post": { "summary": "An episode's clips are found (also after each extra search)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEpisode" } } } }, "responses": { "200": { "description": "Any 2xx means received." } } } }, "clip.ready": { "post": { "summary": "A clip render finished; data.download_url is good for 7 days", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventJob" } } } }, "responses": { "200": { "description": "Any 2xx means received." } } } }, "transcript.completed": { "post": { "summary": "A transcript finished; links to the text, SRT and VTT", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTranscript" } } } }, "responses": { "200": { "description": "Any 2xx means received." } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "slk_live_... or slk_test_..., from your Slice account settings." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after": { "type": "integer" }, "limit": { "type": "integer" }, "needed_cents": { "type": "integer" }, "credit_cents": { "type": "integer" } }, "additionalProperties": true } } }, "EventType": { "type": "string", "enum": [ "episode.ready", "episode.failed", "clip.ready", "clip.failed", "transcript.completed", "transcript.failed" ] }, "Me": { "type": "object", "properties": { "account": { "type": "object", "properties": { "email": { "type": "string" }, "plan": { "type": "string", "enum": [ "slice", "free" ] } } }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "livemode": { "type": "boolean" }, "usage": { "type": "object", "properties": { "period_resets_at": { "type": "string", "format": "date-time" }, "plan_episodes": { "type": "object", "properties": { "included": { "type": "integer" }, "used": { "type": "integer" } } }, "credit_cents": { "type": "integer", "description": "Below zero after a refunded credit pack whose credit was partly spent." }, "credit": { "type": "string" }, "balance_below_zero": { "type": "boolean" }, "transcripts": { "type": "object", "properties": { "free_per_month": { "type": "integer" }, "used": { "type": [ "integer", "null" ] } } } } }, "limits": { "type": "object", "properties": { "reads_per_minute": { "type": "integer" }, "writes_per_minute": { "type": "integer" }, "episodes_per_day": { "type": "integer" }, "episodes_in_progress": { "type": "integer" } } } } }, "EpisodeStatus": { "type": "string", "enum": [ "waiting_for_upload", "uploading", "transcribing", "finding_clips", "ready", "failed" ] }, "EpisodeSummary": { "type": "object", "properties": { "episode_id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/EpisodeStatus" }, "clips_found": { "type": "integer" }, "created": { "type": "string" } } }, "EpisodeCreated": { "type": "object", "properties": { "episode_id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/EpisodeStatus" }, "livemode": { "type": "boolean" }, "upload": { "type": "object", "properties": { "method": { "const": "PUT" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expires_in_seconds": { "type": "integer" } } }, "upload_page_url": { "type": "string", "description": "The same upload as a page a person can open." }, "message": { "type": "string" } } }, "FoundClip": { "type": "object", "properties": { "number": { "type": "integer" }, "ref": { "type": "string" }, "title": { "type": "string" }, "hook": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "length": { "type": "string" }, "pieces": { "type": "integer" }, "cut_status": { "type": "string", "enum": [ "not_cut", "cutting", "cut", "failed" ] }, "clip_id": { "type": "string" }, "poster_url": { "type": "string" }, "export_status": { "type": "string", "enum": [ "none", "rendering", "completed", "failed" ] }, "job_id": { "type": "string" }, "download_url": { "type": "string" }, "about": { "type": "string" }, "reason": { "type": "string" } } }, "Episode": { "type": "object", "properties": { "episode_id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/EpisodeStatus" }, "progress_percent": { "type": "number" }, "duration": { "type": "string" }, "upload_url": { "type": "string" }, "clips": { "type": "array", "items": { "$ref": "#/components/schemas/FoundClip" } }, "message": { "type": "string" }, "livemode": { "type": "boolean" } } }, "MakeClips": { "type": "object", "properties": { "episode_id": { "type": "string" }, "clips": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "ref": { "type": "string" }, "title": { "type": "string" }, "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "cutting", "rendering", "failed" ] }, "clip_id": { "type": "string" }, "message": { "type": "string" } } } }, "charged_cents": { "type": "integer" }, "message": { "type": "string" } } }, "Job": { "type": "object", "properties": { "job_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "cut", "render" ] }, "status": { "type": "string", "enum": [ "queued", "cutting", "rendering", "completed", "failed", "expired", "not_rendered" ] }, "progress_percent": { "type": "number" }, "clip_id": { "type": "string" }, "title": { "type": "string" }, "poster_url": { "type": "string" }, "download_url": { "type": "string", "description": "A short link to the MP4, good for 7 days." }, "file_size_mb": { "type": "number" }, "clips": { "type": "array", "items": { "type": "object", "properties": { "clip_id": { "type": "string" }, "title": { "type": "string" }, "render_job_id": { "type": "string" }, "render_status": { "type": "string" }, "download_url": { "type": "string" } } } }, "message": { "type": "string" } } }, "Transcript": { "type": "object", "properties": { "transcript_id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed" ] }, "results_url": { "type": "string" }, "file_name": { "type": "string" }, "duration_minutes": { "type": "number" }, "word_count": { "type": "integer" }, "language": { "type": "string" }, "transcript": { "type": "string" }, "transcript_truncated": { "type": "boolean" }, "downloads": { "type": "object", "properties": { "txt": { "type": "string" }, "srt": { "type": "string" }, "vtt": { "type": "string" } } }, "message": { "type": "string" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "last_success_at": { "type": [ "string", "null" ] } } }, "EventEnvelope": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "$ref": "#/components/schemas/EventType" }, "timestamp": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean" }, "data": { "type": "object" } } }, "EventEpisode": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Episode" } } } ] }, "EventJob": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Job" }, { "type": "object", "properties": { "episode_id": { "type": "string" } } } ] } } } ] }, "EventTranscript": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transcript" } } } ] } } } }