API d'envoi renforcé

Mis à jour le 2026-09-18 · équipe Suno-API

Description du point d'accès

L'envoi renforcé transmet un fichier audio local ; le système effectue le renforcement en arrière-plan et produit un morceau complet et lisible. L'appel d'envoi renvoie immédiatement les informations de la tâche, et le client interroge le point d'accès de consultation pour suivre l'avancement.

Point d'accès d'envoi : POST /api/music/enhanced-upload

Consultation d'une tâche : GET /api/music/enhanced-upload/:id

Annulation d'une tâche : POST /api/music/enhanced-upload/:id/cancel

Consultation de la liste : GET /api/music/enhanced-upload

Facturation : 10 ¥ par appel, prélevés à l'avance au tarif fixe de suno-enhanced-upload. Si la tâche échoue, ou est annulée pendant l'étape autorisée, le montant prélevé est remboursé automatiquement. Le montant réellement facturé suit la configuration tarifaire actuelle du back-office.

Déroulement des appels

1. Appelez POST /api/music/enhanced-upload pour envoyer le fichier audio.
2. Conservez le task_id renvoyé.
3. Appelez GET /api/music/enhanced-upload/:id pour consulter l'avancement et le résultat.
4. Une fois le rendu final Suno terminé, le service utilise le compte Suno lié à cette tâche pour appeler le point d'accès de téléchargement autorisé de Studio et écrit le MP3 dans le service média CN2.
5. La tâche ne passe à completed que lorsque l'actif CN2 est prêt ; c'est à ce moment que l'adresse audio CDN se lit dans audio_url de la réponse.

/api/forbidden est une adresse de remplacement qui peut apparaître dans les métadonnées de Suno Studio ; ce n'est pas une ressource lisible ni téléchargeable. Elle n'est jamais renvoyée au client et ne sert pas de preuve d'achèvement. Si le rendu est terminé mais que CN2 prépare encore, le point d'accès continue de renvoyer processing et ne renvoie pas audio_url ; le client doit continuer d'interroger et ne pas considérer l'adresse vide comme un échec.

Soumettre un envoi renforcé

Headers

Paramètres de formulaire

Exemple de requête

L'exemple ci-dessous reprend la même forme d'appel que lors de la validation en production, mais la clé d'API a été remplacée par un remplacement.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Réponse

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Consulter une tâche

Exemple de requête

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Exemple de réponse en cours de traitement

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Exemple de réponse terminée

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Annuler une tâche

L'annulation n'est possible que tant que la tâche et le workflow du backend sont encore à l'étape queued. Une fois la tâche en leasing, running, processing ou terminée, elle ne peut plus être annulée.

Exemple de requête

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Réponse

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Si la tâche a déjà commencé à être traitée, le point d'accès renvoie :

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Consulter la liste des tâches

Le point d'accès de liste ne renvoie que les tâches d'envoi renforcé de l'utilisateur auquel appartient la clé d'API actuelle ; les tâches de génération ordinaire, de cover et de prolongation ne s'y mélangent pas.

Paramètres de query

Exemple de requête

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Réponse

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Référence des champs de la réponse

Remarques

• Ce point d'accès ne prend actuellement en charge que l'envoi de fichier multipart ; file_url et file_base64 en JSON ne sont pas acceptés.
• Le fichier envoyé fait au maximum 80 Mo.
• Le point d'accès d'envoi est asynchrone : une réponse queued signifie que la tâche est en file d'attente, et non que l'audio est terminé.
• L'annulation ne concerne que les tâches qui n'ont pas encore commencé à être traitées ; une fois le traitement lancé, le workflow du compte de la plateforme n'est pas interrompu.
• N'exposez pas de vraies clés d'API dans le code client.

Lancer une reprise une fois l'envoi renforcé terminé

Une fois l'envoi renforcé terminé, vous pouvez utiliser le résultat comme clip source et appeler POST /api/music/generate-from-source pour lancer une reprise.

Attention : la reprise est un point d'accès synchrone — la commande n'est acceptée qu'à l'arrivée de la réponse, et les cas mesurés peuvent attendre jusqu'à environ 230 secondes. Réglez le timeout du client à 300 secondes ou plus, et ne réessayez pas juste après un timeout. Voir « Temps d'attente et réglage du timeout » dans la Présentation de la nouvelle API.

Interrogez d'abord GET /api/music/enhanced-upload/:id jusqu'à ce que task.status soit completed. À ce moment :

• task.song_id est l'ID réel du morceau et correspond au sourceClipId attendu par le point d'accès de reprise ;
• il est conseillé de passer task.audio_url comme sourceAudioUrl, pour que le serveur gère le cas où le clip source et le compte d'exécution diffèrent ;
• task.task_id n'est que l'ID de la tâche d'envoi renforcé et ne peut pas servir de sourceClipId ;
• pending:enhanced-upload:* est un ID de remplacement de l'étape de traitement et ne peut pas servir à une reprise.

Pour lancer la reprise, utilisez la même clé d'API que pour l'envoi renforcé et composez la requête selon la correspondance ci-dessous :

Les autres paramètres (paroles, style, titre, modèle) se remplissent selon l'API de cover à partir d'un clip source. Quand le point d'accès de reprise renvoie le nouveau clips[].song_id, utilisez POST /api/music/query pour consulter le statut de génération et l'audio final.