API de Mídia

Lista mídias prontas da mais nova para a mais antiga, no máximo 1000 por página. folder mantém apenas os arquivos diretamente dentro de uma pasta de mídia (seu ID), ou com root somente aqueles na raiz da biblioteca; um ID de pasta bem formado que não nomeia nenhuma pasta não lista nada. next_cursor é a posição da última linha retornada enquanto houver mais linhas; passe-o de volta como after, com os mesmos filtros, para a próxima página. next_cursor é nulo na última página.

Gerar uma imagem estática a partir de um prompt, armazená-la como mídia privada pronta do projeto e faturar seu uso. O POST responde 202 imediatamente com Operation, com ou sem Prefer: respond-async, porque um proxy diante da API descarta uma solicitação que não envia nenhum byte por 100 s e uma imagem estática de alta qualidade pode demorar mais.

Consulte GET /api/operations/{id} até que Operation seja succeeded, quando seu result for {media_id, usage: {quality, credits, usd}} (MediaGenerationUsage), ou failed, quando seu error for o problema. Uma recusa decidida antes de qualquer trabalho do fornecedor (payment_required, reseller_generation_limit, rate_limited, not_ready, invalid_request) ainda responde ao POST.

Nunca inclui bytes de imagem, b64_json, chaves de objeto, URLs assinadas, URLs do fornecedor, custo do fornecedor, tokens do fornecedor ou o nome do modelo de implantação. O prompt são bytes do cliente e não é ecoado.

Antes que o prompt alcance o fornecedor de imagem, o servidor adiciona requisitos fixos de enquadramento: a arte deve preencher a moldura de ponta a ponta, e nenhuma televisão, monitor, tela, display, moldura, borda, suporte, parede, sala, maquete de dispositivo, sombra ou fotografia de sinal instalado pode ser representada, e qualquer texto no prompt do chamador descrevendo onde o sinal será pendurado ou qual dispositivo o mostrará é tratado como metadados de posicionamento, não como assunto.

Regras decorativas e bordas dentro do próprio design permanecem disponíveis. O prompt do chamador nunca é reescrito ou removido e é armazenado inalterado. Idempotency-Key repete a mesma Operation, nunca uma segunda tentativa faturada. Os clientes não fazem PUT nem confirmam os bytes gerados.

A versão armazenada é WebP com perda (qualidade 90) no tamanho exato da proporção com uma borda curta de 1080 px (16:9 é 1920x1080, 9:16 1080x1920, 1:1 1080x1080, 4:3 1440x1080, 3:4 1080x1440, 3:2 1620x1080, 2:3 1080x1620); a tela do fornecedor é recortada centralmente e reamostrada para esse tamanho.

O nome do arquivo é distinto por geração, generated-16x9-1a2b3c4d.webp, com o sufixo retirado do id do mídia. Busque os bytes com GET /api/media/{id}/content. Own-gen-then-upload permanece válido.

No Standard, saldo restante que não cobre o dobro do custo do fornecedor da imagem estática, arredondado para créditos inteiros, após o piso introdutório (negativo 1.000.000 créditos até 2027-01-01, depois zero) retorna payment_required, exceto SCREENRIG__ENVIRONMENT=development, e a admissão antes da chamada ao fornecedor requer saldo acima desse piso pelo mínimo por qualidade: 200 créditos para baixa, 800 para média, 2000 para alta.

Outros planos nunca são recusados por causa do saldo.

Uma organização cobrada por meio de um revendedor é recusada com reseller_generation_limit (402) assim que os clientes delegados do revendedor dela tiverem sido cobrados pelo limite mensal de geração de imagens ($100 ao preço de tabela enquanto o revendedor aguarda análise, $1,000 depois, contado por mês UTC), a menos que o crédito próprio da organização cubra a imagem; uma geração já admitida é concluída.

Uma configuração vazia do fornecedor selecionado retorna not_ready. Somente token de projeto. Uma geração em andamento por organização; mais paralelismo é rate_limited.

