Saltar para o conteúdo principal
POST
Envie referências e receba uma URL pública diretamente em caso de sucesso, sem consultas periódicas. O upload é gratuito, mas o saldo da conta deve ser positivo. Os três endpoints compartilham uma cota por usuário: por padrão, 2000 arquivos em 72 horas.
O Playground da documentação não aceita uploads de arquivos. Use os exemplos cURL, Python ou JavaScript. O exemplo JavaScript exige um <input type="file"> com um arquivo selecionado.

Autenticação

string
obrigatório
Use uma APIMart API Key válida, habilitada e não expirada como Bearer <token>. A conta não pode estar suspensa e deve ter saldo positivo. Esgotar a cota própria da Key não impede uploads. Obtenha uma Key em Gerenciamento de API Keys.

Parâmetros da solicitação

file
obrigatório
Envie um arquivo com seu nome no campo file de uma solicitação multipart/form-data. Não substitua a parte do arquivo por JSON, string base64 ou URL. Outros campos são ignorados; se houver várias partes file, somente a primeira será processada.Formatos aceitos: MP3 (.mp3), WAV (.wav), M4A (.m4a)Tamanho máximo padrão: 15MB. Os limites de tamanho são configuráveis. Valem a configuração atual e o limite indicado na mensagem de erro.
Com cURL --form, Python files ou JavaScript FormData, deixe o cliente gerar Content-Type com a boundary. Não defina esse cabeçalho manualmente.

Validação de arquivos

O tipo é detectado pelo conteúdo, não pela extensão ou MIME informado. O conteúdo deve corresponder ao endpoint. Renomear não converte o formato; tipos incompatíveis retornam HTTP 400. A estrutura do contêiner ou dos quadros de áudio é validada. Cabeçalhos falsos e arquivos corrompidos são rejeitados. OGG, FLAC e AAC como fluxo ADTS bruto não são aceitos.

Resposta de sucesso

HTTP 200 retorna os dados do arquivo. url fica na raiz do JSON, sem objeto data envolvendo a resposta nem ID de tarefa de geração.
string
URL pública para o parâmetro de referência apropriado da API de geração. Cada modelo mantém seus limites de formato, tamanho, quantidade e duração. Upload bem-sucedido não garante compatibilidade com o modelo.
string
Nome original do arquivo.
string
Tipo MIME detectado pelo servidor a partir do conteúdo, não o declarado pelo cliente.
string
Categoria do arquivo. Este endpoint retorna audio.
integer
Tamanho real em bytes.
integer
Horário do upload como timestamp Unix em segundos.
object
Informações opcionais de cota. Os campos de usuários limitados estão abaixo. A estrutura pode variar para acesso ilimitado ou estatísticas indisponíveis.

Cota compartilhada e limites de requisições

Imagens, vídeos e áudios compartilham uma cota por usuário. Várias Keys do mesmo usuário não somam cota. A janela avança a cada hora cheia e conta, por padrão, os uploads bem-sucedidos das últimas 71–72 horas aproximadamente. Arquivos inválidos, grandes demais ou não armazenados não consomem cota de arquivos. Respostas limitadas comuns incluem X-Upload-Quota-Limit, X-Upload-Quota-Remaining e X-Upload-Quota-Reset, correspondentes a limit, remaining e reset_at. Reset está em segundos Unix. Usuários ilimitados recebem quota: {"unlimited": true} sem esses três cabeçalhos. Se as estatísticas estiverem indisponíveis, uma resposta de sucesso pode omitir quota. Não interprete a ausência como zero ou ilimitado, nem repita o upload apenas por esse motivo. Cota de arquivos esgotada retorna HTTP 429, error.type: rate_limit_exceeded, quota com remaining: 0 e Retry-After. Aguarde os segundos indicados. Há outro limite independente de 1000 requisições por Key a cada 60 segundos, identificado por rate_limit_error.

Tratamento de erros

Os erros ficam no objeto error na raiz do JSON. Verifique o status HTTP, error.type / error.code e error.message.

Uso das URLs e conservação

72 horas é a janela padrão da cota, não uma garantia de conservação dos arquivos. A duração depende da política de armazenamento. Preserve os originais e use as URLs prontamente na geração; não suponha que sejam permanentes.

Outros endpoints de upload