Pular para o conteúdo
Wbiztool

API de mídia

API para listar arquivos de mídia

Obtenha os arquivos da biblioteca de mídia do seu espaço de trabalho com as URLs de download, dos mais recentes para os mais antigos. Filtre por tipo ou pesquise pelo nome para encontrar um arquivo enviado antes e reutilizar a URL dele em uma mensagem.

GEThttps://wbiztool.com/api/v1/media/list/

Corpo: Query string, ou corpo JSON com POST

A lista inclui arquivos enviados com a API de upload de mídia e pela página Diretório de Mídia. Arquivos excluídos não são incluídos.

Exemplo rápido#

curl -G https://wbiztool.com/api/v1/media/list/ \
  --data-urlencode client_id=12345 \
  --data-urlencode api_key=YOUR_API_KEY \
  --data-urlencode file_type=image \
  --data-urlencode page=1 \
  --data-urlencode limit=20

Substitua 12345 e YOUR_API_KEY pelos seus próprios valores. Veja em Autenticação onde encontrá-los.

Parâmetros da requisição#

Envie os parâmetros na query string de uma requisição GET, ou como corpo JSON em uma requisição POST com Content-Type: application/json. Não misture os dois: se client_id estiver na query string, o corpo JSON é ignorado. Um POST com campos de formulário também funciona para client_id, api_key, file_type e search, mas page e limit são ignorados em campos de formulário; envie-os na query string ou em JSON.

Autenticação

client_idintegerobrigatório

Seu ID do Cliente da API, em Configurações → Chaves API.

api_keystringobrigatório

Sua chave de API, na mesma página.

Filtros e paginação

pageintegeropcional

Número da página, começando em 1 (padrão). Valores abaixo de 1 são tratados como 1.

limitintegeropcional

Arquivos por página, de 1 a 100. Padrão 20. Valores acima de 100 são tratados como 100, e valores abaixo de 1, como 20.

file_typestringopcional

image somente para imagens, ou file para todo o resto. Qualquer outro valor é ignorado.

searchstringopcional

Retorna somente os arquivos cujo nome original ou nome armazenado contém este texto. Não diferencia maiúsculas de minúsculas.

POST com corpo JSONcURL
curl -X POST https://wbiztool.com/api/v1/media/list/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "search": "invoice",
    "page": 1,
    "limit": 50
  }'

Resposta#

{
  "status": 1,
  "message": "Media files retrieved successfully",
  "data": {
    "total_count": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "media_files": [
      {
        "id": 5123,
        "file_name": "media_12345_17895806123456.jpg",
        "original_file_name": "diwali-sale.jpg",
        "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456.jpg",
        "file_type": "image",
        "file_size": 524288,
        "file_size_display": "512.0 KB",
        "mime_type": "image/jpeg",
        "is_image": true,
        "file_extension": "jpg",
        "created_at": "2026-09-16T10:23:52.106447+00:00",
        "uploaded_by": "[email protected]"
      }
    ]
  }
}
CampoTipoDescrição
statusinteger1 em caso de sucesso, 0 se a requisição falhou.
messagestringMedia files retrieved successfully; caso contrário, o erro.
data.total_countintegerArquivos que correspondem aos seus filtros, somando todas as páginas.
data.pageintegerA página retornada.
data.limitintegerO tamanho de página usado, após o ajuste para o intervalo de 1 a 100.
data.total_pagesintegerNúmero de páginas. 0 quando não há arquivos.
data.has_nextbooleantrue se houver uma página depois desta.
data.has_previousbooleantrue se page for maior que 1.
data.media_filesarrayOs arquivos desta página, dos mais recentes para os mais antigos. Vazio se a página estiver além do fim.

Campos do arquivo de mídia#

CampoTipoDescrição
idintegerID do arquivo de mídia. Use-o com Obter arquivo de mídia.
file_namestringNome com o qual o arquivo é armazenado.
original_file_namestringO nome que o arquivo tinha quando foi enviado.
file_urlstringURL de download direto. Use-a como img_url ou file_url ao enviar.
file_typestringimage ou file.
file_sizeintegerTamanho em bytes.
file_size_displaystringTamanho legível com uma casa decimal, por exemplo 512.0 KB.
mime_typestringTipo MIME, por exemplo image/jpeg.
is_imagebooleantrue quando file_type é image.
file_extensionstringExtensão de original_file_name em minúsculas, sem o ponto.
created_atstringHorário do upload, em ISO 8601, em UTC, com deslocamento +00:00.
uploaded_bystring ou nullNome de usuário de login (geralmente o endereço de e-mail) do membro da equipe que enviou o arquivo.

Erros#

Os erros também retornam HTTP 200, com status igual a 0:

{ "status": 0, "message": "Invalid API key" }
MensagemComo corrigir
client_id is requiredAdicione client_id. Se você enviar JSON, verifique se o corpo é um JSON válido (um erro de análise é informado com esta mensagem).
api_key is requiredAdicione api_key.
client_id must be a valid integerEnvie client_id como número.
Invalid API keyVerifique se a chave existe e não foi excluída nem desativada.
Invalid client_id for this API keyA chave pertence a outro client_id.
Error retrieving media files: …Geralmente page ou limit na query string ou nos campos de formulário não é um número inteiro. Em um corpo JSON não há erro: se page não for um número inteiro, page, limit, file_type e search são todos ignorados, e você recebe a página 1 com 20 arquivos e sem filtros. Se só limit não for, limit, file_type e search são ignorados.

Ler todas as páginas#

Continue solicitando a próxima página enquanto data.has_next for true.

Obter todos os arquivos de mídia
import requests

files, page = [], 1

while True:
    result = requests.get(
        "https://wbiztool.com/api/v1/media/list/",
        params={"client_id": 12345, "api_key": "YOUR_API_KEY", "page": page, "limit": 100},
        timeout=60,
    ).json()
    if result["status"] != 1:
        raise RuntimeError(result["message"])

    files += result["data"]["media_files"]
    if not result["data"]["has_next"]:
        break
    page += 1

print(len(files), "files")

Dicas#

  • Use o parâmetro de envio certo: quando is_image for true, envie a URL como img_url com msg_type 1; caso contrário, como file_url com msg_type 2. Veja Enviar mensagem.
  • Mantenha sua chave de API fora dos logs: query strings costumam ser registradas por proxies e servidores. Se isso for importante para você, use POST com corpo JSON.