Lista todas as pastas de mídia no projeto, no máximo 1000, ordenadas por nome. Pastas organizam a biblioteca de mídia, e um seletor de playlist por:folder reproduz os arquivos diretamente dentro de uma pasta. O parent_id de uma pasta é nulo na raiz da biblioteca.

Construa a árvore a partir do parent_id; a pasta de um arquivo é Media.folder_id. library=true lista, em vez disso, as pastas da Biblioteca da organização (somente leitura; um seletor by:folder pode nomear uma).

Cria uma pasta de mídia na raiz da biblioteca (parent_id nulo ou ausente) ou dentro de parent_id. Nomes são aparados, têm de 1 a 100 caracteres Unicode sem controles, não são "." ou "..", e podem repetir. Uma organização tem no máximo 1000 pastas em todos os seus projetos (quota_exceeded) aninhadas no máximo 10 níveis (invalid_request). Emite media.folder_created.

Renomeia uma pasta (nome) ou a move com tudo dentro (parent_id, nulo para a raiz da biblioteca). Uma pasta não pode ser movida para dentro de si mesma ou de uma pasta dentro dela, e a movimentação deve manter todas as pastas dentro de 10 níveis (invalid_request). Uma alteração avança a revisão da pasta e emite media.folder_updated; os mesmos valores são uma operação nula.

If-Match protege opcionalmente a revisão.

Exclui uma pasta. Nada dentro é excluído - seus arquivos e pastas sobem para o pai da pasta excluída (a raiz da biblioteca quando não tinha pai), cada arquivo e pasta movido avança sua revisão. Um seletor de playlist por:folder que nomeia a pasta excluída não corresponde a nada; telas em reprodução descartam esse primitivo na próxima resolução do seletor.

Emite media.folder_deleted. If-Match pode proteger a revisão opcionalmente.

Move arquivos (media_ids) e pastas (folder_ids) para uma pasta (folder_id), ou para a raiz da biblioteca quando folder_id for null, em uma única requisição tudo-ou-nada de no máximo 1000 ids. Cada id deve existir (not_found). Uma pasta não pode se mover para dentro de si mesma ou de uma pasta dentro dela, e a movimentação deve manter todas as pastas dentro de 10 níveis (invalid_request).

Itens já no destino permanecem como estão; cada arquivo e pasta movidos avança sua revisão. Mover arquivos altera o que os seletores by:folder de suas pastas antiga e nova reproduzem, a partir da próxima resolução do seletor de cada tela; mover uma pasta não altera os arquivos próprios de nenhuma pasta. Emite media.moved.

Um movimento de credencial Propose torna cada arquivo movido pendente e enfileira sua revisão de mídia, e os seletores de playlists aprovadas o resolvem pela pasta com que foi aprovado até que uma pessoa aprove a mudança (docs/reviews.md).

Pré-visualização somente leitura das correspondências atuais de imagem ou vídeo prontas do projeto. Retorna ordenação de nome de arquivo e política normalizada; reprodução aleatória embaralha a cada nova passagem no Player. Não avança cursores, concede conteúdo ou altera manifestos. Mais de 1024 correspondências retorna invalid_request.

Define ou limpa a(s) tag(s) do item de mídia. A alteração das tags por uma credencial Propose torna o item pendente e enfileira sua revisão de mídia; os seletores de playlists aprovadas o resolvem pelas tags com que foi aprovado até que uma pessoa aprove a mudança (docs/reviews.md). Um patch que mantém o mesmo conjunto de tags é aplicado e o item permanece aprovado.

Uma pessoa conectada define as tags de um item de mídia. tags é o conjunto novo completo, mantido ordenado: a tag única de um item, quando existe, conta como uma de suas tags e é substituída pelas demais, então envie-a novamente para mantê-la. Um array vazio limpa todas as tags, e uma tag malformada ou repetida, ou mais de 32, é invalid_request.

É a alteração de tag que patchMedia faz sob uma credencial Manage, na sessão do painel: a revisão da mídia avança uma unidade e media.updated carrega a pessoa como ator, independentemente de o conjunto ter mudado. A mudança de uma pessoa é ao vivo, nunca uma revisão.

