개발자 리소스

SDK

타입이 지정된 RunAPI SDK를 설치하고, API 키로 인증하고, 애플리케이션에 적합한 Task 수명 주기를 선택합니다.

RunAPI SDK는 JavaScript, Python, PHP, Java, Ruby, Go로 지원되는 모델 패밀리에 대한 타입이 지정된 클라이언트를 제공합니다. 애플리케이션이 호출하는 모델 패밀리에 맞는 언어 패키지를 선택하세요.

모델 SDK 설치

언어 및 모델 패밀리에 맞는 패키지를 설치하세요. 예를 들어 Suno JavaScript SDK를 설치하려면:

SHELL

npm install @runapi.ai/[email protected]

동일한 모델 패밀리는 지원되는 각 런타임의 패키지 매니저를 통해서도 이용할 수 있습니다:

SHELL

pip install runapi-suno==0.4.3
composer require runapi-ai/suno:0.3.1
gem install runapi-suno --version 0.4.3
go get github.com/runapi-ai/suno-sdk/[email protected]

Java의 경우 Gradle 또는 Maven으로 Suno 모듈을 추가하세요:

KOTLIN

dependencies {
  implementation("ai.runapi:runapi-suno:0.3.2")
}

XML

<dependency>
  <groupId>ai.runapi</groupId>
  <artifactId>runapi-suno</artifactId>
  <version>0.3.2</version>
</dependency>

클라이언트 인증

클라이언트를 생성하기 전에 환경에서 RUNAPI_API_KEY를 설정하세요. SDK는 REST 요청 및 CLI 워크플로우와 동일한 계정 컨텍스트에 RunAPI API 키를 사용합니다.

SHELL

export RUNAPI_API_KEY="runapi_..."

인증 가이드에서 키를 생성하고 교체하세요. 키는 애플리케이션 소스 코드가 아닌 시크릿 매니저에 보관하세요.

Files 및 업로드 작업

모든 Provider Client는 핵심 패키지에서 영구적인 files와 멀티파트 uploads 리소스를 노출합니다. 기존 files.create 메서드는 여전히 임시 URL을 생성합니다. 영구 File 객체를 생성하려면 JavaScript, Java, PHP에서는 files.createFile을, Python과 Ruby에서는 files.create_file을, Go에서는 Files.CreateFile을 사용하세요.

JAVASCRIPT

const file = await client.files.createFile({
  file: new Blob([fileBytes], { type: "application/pdf" }),
  filename: "knowledge.pdf",
  purpose: "user_data",
});

const bytes = await client.files.content(file.id);
await client.files.deleteFile(file.id);

요청이 Part로 분할될 때 uploads.create, addPart, complete, cancel을 사용하세요. Python과 Ruby는 add_part를, Go는 AddPart를 사용합니다. 제한, REST 예제, 전체 수명 주기는 Files and Uploads를 참조하세요.

오디오 동기 전사

OpenAI Transcription SDK는 로컬 오디오 파일을 업로드하고 동일한 요청에서 완료된 전사를 반환합니다. JSON 응답 형식은 언어 네이티브 객체를 반환하고, text, SRT, VTT 형식은 정확한 응답 문자열을 반환합니다.

JAVASCRIPT

import { OpenaiTranscriptionClient } from "@runapi.ai/openai-transcription";

const client = new OpenaiTranscriptionClient();
const transcript = await client.speechToText.run({
  file: new Blob([audioBytes], { type: "audio/mpeg" }),
  filename: "interview.mp3",
  response_format: "json",
});

파일 형식, 모델별 필드, 응답 형식은 오디오 전사 API 참조를 참고하세요.

비동기 Task 작업

많은 미디어 작업은 비동기로 처리됩니다. create를 사용하여 Task를 제출하고 즉시 id를 받거나, get으로 현재 상태를 조회하거나, run으로 제출 후 종료 상태에 도달할 때까지 폴링하십시오. 웹 요청 핸들러에서는 작업자를 점유하지 않도록 create와 콜백 또는 이후 get 폴링을 조합하여 사용하는 것이 좋습니다.

JavaScript

JAVASCRIPT

import { SunoClient } from "@runapi.ai/suno";

const client = new SunoClient();
const result = await client.textToMusic.run({
  model: "suno-v5",
  vocal_mode: "auto_lyrics",
  prompt: "A short piano theme",
});

console.log(result.audios[0].audio_url);

Python

PYTHON

from runapi.suno import SunoClient

client = SunoClient()
result = client.text_to_music.run(
    model="suno-v4.5-plus",
    vocal_mode="auto_lyrics",
    prompt="A short piano theme",
)

print(result.audios[0].audio_url)

PHP

<?php

use RunApi\Suno\SunoClient;

