---
title: SDK | RunAPI
description: 타입이 지정된 RunAPI SDK를 설치하고, API 키로 인증하고, 애플리케이션에 적합한 Task 수명 주기를 선택합니다.
url: https://runapi.ai/ko/docs/resources/sdks.md
canonical: https://runapi.ai/ko/docs/resources/sdks
locale: ko
---

> HTML 버전: https://runapi.ai/ko/docs/resources/sdks
> 에이전트용 사이트 색인: https://runapi.ai/llms.txt

# SDK

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

## 모델 SDK 설치

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

```shell
npm install @runapi.ai/suno@0.4.6
```

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

```shell
pip install runapi-suno==0.4.4
composer require runapi-ai/suno:0.3.2
gem install runapi-suno --version 0.4.4
go get github.com/runapi-ai/suno-sdk/go@v0.4.5
```

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

```kotlin
dependencies {
  implementation("ai.runapi:runapi-suno:0.3.3")
}
```

```xml
<dependency>
  <groupId>ai.runapi</groupId>
  <artifactId>runapi-suno</artifactId>
  <version>0.3.3</version>
</dependency>
```

## 클라이언트 인증

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

```shell
export RUNAPI_API_KEY="runapi_..."
```

[인증 가이드](https://runapi.ai/ko/docs/guides/authentication.md)에서 키를 생성하고 교체하세요. 키는 애플리케이션 소스 코드가 아닌 시크릿 매니저에 보관하세요.

## 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](https://runapi.ai/ko/docs/resources/files.md)를
참조하세요.

## 오디오 동기 전사

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 참조](https://runapi.ai/ko/docs/api/openai-transcription/speech-to-text.md)를 참고하세요.

## 비동기 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
<?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

```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](https://runapi.ai/ko/docs/resources/cli.md)를 사용하세요. 정확한 요청 필드, Task 응답, 오류에 대해서는
[API 참조](https://runapi.ai/ko/docs/api/openai/chat-completions.md)를 사용하세요.

---

## RunAPI의 더 많은 정보

- [홈](https://runapi.ai/ko/.md)
- [모델 카탈로그](https://runapi.ai/ko/models.md)
- [요금](https://runapi.ai/ko/pricing.md)
- [제공사](https://runapi.ai/ko/models)
- [문서](https://runapi.ai/ko/docs/guides)
- [SDK](https://runapi.ai/ko/sdk.md)
- [CLI](https://runapi.ai/ko/cli.md)
- [MCP Server](https://runapi.ai/ko/mcp.md)
- [Claude Code와 Cursor](https://runapi.ai/ko/claude-code-vs-cursor.md)
- [Cursor API 설정](https://runapi.ai/ko/cursor-api-setup.md)
- [RunAPI와 OpenRouter 비교](https://runapi.ai/ko/openrouter-alternative.md)
- [엔터프라이즈](https://runapi.ai/ko/contact.md)
- [문의](https://runapi.ai/ko/contact.md)
- [약관](https://runapi.ai/ko/terms.md)
- [개인정보](https://runapi.ai/ko/privacy.md)
- [에이전트용 사이트 색인](https://runapi.ai/llms.txt)

문의: contact@runapi.ai

## 구조화된 데이터

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "ko",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/ko",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/ko/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "ko",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/ko",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/koicon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "ko",
    "@type": "TechArticle",
    "headline": "SDK",
    "description": "타입이 지정된 RunAPI SDK를 설치하고, API 키로 인증하고, 애플리케이션에 적합한 Task 수명 주기를 선택합니다.",
    "url": "https://runapi.ai/ko/docs/resources/sdks",
    "mainEntityOfPage": "https://runapi.ai/ko/docs/resources/sdks"
  }
]
```