Mídia aguardando revisão humana (review_state pendente, deixada por upload ou alteração de credencial Propose) é recusada com media_pending_review (409) e nada muda: decida a revisão em Revisões primeiro, para que uma edição de tag nunca aprove uma proposta de agente. Seletores de playlist por tag observam as novas tags na próxima atualização do loop da playlist.

O corpo não tem outro membro. If-Match carrega a revisão da mídia e é obrigatório (invalid_request quando ausente, revision_conflict quando obsoleto). Apenas sessão do dashboard; agentes alteram tags com patchMedia. listMedia com tag encontra o item por suas novas tags.

Define quando um item de mídia pode ser escolhido pelos seletores dinâmicos (all, tag e folder) que o reproduzem, ou remove a regra com availability null. A regra é a da programação: from e until (civis, precisão de minuto, until exclusivo), ocorrências windows, monthly e dates e datas except, lidos no fuso horário de cada tela que resolve o seletor.

Um arquivo fora de sua regra é deixado de fora da seleção no próximo limite do loop da playlist e volta quando a regra vigora de novo; o limite de uma janela é seguido em até um minuto após o próximo loop do Player. Nenhuma revisão da playlist ou do manifesto muda. IDs explícitos (seletor por id ou ids) ignoram a regra, assim como tudo o que não é um seletor dinâmico.

Uma tela offline mantém sua última seleção até se reconectar. Definir a regra que o item já tem não muda nada. Uma credencial Propose não pode defini-la (insufficient_access): quando a mídia é reproduzida é decisão de uma pessoa com acesso Manage. Mídia aguardando a revisão de uma pessoa é recusada com media_pending_review.

If-Match carrega a revisão da mídia e é obrigatório.

Substitui no local o arquivo de um item de mídia pronto por um upload declarado (createMediaUpload) cujos bytes foram gravados, em vez de confirmá-lo como nova mídia.

A mídia mantém o seu id, de modo que cada playlist e cada agendamento que a cita reproduz o novo arquivo sem ser reagendado, e os seletores de pasta, tag e todas as mídias que a escolhem passam a reproduzi-lo na próxima resolução. A substituição deve ser do mesmo tipo de arquivo (imagem por imagem, vídeo por vídeo, áudio por áudio); outro tipo resulta em invalid_request.

Uma mudança de proporção é permitida: o resultado da operação traz uma entrada warnings aspect_ratio_changed com as playlists que usam o item. Todas as regras de upload se aplicam (o limite de bytes de vídeo do plano, os limites de dimensão e a cota de armazenamento).

O arquivo em uso permanece no histórico de versões da mídia (listMediaVersions) e conta nos bytes armazenados até a sua versão ser excluída. If-Match, quando enviado, é a revisão da mídia lida pelo chamador (revision_conflict quando desatualizada).

A resposta é a operação do upload, como em commitMediaUpload: consulte getOperation; o resultado de uma operação bem-sucedida é {media_id, id, version, warnings}. Bytes idênticos ao arquivo em uso não substituem nada e fazem a operação falhar com resource_conflict.

Com Propose efetivo, a substituição aguarda revisão: a operação é bem-sucedida com result.status pending_review e result.review_id, a mídia continua reproduzindo o seu arquivo até uma pessoa aprovar, e uma substituição mais recente da mesma mídia substitui a que espera.

Lista as versões de um item de mídia, da mais recente para a mais antiga, com a versão em uso primeiro (current: true). Uma versão é um arquivo que o item já teve: number é a sua época de conteúdo mais um (1 para o upload, mais um a cada substituição, restauração ou alteração da sincronização da mídia), e os bytes são mantidos até a versão ser excluída.

Leia os bytes de uma versão com GET /api/media/{id}/content?version=N.

Remove uma versão anterior: o registro some, os bytes saem de imediato dos bytes armazenados do projeto e o objeto é removido após 24 horas, a menos que outra versão ou a versão em uso mantenha o mesmo arquivo. A versão em uso não pode ser excluída (resource_conflict), e nenhuma versão pode ser excluída enquanto uma substituição da mídia aguarda revisão.

