API Reference

The VidioClient is the main entry point for interacting with the VIDIO API from Python. Use it to upload files, create highlight reel jobs, check job status, render outputs, and wait for processing to complete.

API access is currently available for Studio plan and above.

The client model

The VidioClient provides a simple interface for working with the VIDIO API. After creating a client with your API key, you can upload input files, create highlight reel jobs, poll job status, render outputs, and wait for jobs to finish.

Properties

api_keystring

Your VIDIO API key used to authenticate requests.

Methods

CLASSVidioClient(api_key)

Initialize client

Creates a new VidioClient instance.

Parameters

api_keystring

Your VIDIO API key.

Returns

A configured VidioClient instance.

python

from vidio import VidioClient
import os

client = VidioClient(
    api_key=os.getenv("VIDIO_API_KEY")
)

METHODclient.upload(file_path)

Upload file

Uploads a local file to VIDIO and returns an upload result containing the input key.

Parameters

file_pathstring

The local path to the file you want to upload.

Returns

An upload result object containing `input_key`.

python

result = client.upload("/path/to/video.mp4")
print(result.input_key)

METHOD

client.create_highlight_reel(input_keys, video_category, output_length, aspect_ratio, music_category=None, music_volume=None, original_audio_volume=None)

Create highlight reel

Creates a highlight reel job from one or more uploaded input files.

Parameters

input_keyslist[string]

A list of uploaded file keys returned by upload(). The order of input keys determines the order of media in the output video.

video_categorystring

Video category such as ball-sports. It can be podcast, ball-sports, non-ball-sports, beauty-product-demo, wedding, travel, others. For best results, specify the category that most closely matches your content. If your content doesn't fit any category, use others.

output_lengthinteger

Desired output length in seconds. The output length should be less than or equal to the total length of all input videos combined.

aspect_ratiostring

Output aspect ratio such as landscape, portrait, or square.

music_categorystring, optional

Preset music category to apply to the output. Supported values are corporate, romantic, sports, kids_and_comedy, ambient_and_nature, horror_and_suspense, documentary, and trending_vlogs. If the output duration is shorter than the music duration, the selected track will loop to fit the output.

music_volumeinteger, optional

Background music volume from 0 to 100. If not provided, the default is 100.

original_audio_volumeinteger, optional

Original source audio volume from 0 to 100. If not provided, the default is 100.

Returns

A job object containing `job_id` and status information.

python

job = client.create_highlight_reel(
    input_keys=[result.input_key],
    video_category="ball-sports",
    output_length=30,
    aspect_ratio="landscape",
    music_category="sports",
    music_volume=70,
    original_audio_volume=100,
)

print(job.job_id)
print(job.status)

METHODclient.get_job(job_id)

Get job

Fetches the current status of a job. When the job has been rendered, the response can also include structured output data for the last sub-job, including outputs and overlays.

Parameters

job_idstring

The job ID returned when the highlight reel job was created.

Returns

A job object with the latest status. If rendering is complete, it may also include `outputs` for the last sub-job.

Response fields

job_idstring

The job ID.

statusstring

The current job status, such as submitted, queued, processing, processed, rendering, or rendered.

outputslist[OutputResult]

Returned when the job is fully rendered and output data is available from the last sub-job.

startfloat | null

Start time of the output segment, if available.

endfloat | null

End time of the output segment, if available.

thumbnailstring | null

Thumbnail path or URL for the output.

durationfloat | null

Duration of the output in seconds.

fpsfloat | null

Frames per second for the output.

overlayslist[OverlayResult]

Sanitized overlays included in the output.

idinteger | null

Overlay ID.

fileIDstring | null

Associated file ID, when available.

originalFileNamestring | null

Original input file name associated with the overlay, when available.

from_integer | float | null

Frame offset where the overlay starts.

contentstring | null

Overlay content value, such as a thumbnail path or sound identifier.

durationInFramesinteger | null

Overlay duration in frames.

typestring | null

Overlay type such as video or sound.

srcstring | null

Source URL for the overlay media.

videoStartTimeinteger | float | null

Source video start time, when applicable.

python

job_status = client.get_job(job.job_id)
print(job_status.status)

for output in job_status.outputs:
    print(output.thumbnail)
    print(output.duration)
    for overlay in output.overlays:
        print(overlay.type, overlay.src)

json

{
  "job_id": "abc123",
  "status": "rendered",
  "outputs": [
    {
      "start": null,
      "end": null,
      "thumbnail": "out/...jpg",
      "duration": 15.22,
      "overlays": [
        {
          "id": 0,
          "fileID": "file_123",
          "from": 0,
          "content": "https://...",
          "durationInFrames": 284,
          "type": "video",
          "src": "https://...",
          "videoStartTime": 5425
        },
        {
          "id": 876361,
          "from": 0,
          "content": "running-night-393139",
          "durationInFrames": 912,
          "type": "sound",
          "src": "https://..."
        }
      ],
      "fps": 59.94
     }
  ]
}

METHODclient.wait_for_job(job_id)

Wait for job

Polls the API until the highlight reel job reaches a completed state.

Parameters

job_idstring

The job ID to wait for.

Returns

The final completed job object.

python

final_job = client.wait_for_job(job.job_id)
print(final_job.status)

METHODclient.render(job_id, output_index=0)

Render output

Starts rendering an output video for a completed highlight reel job. Use `output_index` to select which item from the `OutputResult` list to render. In general, the first output is the best result.

Parameters

job_idstring

The completed highlight reel job ID.

output_indexinteger, optional

The index of the OutputResult list to render. The default is 0. In general, the first output is the best result.

Returns

A render result object with render status.

python

render_result = client.render(
    job_id=job.job_id,
    output_index=0,
)

print(render_result.status)

METHODclient.wait_for_render(job_id)

Wait for render

Polls until the render finishes and the output is ready.

Parameters

job_idstring

The job ID associated with the render.

Returns

The final render result object.

python

final_render = client.wait_for_render(job.job_id)
print(final_render.output_url)