Suno 공통 규약 및 작업 조회

curl --request GET \
  --url https://api.apimart.ai/v1/music/tasks/{task_id}

import requests

url = "https://api.apimart.ai/v1/music/tasks/{task_id}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.apimart.ai/v1/music/tasks/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apimart.ai/v1/music/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apimart.ai/v1/music/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.apimart.ai/v1/music/tasks/{task_id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apimart.ai/v1/music/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<track id, used with audio_index to locate it for subsequent operations>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}

GET

music

tasks

{task_id}

Suno 공통 규약 및 작업 조회

curl --request GET \
  --url https://api.apimart.ai/v1/music/tasks/{task_id}

import requests

url = "https://api.apimart.ai/v1/music/tasks/{task_id}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.apimart.ai/v1/music/tasks/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apimart.ai/v1/music/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apimart.ai/v1/music/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.apimart.ai/v1/music/tasks/{task_id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apimart.ai/v1/music/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<track id, used with audio_index to locate it for subsequent operations>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}

이 페이지는 모든 Suno 음악 API의 공통 규약이며, 각 엔드포인트의 개별 문서와 함께 사용합니다. 모든 생성 / 편집 API는 비동기 작업입니다: 제출하여 task_id를 받은 뒤, 이 페이지의 조회 API를 폴링하여 결과를 가져옵니다.

인증

모든 요청은 요청 헤더에 다음을 포함해야 합니다:

Authorization: Bearer <당신의 API Key>
Content-Type: application/json

API Key 관리 페이지에 접속하여 API Key를 발급받으세요.

작업 생명주기 (모든 API는 비동기)

제출

POST /v1/music/generations/<작업> → 즉시 당사의 task_id를 반환합니다:

{ "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }

폴링

GET /v1/music/tasks/:task_id를 status가 completed 또는 failed가 될 때까지 호출합니다. 생성 중에는 status가 pending이며, progress는 대기 10 → 준비 50 → 완료 100으로 진행됩니다. 폴링 간격은 3–5s를 권장하며, 음악 생성은 보통 30–120s가 걸립니다.

결과 가져오기

완료 후 data.result.music[]에서 audio_url / image_url / video_url 등을 가져옵니다.

작업 상태 전이: submitted → pending → completed / failed. 실패 시 data.error.message가 원인을 제공하며, 선차감된 크레딧이 자동으로 환불됩니다.

버전 version

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, 음질과 과금에 영향을 줍니다. 미전달 시 기본값을 사용합니다. 사용 가능한 버전과 기본값은 엔드포인트마다 다릅니다 — 일부 엔드포인트는 하위 집합만 지원하고, 일부 엔드포인트는 버전 차원이 없습니다. 각 엔드포인트의 자체 문서를 기준으로 하세요.

소스 오디오 트랙 참조: task_id + audio_index

기존 곡을 기반으로 하는 작업 (이어쓰기 / 커버 / 트랙 분리 / 보컬 추가 / 자르기…)은 어떤 업스트림 id도 기억할 필요 없이, 다음만 전달합니다:

task_id: 소스 오디오 트랙을 생성한 그 작업의 당사 task_id
audio_index: 해당 작업 결과 music[]에서 몇 번째 곡인지 (1부터 시작, 기본값 1; 한 번의 생성은 보통 2곡: 1과 2)

소스를 확인할 수 없는 경우 (작업 미완료 / 인덱스 범위 초과 / task_id 미존재) 제출 시점에 400을 반환합니다.

작업 조회: GET /v1/music/tasks/:task_id

task_id

string

필수

제출 API가 반환한 당사의 task_id.

이 API를 status가 completed 또는 failed가 될 때까지 폴링합니다. 완료 후 data.result.music[]에서 산출물을 가져옵니다.

Response

task_id

string

작업 고유 식별자

status

string

작업 상태: submitted / pending / completed / failed

progress

integer

진행률: 대기 10 → 준비 50 → 완료 100

data

object

결과 데이터

표시 속성

result

object

status가 completed일 때 존재

표시 result 속성

music

array

산출물 목록 (한 번의 생성은 보통 2곡)

표시 music[] 속성

audio_id

string

오디오 트랙 id, 이후 작업에서 audio_index로 위치를 지정하는 데 사용

title

string

제목

duration

number

재생 시간 (초)

lyrics

string

가사

개요

텍스트 시리즈

이미지 시리즈

비디오 시리즈

오디오 시리즈

모더레이션 시리즈

업로드 관리

작업 관리

계정 관리

Suno 공통 규약 및 작업 조회

인증

작업 생명주기 (모든 API는 비동기)

버전 version

소스 오디오 트랙 참조: task_id + audio_index

작업 조회: GET /v1/music/tasks/:task_id

Response

​인증

​작업 생명주기 (모든 API는 비동기)

​버전 version

​소스 오디오 트랙 참조: task_id + audio_index

​작업 조회: GET /v1/music/tasks/:task_id

​Response

인증

작업 생명주기 (모든 API는 비동기)

버전 version

소스 오디오 트랙 참조: task_id + audio_index

작업 조회: GET /v1/music/tasks/:task_id

Response