curl --request POST \
--url https://api.apimart.ai/v1/uploads/audios \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp3'
import requests
with open("reference.mp3", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/audios",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/audios", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp3",
"filename": "reference.mp3",
"content_type": "audio/mpeg",
"file_type": "audio",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "audio file exceeds maximum 15728640 bytes (15MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Gerenciamento de Upload
Enviar áudio
Envie áudio MP3, WAV ou M4A e receba uma URL pública para APIs de geração. Limite padrão: 15MB por arquivo.
POST
/
v1
/
uploads
/
audios
curl --request POST \
--url https://api.apimart.ai/v1/uploads/audios \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp3'
import requests
with open("reference.mp3", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/audios",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/audios", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp3",
"filename": "reference.mp3",
"content_type": "audio/mpeg",
"file_type": "audio",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "audio file exceeds maximum 15728640 bytes (15MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
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.curl --request POST \
--url https://api.apimart.ai/v1/uploads/audios \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp3'
import requests
with open("reference.mp3", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/audios",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/audios", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp3",
"filename": "reference.mp3",
"content_type": "audio/mpeg",
"file_type": "audio",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "audio file exceeds maximum 15728640 bytes (15MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
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.--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 HTTP400.
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.
| Formato | Tipo MIME detectado |
|---|---|
| MP3 (.mp3) | audio/mpeg |
| WAV (.wav) | audio/wav |
| M4A (.m4a) | audio/mp4 |
Resposta de sucesso
HTTP200 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.
| Campo | Descrição |
|---|---|
quota.limit | Máximo de uploads bem-sucedidos deste usuário na janela; pode diferir do padrão de 2000. |
quota.used | Quantidade usada na janela, incluindo este upload bem-sucedido. |
quota.remaining | Quantidade de arquivos que ainda podem ser enviados no momento. |
quota.window_hours | Duração da janela em horas; padrão 72. |
quota.reset_at | Momento em que o lote mais antigo sai da janela, em segundos Unix. Algumas vagas são liberadas; a cota inteira não necessariamente reinicia de uma vez. |
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 incluemX-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 objetoerror na raiz do JSON. Verifique o status HTTP, error.type / error.code e error.message.
| HTTP | error.type | Causa e ação |
|---|---|---|
| 400 | invalid_request_error | Arquivo ausente, solicitação sem multipart, arquivo vazio, tipo incorreto, formato incompatível ou conteúdo corrompido. Corrija o arquivo ou endpoint. |
| 401 / 403 | — | Key inválida ou desabilitada, ou conta suspensa. Verifique a autenticação e o status da conta. |
| 402 | insufficient_user_quota | Saldo não positivo ou Key expirada. Adicione saldo ou use uma Key válida. Uploads gratuitos também exigem essas condições. |
| 413 | invalid_request_error | Arquivo acima do limite do seu tipo. Comprima ou reduza o tamanho; consulte o limite atual no erro. |
| 429 | rate_limit_exceeded | Cota compartilhada esgotada. Leia quota e Retry-After e aguarde vagas disponíveis. |
| 429 | rate_limit_error | Requisições excessivas da Key. Reduza a frequência e aumente o intervalo entre tentativas. |
| 503 | server_error | Muitos uploads simultâneos de vídeo/áudio ou armazenamento temporariamente indisponível. Tente novamente mais tarde. |
| 500 | server_error | Falha ao gravar o arquivo. Tente novamente mais tarde. |