@spec add_caption(t() | keyword(), String.t(), String.t(), String.t(), String.t()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Adds or updates a caption track for a video.

@spec add_output_codec(t() | keyword(), String.t(), integer()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Adds an output codec to a video (0 = x264, 1 = vp9, 2 = hevc, 3 = av1).

@spec cleanup_resolutions(t() | keyword(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Cleans up unconfigured resolution files from a video.

Options

• :dry_run — if true, returns info without deleting (default false)

@spec create(t() | keyword(), Bunnyx.Params.attrs()) ::
  {:ok, Bunnyx.Stream.Video.t()} | {:error, Bunnyx.Error.t()}

Creates a video. The video must be uploaded separately with upload/3.

Attributes

• :title (required) — video title
• :collection_id — collection to place the video in
• :thumbnail_time — time in ms to extract the thumbnail from

@spec create_collection(t() | keyword(), String.t()) ::
  {:ok, Bunnyx.Stream.Collection.t()} | {:error, Bunnyx.Error.t()}

Creates a collection with the given name.

@spec delete(t() | keyword(), String.t()) :: {:ok, nil} | {:error, Bunnyx.Error.t()}

Deletes a video.

@spec delete_caption(t() | keyword(), String.t(), String.t()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Deletes a caption track from a video.

@spec delete_collection(t() | keyword(), String.t()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Deletes a collection.

@spec fetch(
  t() | keyword(),
  keyword()
) :: {:ok, Bunnyx.Stream.Video.t()} | {:error, Bunnyx.Error.t()}

Fetches a video from a URL for the library to download and encode.

Attributes

• :url (required) — source URL
• :title — video title
• :headers — headers to send with the fetch request

@spec get(t() | keyword(), String.t()) ::
  {:ok, Bunnyx.Stream.Video.t()} | {:error, Bunnyx.Error.t()}

Fetches a video by GUID.

@spec get_collection(t() | keyword(), String.t()) ::
  {:ok, Bunnyx.Stream.Collection.t()} | {:error, Bunnyx.Error.t()}

Fetches a collection by GUID.

@spec heatmap(t() | keyword(), String.t()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns the video watch heatmap data.

@spec list(
  t() | keyword(),
  keyword()
) ::
  {:ok,
   %{
     items: [Bunnyx.Stream.Video.t()],
     current_page: integer(),
     total_items: integer(),
     per_page: integer()
   }}
  | {:error, Bunnyx.Error.t()}

Lists videos in the library.

Options

• :page — page number
• :per_page — items per page
• :search — search term
• :collection — filter by collection ID
• :order_by — sort field (default "date")

@spec list_collections(
  t() | keyword(),
  keyword()
) ::
  {:ok,
   %{
     items: [Bunnyx.Stream.Collection.t()],
     current_page: integer(),
     total_items: integer(),
     per_page: integer()
   }}
  | {:error, Bunnyx.Error.t()}

Lists collections in the library.

Options

• :page — page number
• :per_page — items per page
• :search — search term
• :order_by — sort field
• :include_thumbnails — include preview image URLs

@spec new(keyword()) :: t()

Creates a new Stream client.

Options

• :api_key (required) — video library API key
• :library_id (required) — video library ID
• :receive_timeout — socket receive timeout in milliseconds (default 15_000)
• :finch — a custom Finch pool name

@spec oembed(t() | keyword(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns oEmbed data for a video URL.

Options

• :max_width — maximum embed width
• :max_height — maximum embed height
• :token — authentication token
• :expires — token expiration timestamp

@spec reencode(t() | keyword(), String.t()) :: {:ok, nil} | {:error, Bunnyx.Error.t()}

Triggers re-encoding of a video.

@spec repackage(t() | keyword(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Repackages a video.

Options

• :keep_original_files — keep originals after repackaging (default true)

@spec set_thumbnail(t() | keyword(), String.t(), String.t()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Sets a video thumbnail from a URL.

@spec smart_actions(t() | keyword(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Triggers AI-powered smart actions for a video.

Options

• :generate_title — auto-generate title
• :generate_description — auto-generate description
• :generate_chapters — auto-generate chapters
• :generate_moments — auto-generate moments
• :source_language — source language code

@spec transcribe(t() | keyword(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Triggers transcription for a video.

Options

• :target_languages — list of ISO 639-1 language codes
• :source_language — source language code
• :generate_title — auto-generate title
• :generate_description — auto-generate description
• :generate_chapters — auto-generate chapters
• :generate_moments — auto-generate moments
• :force — force re-transcription

@spec update(t() | keyword(), String.t(), Bunnyx.Params.attrs()) ::
  {:ok, Bunnyx.Stream.Video.t()} | {:error, Bunnyx.Error.t()}

Updates a video's metadata.

Attributes

• :title — video title
• :collection_id — collection ID
• :chapters — list of chapter maps
• :moments — list of moment maps
• :meta_tags — list of meta tag maps

@spec update_collection(t() | keyword(), String.t(), String.t()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Updates a collection's name.

@spec upload(t() | keyword(), String.t(), binary()) ::
  {:ok, nil} | {:error, Bunnyx.Error.t()}

Uploads video data to a previously created video.

@spec video_heatmap_data(t() | keyword(), String.t()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns raw heatmap data for a video.

@spec video_play_data(t() | keyword(), String.t()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns player configuration and playback URLs for a video.

@spec video_resolutions(t() | keyword(), String.t()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns resolution availability and encoding info for a video.

@spec video_statistics(
  t() | keyword(),
  keyword()
) :: {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns video statistics for the library or a specific video.

Options

• :date_from — start date (ISO 8601 string)
• :date_to — end date (ISO 8601 string)
• :hourly — group by hour instead of day
• :video_guid — filter by specific video GUID

@spec video_storage_info(t() | keyword(), String.t()) ::
  {:ok, map()} | {:error, Bunnyx.Error.t()}

Returns storage size breakdown for a video.