Uma versão excluída não pode ser restaurada.

Coloca uma versão anterior de volta em uso como nova versão, na próxima época de conteúdo da mídia: a mídia mantém o seu id e a revisão avança uma unidade, de modo que cada playlist e cada agendamento que a cita volta a reproduzir esse arquivo sem ser reagendado. A versão copiada permanece no histórico e compartilha os bytes; a nova versão conta nos bytes armazenados como qualquer outra.

A versão em uso não pode ser restaurada (resource_conflict). If-Match, quando enviado, é a revisão da mídia lida pelo chamador. O corpo pode trazer uma nota. Com Propose efetivo, a restauração vira uma revisão: 202 pending_review, e a mídia mantém o seu arquivo até uma pessoa aprovar.

Exporta a versão imutável original pertencente ao projeto autenticado. O portador do projeto é cobrado o crédito normal da solicitação API autenticada, e os bytes de resposta completos são registrados como egressos project_media_export. O identificador de mídia nunca é authority: o identificador de outro projeto retorna not_found.

A API transmite a partir do armazenamento privado e nunca publica uma chave de objeto, URL de armazenamento ou GET assinado. O nome do arquivo do anexo é o identificador da mídia mais a extensão canônica para o tipo de conteúdo verificado. A leitura de conteúdo nunca é recusada por causa do saldo.

Uma sessão do painel visualiza os mesmos bytes inline: bytes concluídos são registrados como dashboard_media egress, e a resposta é privada, no-cache para que o navegador mantenha uma cópia e a revalide com If-None-Match. A resposta de um portador de projeto permanece privada, no-store.

Aplica as mesmas regras de propriedade do projeto, condicionais, intervalo e armazenamento privado que exportMediaContent sem abrir ou transferir a versão armazenada.

Lists the project's media sync accounts, newest first (200 per page; next_cursor continues). Each shows its tenant and client id, its state and its last test; the client secret is never returned, only whether one is set and its last four characters.

Adiciona uma conta que sincroniza por leitura. kind microsoft365 armazena as credenciais do próprio aplicativo do Microsoft Entra do projeto, para que as sincronizações possam ler uma pasta do SharePoint ou do OneDrive for Business: config.tenant_id é o ID do diretório ou o domínio primário do tenant (common, organizations e consumers são recusados), config.client_id o ID do aplicativo, e secret o valor de um dos segredos de cliente do aplicativo; o aplicativo precisa da permissão de aplicativo Sites.Selected do Microsoft Graph (concedida em cada site) ou Files.Read.All, com consentimento do administrador.

Em vez desses três, config.connection_id nomeia uma conexão da Microsoft do projeto (createConnection), em qualquer um dos dois modos, que faz login e guarda o segredo. kind canva só aceita um nome: a conta fica em pending_consent e a resposta traz authorize_url, um link de uso único (válido até authorize_expires_at) que a pessoa dona da conta do Canva abre, logada no Canva, para conectá-la pela integração do Canva do screenRIG.

A concessão pertence ao projeto, então as sincronizações dela duram mais que a pessoa que a conectou.

Um servidor sem a integração com o Canva responde 409 canva_not_configured. kind dropbox funciona como canva: a conta fica em pending_consent e authorize_url é um link de uso único que a pessoa dona da conta do Dropbox abre, logada no Dropbox, para permitir acesso somente leitura (files.metadata.read, files.content.read, account_info.read, sharing.read).

