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
}
}
Gestion des uploads
Téléverser un fichier audio
Téléversez un fichier MP3, WAV ou M4A pour obtenir une URL publique destinée aux API de génération. Limite par défaut : 15MB par fichier.
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
}
}
Téléversez un média de référence et recevez directement son URL publique en cas de succès, sans suivi périodique. Le téléversement est gratuit, mais le solde du compte doit être positif. Les trois endpoints partagent un quota par utilisateur : 2000 fichiers sur 72 heures par défaut.
Le Playground de la documentation ne permet pas le téléversement. Utilisez les exemples cURL, Python ou JavaScript ci-dessous. L’exemple JavaScript nécessite un
<input type="file"> avec un fichier sélectionné.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
}
}
Authentification
string
requis
Utilisez une APIMart API Key valide, active et non expirée sous la forme
Bearer <token>. Le compte ne doit pas être suspendu et son solde doit être positif. Un quota propre à la Key épuisé n’empêche pas le téléversement. Obtenez une Key dans Gestion des API Keys.Paramètres de requête
file
requis
Envoyez un fichier avec son nom dans le champ
file d’une requête multipart/form-data. Ne remplacez pas cette partie par du JSON, une chaîne base64 ou une URL. Les autres champs sont ignorés ; si plusieurs parties file sont présentes, seule la première est traitée.Formats pris en charge: MP3 (.mp3), WAV (.wav), M4A (.m4a)Taille maximale par défaut: 15MB. Les limites de taille sont configurables. La configuration active et le message d’erreur de dépassement font référence.--form, Python files ou JavaScript FormData, laissez le client créer Content-Type avec sa boundary. Ne définissez pas cet en-tête manuellement.
Validation des fichiers
Le type est détecté à partir du contenu, pas de l’extension ou du MIME déclaré. Le contenu doit correspondre à l’endpoint. Renommer ne convertit pas un fichier ; un type incorrect renvoie HTTP400.
La structure du conteneur ou des trames audio est vérifiée. Les faux en-têtes et fichiers endommagés sont refusés. OGG, FLAC et AAC (flux ADTS brut) ne sont pas acceptés.
| Format | Type MIME détecté |
|---|---|
| MP3 (.mp3) | audio/mpeg |
| WAV (.wav) | audio/wav |
| M4A (.m4a) | audio/mp4 |
Réponse de succès
HTTP200 renvoie les informations du fichier. url est à la racine du JSON, sans enveloppe data ni identifiant de tâche de génération.
string
URL publique à passer au paramètre de référence approprié de l’API de génération. Les modèles conservent leurs propres limites de format, taille, nombre et durée. Un téléversement réussi ne garantit pas la compatibilité avec le modèle.
string
Nom d’origine du fichier.
string
Type MIME détecté par le serveur à partir du contenu, et non la valeur déclarée par le client.
string
Catégorie de fichier. Cet endpoint renvoie
audio.integer
Taille réelle en octets.
integer
Date de téléversement en secondes Unix.
object
Informations facultatives sur le quota. Les champs d’un utilisateur limité sont listés ci-dessous. La structure peut différer pour un accès illimité ou des statistiques indisponibles.
| Champ | Description |
|---|---|
quota.limit | Nombre maximal de téléversements réussis pour cet utilisateur dans la fenêtre ; peut différer de 2000. |
quota.used | Nombre utilisé dans la fenêtre, téléversement actuel inclus. |
quota.remaining | Nombre de fichiers encore téléversables actuellement. |
quota.window_hours | Durée de la fenêtre en heures, 72 par défaut. |
quota.reset_at | Instant où le lot le plus ancien sort de la fenêtre, en secondes Unix. Certaines places se libèrent ; le quota entier ne se réinitialise pas forcément d’un coup. |
Quota partagé et limites de requêtes
Images, vidéos et audios partagent un quota par utilisateur. Plusieurs Keys d’un même utilisateur n’ajoutent pas de quota. La fenêtre glisse à chaque heure pleine et compte par défaut les succès des dernières 71–72 heures environ. Les fichiers invalides, trop volumineux ou non enregistrés ne consomment pas ce quota. Les réponses limitées ordinaires incluentX-Upload-Quota-Limit, X-Upload-Quota-Remaining et X-Upload-Quota-Reset, correspondant à limit, remaining et reset_at. Reset est en secondes Unix.
Les utilisateurs illimités reçoivent quota: {"unlimited": true} sans ces trois en-têtes. Si les statistiques sont indisponibles, une réponse réussie peut omettre quota. Cette absence ne signifie ni zéro ni illimité ; ne téléversez pas de nouveau uniquement pour cette raison.
Un quota de fichiers épuisé renvoie HTTP 429, error.type: rate_limit_exceeded, quota avec remaining: 0 et Retry-After. Attendez le nombre de secondes indiqué. Une limite distincte de 1000 requêtes par Key sur 60 secondes utilise rate_limit_error.
Gestion des erreurs
Les erreurs se trouvent dans l’objeterror à la racine du JSON. Consultez le statut HTTP, error.type / error.code et error.message.
| HTTP | error.type | Cause et action |
|---|---|---|
| 400 | invalid_request_error | Fichier absent, requête non multipart, fichier vide, mauvais type, format non accepté ou contenu endommagé. Corrigez le fichier ou l’endpoint. |
| 401 / 403 | — | Key invalide ou désactivée, ou compte suspendu. Vérifiez l’authentification et le compte. |
| 402 | insufficient_user_quota | Solde non positif ou Key expirée. Rechargez le compte ou utilisez une Key valide. La gratuité ne dispense pas de ces conditions. |
| 413 | invalid_request_error | Fichier dépassant la limite de son type. Compressez ou réduisez-le ; consultez la limite actuelle dans l’erreur. |
| 429 | rate_limit_exceeded | Quota partagé épuisé. Lisez quota et Retry-After, puis attendez la libération de places. |
| 429 | rate_limit_error | Requêtes trop fréquentes pour la Key. Réduisez la fréquence et espacez les tentatives. |
| 503 | server_error | Trop de téléversements vidéo/audio simultanés ou stockage temporairement indisponible. Réessayez plus tard. |
| 500 | server_error | Échec d’enregistrement du fichier. Réessayez plus tard. |