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.
https://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=20import requests
response = requests.get(
"https://wbiztool.com/api/v1/media/list/",
params={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"file_type": "image",
"page": 1,
"limit": 20,
},
timeout=60,
)
result = response.json()
if result["status"] == 1:
data = result["data"]
print(f"Page {data['page']} of {data['total_pages']} ({data['total_count']} files)")
for media in data["media_files"]:
print(media["id"], media["original_file_name"], media["file_url"])
else:
print("Failed:", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({
client_id: "12345",
api_key: "YOUR_API_KEY",
file_type: "image",
page: "1",
limit: "20",
});
const response = await fetch(url);
const result = await response.json();
if (result.status === 1) {
const { data } = result;
console.log(`Page ${data.page} of ${data.total_pages} (${data.total_count} files)`);
for (const media of data.media_files) {
console.log(media.id, media.original_file_name, media.file_url);
}
} else {
console.error("Failed:", result.message);
}<?php
$query = http_build_query([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'file_type' => 'image',
'page' => 1,
'limit' => 20,
]);
$ch = curl_init('https://wbiztool.com/api/v1/media/list/?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
foreach ($result['data']['media_files'] as $media) {
echo $media['id'] . ' ' . $media['original_file_name'] . ' ' . $media['file_url'] . "\n";
}
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}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órioSeu ID do Cliente da API, em Configurações → Chaves API.
api_keystringobrigatórioSua chave de API, na mesma página.
Filtros e paginação
pageintegeropcionalNúmero da página, começando em
1(padrão). Valores abaixo de 1 são tratados como1.limitintegeropcionalArquivos por página, de 1 a 100. Padrão
20. Valores acima de 100 são tratados como100, e valores abaixo de 1, como20.file_typestringopcionalimagesomente para imagens, oufilepara todo o resto. Qualquer outro valor é ignorado.searchstringopcionalRetorna somente os arquivos cujo nome original ou nome armazenado contém este texto. Não diferencia maiúsculas de minúsculas.
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]"
}
]
}
}
| Campo | Tipo | Descrição |
|---|---|---|
status | integer | 1 em caso de sucesso, 0 se a requisição falhou. |
message | string | Media files retrieved successfully; caso contrário, o erro. |
data.total_count | integer | Arquivos que correspondem aos seus filtros, somando todas as páginas. |
data.page | integer | A página retornada. |
data.limit | integer | O tamanho de página usado, após o ajuste para o intervalo de 1 a 100. |
data.total_pages | integer | Número de páginas. 0 quando não há arquivos. |
data.has_next | boolean | true se houver uma página depois desta. |
data.has_previous | boolean | true se page for maior que 1. |
data.media_files | array | Os 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#
| Campo | Tipo | Descrição |
|---|---|---|
id | integer | ID do arquivo de mídia. Use-o com Obter arquivo de mídia. |
file_name | string | Nome com o qual o arquivo é armazenado. |
original_file_name | string | O nome que o arquivo tinha quando foi enviado. |
file_url | string | URL de download direto. Use-a como img_url ou file_url ao enviar. |
file_type | string | image ou file. |
file_size | integer | Tamanho em bytes. |
file_size_display | string | Tamanho legível com uma casa decimal, por exemplo 512.0 KB. |
mime_type | string | Tipo MIME, por exemplo image/jpeg. |
is_image | boolean | true quando file_type é image. |
file_extension | string | Extensão de original_file_name em minúsculas, sem o ponto. |
created_at | string | Horário do upload, em ISO 8601, em UTC, com deslocamento +00:00. |
uploaded_by | string ou null | Nome 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" }
| Mensagem | Como corrigir |
|---|---|
client_id is required | Adicione 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 required | Adicione api_key. |
client_id must be a valid integer | Envie client_id como número. |
Invalid API key | Verifique se a chave existe e não foi excluída nem desativada. |
Invalid client_id for this API key | A 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.
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")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const files = [];
let page = 1;
while (true) {
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({ client_id: "12345", api_key: "YOUR_API_KEY", page: String(page), limit: "100" });
const result = await (await fetch(url)).json();
if (result.status !== 1) throw new Error(result.message);
files.push(...result.data.media_files);
if (!result.data.has_next) break;
page += 1;
}
console.log(files.length, "files");Dicas#
- Use o parâmetro de envio certo: quando
is_imagefortrue, envie a URL comoimg_urlcommsg_type1; caso contrário, comofile_urlcommsg_type2. 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
POSTcom corpo JSON.