A autorização passa pelo aplicativo do Dropbox do screenRIG, ou pelo aplicativo do Dropbox do próprio cliente quando config.app_key o nomeia (PKCE, então sem segredo do aplicativo; o aplicativo precisa listar https://API_ORIGIN/api/dropbox/callback como URI de redirecionamento).

Um servidor sem o aplicativo do Dropbox do screenRIG responde 409 dropbox_not_configured a uma conta dropbox sem app_key. kind google_drive fica em ready de imediato e lê as pastas compartilhadas com config.service_account_email: a conta de serviço do screenRIG ou a própria do cliente, quando secret é a chave JSON dessa conta de serviço.

Uma pasta compartilhada com a conta de serviço do screenRIG só sincroniza quando um membro do projeto com e-mail verificado a compartilhou ou é o proprietário dela. Um servidor sem a conta de serviço do screenRIG responde 409 google_drive_not_configured a uma conta google_drive sem chave. Um segredo é selado em repouso e nunca é devolvido nem registrado em log. Adiciona media_sync_account.created.

Uma nova tentativa exata com a mesma Idempotency-Key devolve a mesma conta (uma nova tentativa para uma conta do Canva ou do Dropbox recebe um novo link).

Uma conta de sincronização de mídia, com o segredo mascarado.

Changes the name, tenant, client id or secret; an omitted secret keeps the stored one. A change of credentials discards the last test. A Canva account takes only a name; media sync account connect renews its connection. Appends media_sync_account.updated. If-Match guards the revision.

Deletes the account. Refused 409 resource_conflict while a sync reads through it; the detail names those syncs. Deleting a Canva account also revokes its tokens at Canva (a failure to revoke is logged and does not undo the delete). Appends media_sync_account.deleted. If-Match guards the revision.

Signs in with the account's app and reports what Microsoft granted it: whether the credentials work and which Graph application permissions the token carries (Sites.Selected, Files.Read.All and the like). Sites.Selected is reported with a warning, because each site needs a grant for the app.

For a Canva account it reports whether Canva still accepts the connection. It does not judge a site's grant, a folder or a design, or consent beyond what the token carries. The result is stored as last_test. A failed check is ok false in the answer, not a problem.

Gera um novo link de consentimento de uso único (authorize_url, válido até authorize_expires_at) para uma conta do Canva ou do Dropbox, para enviar à pessoa dona dessa conta; ela o abre logada no Canva ou no Dropbox e permite o acesso. Ele substitui qualquer link anterior.

Uma conta conectada permanece conectada até que o novo consentimento seja concluído, então isto também renova uma conexão (estado reconnect_required) ou a move para outra conta do Canva ou do Dropbox. O link é uma credencial do consentimento: envie-o somente a essa pessoa.

Um servidor sem a integração com o Canva responde 409 canva_not_configured; uma conta do Dropbox sem app_key em um servidor sem o aplicativo do Dropbox do screenRIG responde 409 dropbox_not_configured.

Lists the Canva designs the connected person can see, most recently changed first (50 per page; continuation continues), optionally those matching query. Each shows its id, title, last change, page count and a view address. An account that is not connected is 409 canva_reconnect_required; a server without the Canva integration is 409 canva_not_configured.

Para onde o Canva envia a pessoa depois que ela permite (ou recusa) o acesso em um link de autorização.

It carries no credential: the one-time state in the query finds the Canva account, must be unexpired and is used once, in the same write that stores the connection. screenRIG exchanges the code (PKCE, client authentication with the integration's credentials), reads whose Canva account it is, seals the tokens and appends media_sync_account.connected.

The answer is a short page naming the account and the project it was connected to; an error, an unknown, expired or used state, or a refused code renders the same page with the reason and changes nothing. Answers only on the API host.

Para onde o Dropbox envia a pessoa depois que ela permite (ou recusa) o acesso em um link de consentimento.

Ela não leva nenhuma credencial: o state de uso único na consulta encontra a conta do Dropbox, não pode ter expirado e é usado uma vez, na mesma gravação que armazena a conexão. O screenRIG troca o código (PKCE, com o aplicativo do Dropbox do screenRIG ou o app_key próprio da conta), lê de quem é a conta do Dropbox, sela os tokens e adiciona media_sync_account.connected.

The answer is a short page naming the account and the project it was connected to; an error, an unknown, expired or used state, or a refused code renders the same page with the reason and changes nothing. Answers only on the API host.

Lists the project's media syncs, newest first (200 per page; next_cursor continues), optionally of one account_id or state. Each shows its source folder, the media folder it fills, its cadence, state, next run and the summary of its last run.

provider canva: lê o design (design é o id dele ou o endereço canva.com/design/ID/...) por uma conta do Canva conectada e armazena a sincronização, que vence agora.

Each run asks Canva for the design's last change and, when it moved, exports the pages (pages, default all; format png gives one image per page and mp4 one video) and imports them into the media folder, replacing the bytes of a page already imported under the same media id so the playlists that use it update; a page the design no longer has leaves play like a removed SharePoint file.

Um design que o Canva não mostra mais interrompe a sincronização no estado error (erro de execução design_unavailable) e mantém a mídia.

Um design ou página que a conta não consegue ver é 409 media_sync_source_refused. provider dropbox: url é o endereço da pasta no Dropbox (https://www.dropbox.com/home/...), um link de pasta compartilhada que a conta conectada adicionou ao seu Dropbox, ou um caminho que começa com /; ele é lido uma vez por meio de uma conta do Dropbox conectada e a sincronização é armazenada, com execução prevista para agora.

As pastas em um espaço de equipe são lidas a partir da raiz da equipe. Cada execução continua a partir da posição salva do Dropbox na pasta, então apenas as alterações são lidas.

Uma pasta que a conta não consegue abrir é 409 media_sync_source_refused; uma conta cuja conexão o Dropbox não honra mais é 409 dropbox_reconnect_required. provider google_drive: url é o endereço da pasta no Google Drive (https://drive.google.com/drive/folders/ID) ou o id dela, compartilhada (a função Viewer basta) com o service_account_email da conta.

Cada execução lista a pasta e compara o checksum de cada arquivo. Os arquivos do Google Docs, Sheets e Slides são ignorados como unsupported_type. Uma pasta que o endereço não consegue abrir é 409 media_sync_source_refused.

Pela conta de serviço do screenRIG, a pasta precisa ser compartilhada por um membro do projeto com e-mail verificado ou pertencer a ele (403 media_sync_sharer_not_member), e cada execução verifica isso de novo (o erro de execução sharer_not_member interrompe a sincronização no estado error). provider sharepoint: lê o endereço da pasta por meio da conta (um endereço de site do SharePoint como https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER, ou um link de compartilhamento; o aplicativo precisa conseguir vê-lo: Sites.Selected precisa de uma concessão no site, um link de compartilhamento precisa de Files.Read.All) e armazena a sincronização, com execução prevista para agora. folder_id é a pasta de mídia para onde os arquivos vão; sem ele, a sincronização cria uma com o nome da pasta de origem.

Each run imports the images (png, jpeg, webp, gif), videos (mp4, webm) and audio (mp3) directly in the source folder, replaces the bytes of a file that changed under the same media id so playlists that use it update, and takes a file removed at the source out of play: its media is deleted, or, while screens still hold it, moved to a Removed subfolder and deleted later.

Subfolders are ignored; other files are listed as skipped with the reason. every is the seconds between runs, 300 to 86400, default 900. A folder the provider refuses is 409 media_sync_source_refused and one it cannot reach is 500 media_sync_source_unavailable; nothing is stored. Appends media_sync.created.

Uma sincronização de mídia, com o resumo da última execução.

Changes the name, every (seconds between runs), state (active or paused; active also resumes a sync an error stopped) or folder_id. A new folder_id points the sync at another media folder and makes its next run read the whole source again, which puts every synced file there. Appends media_sync.updated. If-Match guards the revision.

Interrompe a sincronização e esquece qual arquivo de origem virou qual mídia. A mídia e a pasta dela permanecem. Registra media_sync.deleted. If-Match protege a revisão.

Faz a sincronização vencer agora e responde 202; um worker a executa em cerca de 30 segundos e a resposta de GET /api/media-syncs/{id} mostra o last_run dela.

Uma sincronização interrompida por erro volta a executar; uma sincronização pausada é recusada até ser retomada. force=true faz uma sincronização do Canva exportar o design mesmo quando o Canva o informa como inalterado (recusado para uma do SharePoint: ela já baixa todos os arquivos alterados).