API Reference
Suno Convert-Audio
Use the convert audio endpoint to create an asynchronous Task.
01
Overview
Use the convert audio endpoint with the required inputs. Use the returned Task ID to retrieve its state, or provide callback_url for the deliveries documented below.
Quick start
- Create an API key and set it as RUNAPI_API_KEY.
- Send a POST request whose body matches the request schema.
- Store the returned task ID, then poll until a terminal state or handle the callbacks documented below.
Endpoint
- Base URL
https://runapi.ai- API version
v1- Authentication
Authorization: Bearer YOUR_API_TOKEN
02
Supported models
Open a model page for current pricing, rate limits, and commercial-usage details.
03
JSON bodyRequest schema
Send only the documented fields. When supplied, callback_url receives the Task deliveries documented below.
Request body3 fields
audio_idstring
Required
Audio ID within the source task.
callback_urlstring
Optional
Webhook URL for async notifications.
task_idstring
Required
Source task ID.
04
HTTP 202Create acceptance
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200Polling processing
GET /api/v1/suno/convert_audio/:id
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"wav_url": {
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200Polling completed
GET /api/v1/suno/convert_audio/:id
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"wav_url": {
"type": "string"
}
},
"required": [
"id",
"status",
"wav_url",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"wav_url": "https://file.runapi.ai/reference-audio.wav"
}07
HTTP 200Polling failed
GET /api/v1/suno/convert_audio/:id
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200Customer callback: completed
POST callback_url
Response schema
JSON
{
"properties": {
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"wav_url": {
"type": "string"
}
},
"required": [
"id",
"status",
"wav_url"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"id": "tsk_reference_demo",
"status": "completed",
"wav_url": "https://file.runapi.ai/reference-audio.wav"
}09
HTTP 200Customer callback: failed
POST callback_url
Response schema
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401Errors
POST /api/v1/suno/convert_audio
This response has no body.
11
HTTP 401Errors
GET /api/v1/suno/convert_audio/:id
This response has no body.
12
HTTP 400Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "task_id_is_required",
"message": "task_id is required"
}
}13
HTTP 402Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance"
}
}14
HTTP 403Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "api_token_credit_limit_exceeded",
"message": "API key credit limit exceeded"
}
}15
HTTP 409Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "request_conflict",
"message": "The request uses features that are not supported for the selected model"
}
}16
HTTP 429Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "rate_limited",
"message": "Rate limit reached. Please retry later."
}
}17
HTTP 503Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "service_unavailable",
"message": "Service under maintenance, please try again later"
}
}18
HTTP 504Errors
POST /api/v1/suno/convert_audio
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": {
"code": "timeout_error",
"message": "The request timed out"
}
}19
HTTP 404Errors
GET /api/v1/suno/convert_audio/:id
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "not_found",
"message": "Task with id 'tsk_reference_demo' not found"
}
}20
Generated Code Samples
Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference.
CURL
curl -X POST https://runapi.ai/api/v1/suno/convert_audio \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"task_id":"tsk_source_music","audio_id":"audio_reference"}'Install
BASH
npm install @runapi.ai/suno
JAVASCRIPT
import { SunoClient } from "@runapi.ai/suno";
const client = new SunoClient({ apiKey: process.env.RUNAPI_API_KEY });
const task = await client.convertAudio.create({
"task_id": "tsk_source_music",
"audio_id": "audio_reference"
});Install
BASH
pip install runapi-suno
PYTHON
import os
from runapi.suno import SunoClient
client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.convert_audio.create(
task_id="tsk_source_music",
audio_id="audio_reference"
)Install
BASH
go get github.com/runapi-ai/suno-sdk/go@latest
GO
package main
import (
"context"
"log"
"os"
"github.com/runapi-ai/core-sdk/go/option"
suno "github.com/runapi-ai/suno-sdk/go/suno"
)
func main() {
client, err := suno.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY")))
if err != nil {
log.Fatal(err)
}
task, err := client.ConvertAudio.Create(context.Background(), suno.ConvertAudioParams{
TaskID: "tsk_source_music",
AudioID: "audio_reference",
})
if err != nil {
log.Fatal(err)
}
_ = task
}Install
BASH
gem install runapi-suno
RUBY
require "runapi/suno"
client = RunApi::Suno::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY"))
task = client.convert_audio.create(
task_id: "tsk_source_music",
audio_id: "audio_reference"
)Install
KOTLIN
implementation("ai.runapi:runapi-suno")
JAVA
import ai.runapi.suno.SunoClient;
import ai.runapi.suno.types.ConvertAudioParams;
import ai.runapi.core.polling.TaskCreateResponse;
public final class Example {
public static void main(String[] args) {
SunoClient client = SunoClient.builder()
.apiKey(System.getenv("RUNAPI_API_KEY"))
.build();
TaskCreateResponse task = client.convertAudio().create(
ConvertAudioParams.builder()
.taskId("tsk_source_music")
.audioId("audio_reference")
.build()
);
}
}Install
BASH
composer require runapi-ai/suno
PHP
<?php
require __DIR__ . '/vendor/autoload.php';
use RunApi\Core\ClientOptions;
use RunApi\Suno\SunoClient;
$client = new SunoClient(new ClientOptions(apiKey: getenv('RUNAPI_API_KEY')));
$task = $client->convertAudio->create([
"task_id" => "tsk_source_music",
"audio_id" => "audio_reference"
]);