Referência da API

O VidioClient é o ponto de entrada principal para interagir com a API VIDIO a partir do Python. Utilize-o para enviar ficheiros, criar trabalhos de recorte de destaques, verificar o estado dos trabalhos, renderizar saídas e esperar que o processamento seja concluído.

O acesso à API está atualmente disponível para o plano Studio e superiores.

O modelo do cliente

O VidioClient fornece uma interface simples para trabalhar com a API VIDIO. Após criar um cliente com a sua chave de API, você pode enviar ficheiros de entrada, criar trabalhos de recorte de destaques, consultar o estado dos trabalhos, renderizar saídas e esperar que os trabalhos terminem.

Propriedades

api_keystring

A sua chave de API VIDIO utilizada para autenticar pedidos.

Métodos

CLASSEVidioClient(api_key)

Inicializar cliente

Cria uma nova instância do VidioClient.

Parameters

api_keystring

A sua chave de API VIDIO.

Returns

Uma instância do VidioClient configurada.

python

from vidio import VidioClient
import os

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

MÉTODOclient.upload(file_path)

Enviar ficheiro

Envia um ficheiro local para a VIDIO e retorna um resultado de envio com a chave de entrada.

Parameters

file_pathstring

O caminho local do ficheiro que deseja enviar.

Returns

Um objeto de resultado de envio contendo `input_key`.

python

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

MÉTODOclient.create_highlight_reel(input_keys, video_category, output_length, aspect_ratio)

Criar recorte de destaques

Cria um trabalho de recorte de destaques a partir de um ou mais ficheiros de entrada enviados.

Parameters

input_keyslist[string]

Uma lista de chaves de ficheiros enviados retornadas por upload(). A ordem das chaves de entrada determina a ordem da media no vídeo de saída.

video_categorystring

Categoria do vídeo, como ball-sports. Pode ser podcast, ball-sports, non-ball-sports, beauty-product-demo, wedding, travel, others. Para melhores resultados, especifique a categoria que mais se aproxima do seu conteúdo. Se o seu conteúdo não se encaixar em nenhuma categoria, utilize others.

output_lengthinteger

Duração desejada da saída em segundos. O comprimento da saída deve ser menor ou igual ao comprimento total de todos os vídeos de entrada combinados.

aspect_ratiostring

Relação de aspecto da saída, como landscape, portrait ou square.

music_categorystring, optional

Categoria de música predefinida a aplicar à saída. Os valores suportados são corporate, romantic, sports, kids_and_comedy, ambient_and_nature, horror_and_suspense, documentary, e trending_vlogs. Se a duração da saída for inferior à duração da música, a faixa selecionada será reproduzida em loop para ajustar-se à saída.

music_volumeinteger, optional

Volume da música de fundo de 0 a 100. Se não for fornecido, o valor predefinido é 100.

original_audio_volumeinteger, optional

Volume de áudio da fonte original de 0 a 100. Se não for fornecido, o valor predefinido é 100.

Returns

Um objeto de trabalho contendo `job_id` e informações de estado.

python

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

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

MÉTODOclient.get_job(job_id)

Obter trabalho

Recupera o estado atual de um trabalho.

Parameters

job_idstring

O ID do trabalho retornado quando o trabalho de recorte de destaques foi criado.

Returns

Um objeto de trabalho com o estado mais recente.

Response fields

job_idstring

O ID do trabalho.

statusstring

O estado atual do trabalho, como submitted, queued, processing, processed, rendering ou rendered.

outputslist[OutputResult]

Retornado quando o trabalho estiver completamente renderizado e os dados de saída estiverem disponíveis a partir do último subtrabalho.

startfloat | null

Tempo de início do segmento de saída, se disponível.

endfloat | null

Tempo de fim do segmento de saída, se disponível.

thumbnailstring | null

Caminho ou URL da miniatura para a saída.

durationfloat | null

Duração da saída em segundos.

fpsfloat | null

Fotogramas por segundo da saída.

overlayslist[OverlayResult]

Sobreposições sanitizadas incluídas na saída.

idinteger | null

ID da sobreposição.

fileIDstring | null

ID do ficheiro associado, quando disponível.

originalFileNamestring | null

Nome do ficheiro de entrada original associado à sobreposição, quando disponível.

from_integer | float | null

Deslocamento de fotogramas onde a sobreposição começa.

contentstring | null

Valor do conteúdo da sobreposição, como um caminho de miniatura ou identificador de som.

durationInFramesinteger | null

Duração da sobreposição em fotogramas.

typestring | null

Tipo de sobreposição, tal como video ou sound.

srcstring | null

URL de origem para o conteúdo multimédia da sobreposição.

videoStartTimeinteger | float | null

Tempo de início do vídeo de origem, quando aplicável.

python

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

json

{
  "job_id": "abc123",
  "status": "renderizado",
  "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": "corrida-noite-393139",
          "durationInFrames": 912,
          "type": "sound",
          "src": "https://..."
        }
      ],
      "fps": 59.94
     }
  ]
}

MÉTODOclient.wait_for_job(job_id)

Aguardar trabalho

Consulta a API até que o trabalho de recorte de destaques alcance um estado concluído.

Parameters

job_idstring

O ID do trabalho para o qual aguardar.

Returns

O objeto final do trabalho concluído.

python

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

MÉTODOclient.render(job_id)

Renderizar saída

Inicia a renderização de um vídeo de saída para um trabalho de recorte de destaques concluído.

Parameters

job_idstring

O ID do trabalho de recorte de destaques concluído.

output_indexinteger, optional

O índice da lista OutputResult a renderizar. O padrão é 0. Em geral, a primeira saída é o melhor resultado.

Returns

Um objeto de resultado de renderização com o estado da renderização.

python

render_result = client.render(
    job_id=job.job_id
)

print(render_result.status)

MÉTODOclient.wait_for_render(job_id)

Aguardar renderização

Consulta até que a renderização termine e a saída esteja pronta.

Parameters

job_idstring

O ID do trabalho associado à renderização.

Returns

O objeto final de resultado da renderização.

python

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