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
}
}
Gestión de subidas
Subir audio
Sube audio MP3, WAV o M4A y obtén una URL pública para las API de generación. Límite predeterminado: 15MB por archivo.
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
}
}
Sube material de referencia y recibe directamente una URL pública al completarse, sin consultas periódicas. La subida es gratuita, pero el saldo de la cuenta debe ser positivo. Los tres endpoints comparten una cuota por usuario: 2000 archivos en 72 horas de forma predeterminada.
El Playground de la documentación no admite subidas de archivos. Usa los ejemplos cURL, Python o JavaScript. El ejemplo JavaScript requiere un
<input type="file"> con un archivo seleccionado.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
}
}
Autenticación
string
requerido
Usa una APIMart API Key válida, habilitada y no caducada como
Bearer <token>. La cuenta no debe estar suspendida y debe tener saldo positivo. Agotar la cuota propia de la Key no impide subir archivos. Consigue una Key en Gestión de API Keys.Parámetros de solicitud
file
requerido
Envía un archivo con su nombre en el campo
file de una solicitud multipart/form-data. No sustituyas la parte de archivo por JSON, una cadena base64 o una URL. Otros campos se ignoran; si envías varias partes file, solo se procesa la primera.Formatos admitidos: MP3 (.mp3), WAV (.wav), M4A (.m4a)Tamaño máximo predeterminado: 15MB. Los límites son configurables. Se aplica la configuración activa y el límite indicado en el mensaje de error.--form, Python files o JavaScript FormData, deja que el cliente genere Content-Type con su boundary. No establezcas esa cabecera manualmente.
Validación de archivos
El tipo se identifica por el contenido, no por la extensión ni el MIME declarado. El contenido debe coincidir con el endpoint. Cambiar el nombre no convierte el formato; un tipo incorrecto devuelve HTTP400.
Se valida la estructura del contenedor o de las tramas. Se rechazan cabeceras falsas y archivos dañados. No se admiten OGG, FLAC ni AAC como flujo ADTS sin contenedor adicional.
| Formato | Tipo MIME detectado |
|---|---|
| MP3 (.mp3) | audio/mpeg |
| WAV (.wav) | audio/wav |
| M4A (.m4a) | audio/mp4 |
Respuesta correcta
HTTP200 devuelve los datos del archivo. url está en la raíz JSON, sin envoltorio data ni ID de tarea de generación.
string
URL pública para el parámetro de referencia correspondiente de la API de generación. Cada modelo conserva sus límites de formato, tamaño, cantidad y duración. Una subida correcta no garantiza compatibilidad con el modelo.
string
Nombre original del archivo.
string
Tipo MIME detectado por el servidor a partir del contenido, no el valor declarado por el cliente.
string
Categoría del archivo. Este endpoint devuelve
audio.integer
Tamaño real en bytes.
integer
Fecha de subida como marca de tiempo Unix en segundos.
object
Información opcional de cuota. Los campos de usuarios con límite se enumeran abajo. La estructura puede variar si el acceso es ilimitado o las estadísticas no están disponibles.
| Campo | Descripción |
|---|---|
quota.limit | Máximo de subidas correctas para este usuario en la ventana; puede diferir de 2000. |
quota.used | Cantidad usada en la ventana, incluida esta subida correcta. |
quota.remaining | Número de archivos que aún se pueden subir actualmente. |
quota.window_hours | Duración de la ventana en horas; 72 de forma predeterminada. |
quota.reset_at | Momento en que el grupo más antiguo sale de la ventana, en segundos Unix. Se liberan algunas plazas; no implica un reinicio completo de la cuota. |
Cuota compartida y límites de solicitudes
Imágenes, vídeos y audios comparten una cuota por usuario. Varias Keys del mismo usuario no suman cuota. La ventana avanza a cada hora en punto y cuenta por defecto las subidas correctas de las últimas 71–72 horas aproximadamente. Los archivos inválidos, demasiado grandes o no guardados no consumen cuota de archivos. Las respuestas limitadas normales incluyenX-Upload-Quota-Limit, X-Upload-Quota-Remaining y X-Upload-Quota-Reset, correspondientes a limit, remaining y reset_at. Reset usa segundos Unix.
Los usuarios sin límite reciben quota: {"unlimited": true} sin esas tres cabeceras. Si las estadísticas no están disponibles, una respuesta correcta puede omitir quota. No interpretes esa ausencia como cero o ilimitado, ni vuelvas a subir el archivo solo por ello.
Al agotar la cuota de archivos se devuelve HTTP 429, error.type: rate_limit_exceeded, quota con remaining: 0 y Retry-After. Espera los segundos indicados. Existe otro límite independiente de 1000 solicitudes por Key cada 60 segundos, identificado por rate_limit_error.
Gestión de errores
Los errores aparecen en el objetoerror de la raíz JSON. Consulta el estado HTTP, error.type / error.code y error.message.
| HTTP | error.type | Causa y acción |
|---|---|---|
| 400 | invalid_request_error | Falta el archivo, la solicitud no es multipart, el archivo está vacío, el tipo no coincide, el formato no se admite o el contenido está dañado. Corrige el archivo o endpoint. |
| 401 / 403 | — | Key no válida o deshabilitada, o cuenta suspendida. Revisa la autenticación y la cuenta. |
| 402 | insufficient_user_quota | Saldo no positivo o Key caducada. Añade saldo o usa una Key válida. Las subidas gratuitas también requieren estas condiciones. |
| 413 | invalid_request_error | El archivo supera el límite de su tipo. Comprímelo o redúcelo; consulta el límite actual en el error. |
| 429 | rate_limit_exceeded | Cuota compartida agotada. Lee quota y Retry-After y espera a que se liberen plazas. |
| 429 | rate_limit_error | Demasiadas solicitudes de la Key. Reduce la frecuencia y espacia los reintentos. |
| 503 | server_error | Demasiadas subidas simultáneas de vídeo/audio o almacenamiento temporalmente no disponible. Reintenta más tarde. |
| 500 | server_error | No se pudo guardar el archivo. Reintenta más tarde. |