---
title: SDKs | RunAPI
description: Install a typed RunAPI SDK, authenticate it with an API key, and choose
  the right Task lifecycle for your application.
url: https://runapi.ai/docs/resources/sdks.md
canonical: https://runapi.ai/docs/resources/sdks
locale: en
---

> HTML version: https://runapi.ai/docs/resources/sdks
> Site index for agents: https://runapi.ai/llms.txt

# SDKs

RunAPI SDKs provide typed clients for supported model families in
JavaScript, Python, PHP, Java, Ruby, and Go. Choose the language package
for the model family your application calls.

## Install a model SDK

Install the package that matches your language and model family. For
example, install the Suno JavaScript SDK:

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

The same model family is available through the package manager for each
supported runtime:

```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/go@v0.4.4
```

For Java, add the Suno module with Gradle or Maven:

```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>
```

## Authenticate the client

Set `RUNAPI_API_KEY` in the environment before creating a client. The
SDK uses a RunAPI API key for the same account context as your REST
requests and CLI workflow.

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

Create and rotate keys in the [Authentication
Guide](https://runapi.ai/docs/guides/authentication.md). Keep keys in your secret manager
rather than application source code.

## Work with Files and Uploads

Every Provider Client exposes persistent `files` and multipart `uploads`
resources from its core package. The existing `files.create` method
still creates a temporary URL; use `files.createFile` in JavaScript,
Java, and PHP, `files.create_file` in Python and Ruby, or
`Files.CreateFile` in Go to create a persistent File object.

```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);
```

Use `uploads.create`, `addPart`, `complete`, and `cancel` when a request
is split into Parts. Python and Ruby use `add_part`; Go uses `AddPart`.
See [Files and Uploads](https://runapi.ai/docs/resources/files.md) for limits, REST
examples, and the complete lifecycle.

## Transcribe audio synchronously

The OpenAI Transcription SDK uploads a local audio file and returns the
completed transcription in the same request. JSON response formats
return a language-native object; text, SRT, and VTT formats return the
exact response string.

```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",
});
```

See the [Audio Transcription API
reference](https://runapi.ai/docs/api/openai-transcription/speech-to-text.md) for file
formats, model-specific fields, and response formats.

## Work with asynchronous Tasks

Many media operations are asynchronous. Use `create` to submit a Task
and receive its id immediately, `get` to retrieve its current state, or
`run` to submit and poll until it reaches a terminal state. In a web
request handler, prefer `create` plus a callback or later `get` polling
so the request does not hold a worker open.

### 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()
);
```

## Reuse a Style Persona

Create a Style Persona from a public audio URL, then reuse the returned
`persona.id` with the four supported music operations. `persona_type:
"style"` applies reusable genre and mood characteristics. It does not
guarantee cloning the source recording's voice, lossless preservation of
its style, or any particular similarity to the source audio.

```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,
});
```

## Choose the next workflow

Use an SDK when your application benefits from typed request builders
and language-native Task helpers. Use the [RunAPI
CLI](https://runapi.ai/docs/resources/cli.md) for shell automation, local checks, and
callback debugging. For exact request fields, Task responses, and
errors, use the [API Reference](https://runapi.ai/docs/api/openai/chat-completions.md).

---

## More from RunAPI

- [Home](https://runapi.ai/.md)
- [Model Catalog](https://runapi.ai/models.md)
- [Pricing](https://runapi.ai/pricing.md)
- [Providers](https://runapi.ai/models)
- [Documentation](https://runapi.ai/docs/guides)
- [SDKs](https://runapi.ai/sdk.md)
- [CLI](https://runapi.ai/cli.md)
- [MCP Server](https://runapi.ai/mcp.md)
- [Claude Code vs Cursor](https://runapi.ai/claude-code-vs-cursor.md)
- [Cursor API Setup](https://runapi.ai/cursor-api-setup.md)
- [RunAPI vs OpenRouter](https://runapi.ai/openrouter-alternative.md)
- [Enterprise](https://runapi.ai/contact.md)
- [Contact](https://runapi.ai/contact.md)
- [Terms](https://runapi.ai/terms.md)
- [Privacy](https://runapi.ai/privacy.md)
- [Site index for agents](https://runapi.ai/llms.txt)

Contact: contact@runapi.ai

## Structured data

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "en",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "en",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/icon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "en",
    "@type": "TechArticle",
    "headline": "SDKs",
    "description": "Install a typed RunAPI SDK, authenticate it with an API key, and choose the right Task lifecycle for your application.",
    "url": "https://runapi.ai/docs/resources/sdks",
    "mainEntityOfPage": "https://runapi.ai/docs/resources/sdks"
  }
]
```