$client = new SunoClient();
$result = $client->textToMusic->run([
    'model' => 'suno-v5.5',
    'vocal_mode' => 'auto_lyrics',
    'prompt' => 'A short piano theme',
]);

print_r($result->toArray());

Ruby

RUBY

require "runapi/suno"

client = RunApi::Suno::Client.new
result = client.text_to_music.run(
  model: "suno-v4.5-plus",
  vocal_mode: "auto_lyrics",
  prompt: "A short piano theme"
)

puts result.dig("audios", 0, "audio_url")

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/runapi-ai/core-sdk/go/option"
    "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)
    }

    result, err := client.TextToMusic.Run(context.Background(), suno.TextToMusicParams{
        SunoBaseParams: suno.SunoBaseParams{Model: suno.ModelV45Plus},
        VocalMode: suno.VocalModeAutoLyrics,
        Prompt:    "A short piano theme",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.ID)
}

Java

JAVA

import ai.runapi.suno.SunoClient;
import ai.runapi.suno.types.CompletedTextToMusicResponse;
import ai.runapi.suno.types.TextToMusicModel;
import ai.runapi.suno.types.TextToMusicParams;

SunoClient client = SunoClient.builder()
    .apiKey(System.getenv("RUNAPI_API_KEY"))
    .build();

CompletedTextToMusicResponse result = client.textToMusic().run(
    TextToMusicParams.builder()
        .model(TextToMusicModel.SUNO_V5)
        .vocalMode("auto_lyrics")
        .prompt("A short piano theme")
        .build()
);

Style Persona 재사용

공개 오디오 URL로 Style Persona를 생성한 후, 반환된 persona.id를 지원되는 네 가지 음악 작업에 재사용하세요. persona_type: "style"은 재사용 가능한 장르 및 분위기 특성을 적용합니다. 이는 소스 녹음의 음성을 클로닝하거나, 스타일을 무손실로 보존하거나, 소스 오디오와 특정 유사성을 보장하지 않습니다.

JAVASCRIPT

import { SunoClient } from "@runapi.ai/suno";

const client = new SunoClient();
const referenceAudioUrl = "https://cdn.runapi.ai/public/samples/music.mp3";

const sampled = await client.addSamples.run({
  model: "suno-v5",
  audio_url: referenceAudioUrl,
  start_seconds: 0,
  end_seconds: 30,
});
const sourceAudioId = sampled.audios?.[0]?.id;
if (!sourceAudioId) throw new Error("The sample Task did not return an audio ID");

const { persona } = await client.generatePersona.run({
  task_id: sampled.id,
  audio_id: sourceAudioId,
  name: "Studio Style",
  description: "A warm and expressive acoustic pop style.",
});
const textToMusic = await client.textToMusic.run({
  model: "suno-v5",
  vocal_mode: "auto_lyrics",
  prompt: "An uplifting acoustic pop song about a rainy city night",
  persona_id: persona.id,
  persona_type: "style",
});

const coverAudio = await client.coverAudio.run({
  model: "suno-v5",
  upload_url: referenceAudioUrl,
  vocal_mode: "auto_lyrics",
  prompt: "Rework the reference track as acoustic pop",
  persona_id: persona.id,
  persona_type: "style",
});

const createMashup = await client.createMashup.run({
  model: "suno-v5",
  upload_url_list: [
    referenceAudioUrl,
    "https://cdn.runapi.ai/public/samples/audio-2.mp3",
  ],
  vocal_mode: "auto_lyrics",
  prompt: "Blend both tracks into an energetic acoustic pop mashup",
  persona_id: persona.id,
  persona_type: "style",
});

const extendMusic = await client.extendMusic.run({
  model: "suno-v5",
  upload_url: referenceAudioUrl,
  parameter_mode: "custom",
  instrumental: false,
  prompt: "Continue the arrangement with a brighter chorus",
  style: "Acoustic pop with warm piano",
  title: "Brighter Chorus",
  continue_at: 60,
  persona_id: persona.id,
  persona_type: "style",
});

console.log({
  textToMusic: textToMusic.audios[0]?.audio_url,
  coverAudio: coverAudio.audios[0]?.audio_url,
  createMashup: createMashup.audios[0]?.audio_url,
  extendMusic: extendMusic.audios[0]?.audio_url,
});

다음 워크플로 선택

애플리케이션이 타입이 지정된 요청 빌더와 언어 기반 Task 헬퍼의 이점을 활용할 때는 SDK를 사용하세요. 셸 자동화, 로컬 점검, 콜백 디버깅에는 RunAPI CLI를 사용하세요. 정확한 요청 필드, Task 응답, 오류에 대해서는 API 참조를 사용하세요.