Recursos para Desenvolvedores

SDKs

Instale um SDK RunAPI tipado, autentique-o com uma Chave de API e escolha o ciclo de vida de Task adequado para sua aplicação.

Ver Markdown

Os SDKs do RunAPI fornecem clientes tipados para as famílias de modelos suportadas em JavaScript, Python, PHP, Java, Ruby e Go. Escolha o pacote de linguagem para a família de modelos que sua aplicação utiliza.

Instalar um SDK de modelo

Instale o pacote que corresponde ao seu idioma e família de modelos. Por exemplo, instale o SDK JavaScript do Suno:

SHELL

npm install @runapi.ai/[email protected]

A mesma família de modelos está disponível pelo gerenciador de pacotes para cada runtime suportado:

SHELL

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

Para Java, adicione o módulo Suno com Gradle ou Maven:

KOTLIN

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

XML

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

Autenticar o cliente

Defina RUNAPI_API_KEY no ambiente antes de criar um cliente. O SDK usa uma Chave de API do RunAPI para o mesmo contexto de conta que suas requisições REST e fluxo de trabalho CLI.

SHELL

export RUNAPI_API_KEY="runapi_..."

Crie e rotacione chaves no Guia de Autenticação. Mantenha as chaves no seu gerenciador de segredos em vez de no código-fonte da aplicação.

Trabalhar com Arquivos e Uploads

Cada Provider Client expõe recursos persistentes files e multipart uploads a partir do seu pacote principal. O método files.create existente ainda cria uma URL temporária; use files.createFile em JavaScript, Java e PHP, files.create_file em Python e Ruby, ou Files.CreateFile em Go para criar um objeto File persistente.

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 e cancel quando uma requisição for dividida em Parts. Python e Ruby usam add_part; Go usa AddPart. Consulte Files and Uploads para limites, exemplos REST e o ciclo de vida completo.

Transcrever áudio de forma síncrona

O SDK de Transcrição OpenAI envia um arquivo de áudio local e retorna a transcrição concluída na mesma requisição. Formatos de resposta JSON retornam um objeto nativo da linguagem; os formatos texto, SRT e VTT retornam a string de resposta exata.

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

Consulte a Referência da API de Transcrição de Áudio para formatos de arquivo, campos específicos por modelo e formatos de resposta.

Trabalhar com Tasks assíncronas

Muitas operações de mídia são assíncronas. Use create para enviar uma Task e receber seu id imediatamente, get para recuperar seu estado atual, ou run para enviar e aguardar até atingir um estado terminal. Em um handler de requisição web, prefira create com um callback ou polling posterior via get para que a requisição não mantenha um worker aberto.

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

Reutilizar uma Style Persona

Crie uma Style Persona a partir de uma URL de áudio pública e reutilize o persona.id retornado nas quatro operações de música suportadas. persona_type: "style" aplica características reutilizáveis de gênero e humor. Isso não garante a clonagem da voz da gravação de origem, a preservação sem perdas do seu estilo nem qualquer similaridade específica com o áudio de origem.

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

Escolher o próximo fluxo de trabalho

Use um SDK quando sua aplicação se beneficiar de construtores de requisição tipados e helpers de Task nativos da linguagem. Use a RunAPI CLI para automação em shell, verificações locais e depuração de Callbacks. Para campos exatos de requisição, respostas de Task e erros, use a Referência da API.

Vidu Q4

Os pacotes Vidu fornecem imagem para vídeo e referência para vídeo recursos com ajudantes de criação, recuperação e tarefas assíncronas. Usar vidu-q4-image-to-video ou vidu-q4-reference-to-video para o recurso correspondente. Os nomes dos pacotes são @runapi.ai/vidu para JavaScript, runapi-vidu para Python e Ruby, runapi-ai/vidu para PHP, ai.runapi:runapi-vidu para Java e github.com/runapi-ai/vidu-sdk/go para Go.

Consulte os requisitos de imagens de referência e MP3 no guia da API de tarefas。 Consulte também Preços de imagem para vídeo · Preços de referências para vídeo。