- Referencing source tracks: requires exactly 2, specified via
task_ids(an array of length 2) + optionalaudio_indexes - Async task: submitting returns a
task_id; pollGET /v1/music/tasks/:task_idfor the result
Referencing source tracks: mashup requires exactly 2 source tracks—specify them via task_ids (an array of exactly 2 of ythe task_ids), with optional audio_indexes (a parallel array selecting which item in each task's music[], 1-based, default 1 for both).
custom determines which fields take effect. All submitted fields must still meet their type, range, and length requirements, even when they do not take effect in the current mode. With custom=true, prompt (lyrics), title, tags, negative_tags, auto_lyrics, style_weight, weirdness, audio_weight, and persona_id take effect, while gpt_description is ignored. With custom=false, only gpt_description is used; it is required, and omitting it returns 400 during submission. vocal_gender takes effect in both modes. If custom is omitted, the backend infers it in this order: prompt present → true; no prompt but gpt_description present → false; otherwise, tags or title present → true.
Request example
curl -X POST https://api.openveer.com/v1/music/generations/mashup \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_ids": ["task_01ABC", "task_01DEF"],
"audio_indexes": [1, 2],
"custom": true,
"prompt": "upbeat mashup of the two tracks"
}'import requests
url = "https://api.openveer.com/v1/music/generations/mashup"
payload = {
"model": "suno",
"task_ids": ["task_01ABC", "task_01DEF"],
"audio_indexes": [1, 2],
"custom": True,
"prompt": "upbeat mashup of the two tracks"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = "https://api.openveer.com/v1/music/generations/mashup";
const payload = {
model: "suno",
task_ids: ["task_01ABC", "task_01DEF"],
audio_indexes: [1, 2],
custom: true,
prompt: "upbeat mashup of the two tracks"
};
const headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://api.openveer.com/v1/music/generations/mashup"
payload := map[string]interface{}{
"model": "suno",
"task_ids": []string{"task_01ABC", "task_01DEF"},
"audio_indexes": []int{1, 2},
"custom": true,
"prompt": "upbeat mashup of the two tracks",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer <token>")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class Main {
public static void main(String[] args) throws Exception {
String url = "https://api.openveer.com/v1/music/generations/mashup";
String payload = """
{
"model": "suno",
"task_ids": ["task_01ABC", "task_01DEF"],
"audio_indexes": [1, 2],
"custom": true,
"prompt": "upbeat mashup of the two tracks"
}
""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}<?php
$url = "https://api.openveer.com/v1/music/generations/mashup";
$payload = [
"model" => "suno",
"task_ids" => ["task_01ABC", "task_01DEF"],
"audio_indexes" => [1, 2],
"custom" => true,
"prompt" => "upbeat mashup of the two tracks"
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer <token>",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>require 'net/http'
require 'json'
require 'uri'
url = URI("https://api.openveer.com/v1/music/generations/mashup")
payload = {
model: "suno",
task_ids: ["task_01ABC", "task_01DEF"],
audio_indexes: [1, 2],
custom: true,
prompt: "upbeat mashup of the two tracks"
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = payload.to_json
response = http.request(request)
puts response.bodyimport Foundation
let url = URL(string: "https://api.openveer.com/v1/music/generations/mashup")!
let payload: [String: Any] = [
"model": "suno",
"task_ids": ["task_01ABC", "task_01DEF"],
"audio_indexes": [1, 2],
"custom": true,
"prompt": "upbeat mashup of the two tracks"
]
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try? JSONSerialization.data(withJSONObject: payload)
let task = URLSession.shared.dataTask(with: request) { data, response, error in
if let error = error {
print("Error: \(error)")
return
}
if let data = data, let responseString = String(data: data, encoding: .utf8) {
print(responseString)
}
}
task.resume()using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
var url = "https://api.openveer.com/v1/music/generations/mashup";
var payload = @"{
""model"": ""suno"",
""task_ids"": [""task_01ABC"", ""task_01DEF""],
""audio_indexes"": [1, 2],
""custom"": true,
""prompt"": ""upbeat mashup of the two tracks"""
}";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}#include <stdio.h>
#include <curl/curl.h>
int main(void) {
CURL *curl;
CURLcode res;
curl_global_init(CURL_GLOBAL_DEFAULT);
curl = curl_easy_init();
if(curl) {
const char *url = "https://api.openveer.com/v1/music/generations/mashup";
const char *payload = "{"
"\"model\":\"suno\","
"\"task_ids\":[\"task_01ABC\",\"task_01DEF\"],"
"\"audio_indexes\":[1,2],"
"\"custom\":true,"
"\"prompt\":\"upbeat mashup of the two tracks\""
"}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, url);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
res = curl_easy_perform(curl);
if(res != CURLE_OK) {
fprintf(stderr, "curl_easy_perform() failed: %s\n",
curl_easy_strerror(res));
}
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
curl_global_cleanup();
return 0;
}#import <Foundation/Foundation.h>
int main(int argc, const char * argv[]) {
@autoreleasepool {
NSURL *url = [NSURL URLWithString:@"https://api.openveer.com/v1/music/generations/mashup"];
NSDictionary *payload = @{
@"model": @"suno",
@"task_ids": @[@"task_01ABC", @"task_01DEF"],
@"audio_indexes": @[@1, @2],
@"custom": @YES,
@"prompt": @"upbeat mashup of the two tracks"
};
NSError *error;
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:payload
options:0
error:&error];
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
[request setHTTPMethod:@"POST"];
[request setValue:@"Bearer <token>" forHTTPHeaderField:@"Authorization"];
[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
[request setHTTPBody:jsonData];
NSURLSessionDataTask *task = [[NSURLSession sharedSession]
dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"Error: %@", error);
return;
}
NSString *result = [[NSString alloc] initWithData:data
encoding:NSUTF8StringEncoding];
NSLog(@"%@", result);
}];
[task resume];
[[NSRunLoop mainRunLoop] run];
}
return 0;
}(* Requires cohttp and yojson libraries *)
open Lwt
open Cohttp
open Cohttp_lwt_unix
let url = "https://api.openveer.com/v1/music/generations/mashup"
let payload = {|{
"model": "suno",
"task_ids": ["task_01ABC", "task_01DEF"],
"audio_indexes": [1, 2],
"custom": true,
"prompt": "upbeat mashup of the two tracks"
}|}
let () =
let headers = Header.init ()
|> fun h -> Header.add h "Authorization" "Bearer <token>"
|> fun h -> Header.add h "Content-Type" "application/json"
in
let body = Cohttp_lwt.Body.of_string payload in
let response = Client.post ~headers ~body (Uri.of_string url) >>= fun (resp, body) ->
body |> Cohttp_lwt.Body.to_string >|= fun body_str ->
print_endline body_str
in
Lwt_main.run responseimport 'dart:convert';
import 'package:http/http.dart' as http;
void main() async {
final url = Uri.parse('https://api.openveer.com/v1/music/generations/mashup');
final payload = {
'model': 'suno',
'task_ids': ['task_01ABC', 'task_01DEF'],
'audio_indexes': [1, 2],
'custom': true,
'prompt': 'upbeat mashup of the two tracks'
};
final response = await http.post(
url,
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json',
},
body: jsonEncode(payload),
);
print(response.body);
}library(httr)
library(jsonlite)
url <- "https://api.openveer.com/v1/music/generations/mashup"
payload <- list(
model = "suno",
task_ids = c("task_01ABC", "task_01DEF"),
audio_indexes = c(1, 2),
custom = TRUE,
prompt = "upbeat mashup of the two tracks"
)
response <- POST(
url,
add_headers(
Authorization = "Bearer <token>",
`Content-Type` = "application/json"
),
body = toJSON(payload, auto_unbox = TRUE),
encode = "raw"
)
cat(content(response, "text"))Response example
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}{
"error": {
"code": 400,
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"error": {
"code": 401,
"message": "Authentication failed, please check your API key",
"type": "authentication_error"
}
}{
"error": {
"code": 402,
"message": "Insufficient account balance, please top up and try again",
"type": "payment_required"
}
}{
"error": {
"code": 403,
"message": "Access forbidden, you do not have permission to access this resource",
"type": "permission_error"
}
}{
"error": {
"code": 429,
"message": "Too many requests, please try again later",
"type": "rate_limit_error"
}
}{
"error": {
"code": 500,
"message": "Internal server error, please try again later",
"type": "server_error"
}
}{
"error": {
"code": 502,
"message": "Gateway error, the server is temporarily unavailable",
"type": "bad_gateway"
}
}Authorizations
Authorization stringAll endpoints require authentication using a Bearer Token
Get an API Key:
Visit the API Key management page to get your API Key
Add the following to the request headers when using it:
Authorization: Bearer YOUR_API_KEYBody
model stringAudio model. Currently pass suno (defaults to suno if omitted).
task_ids string[]Array of ythe task_ids for the 2 source tracks (must be exactly 2; any other count returns 400 directly at submission time).
audio_indexes integer[]An array parallel to task_ids that selects a track from each task's data.result.music[] array (1-based; each entry defaults to 1).
instrumental booleanWhether purely instrumental (true=no vocals). If omitted, defaults to false (with vocals).
version stringPublic version: v6 / v6-wild / v6-mini. Defaults to v6; omit this field when using custom_model_id.
custom_model_id stringThe full UUID returned by the model-creation task. Mutually exclusive with version and persona_id.
custom booleantrue=custom mode (prompt used as lyrics); false=inspiration mode (uses gpt_description); if omitted, inferred from the content (see the Warning above).
prompt stringConditionally required: provide lyrics when custom=true && instrumental=false. The field is inactive in inspiration mode, but any submitted value must still meet the length limit.
gpt_description stringInspiration prompt. Required when custom=false — if missing, the request fails with 400 at submission (nothing is charged).
title stringTitle. Only takes effect when custom=true.
tags stringStyle tags. Only takes effect when custom=true.
negative_tags stringStyle tags to exclude. Only takes effect when custom=true.
auto_lyrics booleantrue=rewrite the provided lyrics creatively. Only takes effect when custom=true.
style_weight numberStyle weight, 0.00–1.00 (out-of-range values return 400 directly at submission time). Only takes effect when custom=true.
weirdness numberCreativity weight, from 0.00 to 1.00. weirdness_constraint is accepted as a legacy alias; use weirdness for new requests.
audio_weight numberAudio weight, 0.00–1.00. Only takes effect when custom=true.
vocal_gender stringVocal gender: Male / Female. Works in both modes.
persona_id stringPersona Style ID. Only applies when custom=true is used and mutually exclusive with custom_model_id.
variety stringStyle variation: off / normal / high / extra / max. Optional.
max_mode booleanEnables Max mode. Requires custom mode and is billed at twice the standard price.
audio_format stringOutput audio format: mp3 / m4a / wav. This endpoint does not support a target-duration field.
Get Result: This is an asynchronous task. After submission, you will receive task_id and then poll GET /v1/music/tasks/{task_id} every 3–5 seconds until status becomes completed or failed (music generation usually takes 30–120 seconds; while generation is in progress, status may be pending or processing, and progress is an integer from 0 to 100 and is not guaranteed to change at fixed intervals). Once completed, read audio_url from data.result.music[]. In case of failure, data.error.message provides the reason and the deducted amount will be automatically refunded.
Response
code integerResponse status code
data arraystatus stringTask status
* submitted - Submitted
task_id stringUnique task identifier (used to poll GET /v1/music/tasks/{task_id} for the result)
This documentation is built and hosted on Mintlify, a developer documentation platform.