تخطَّ إلى المحتوى
موارد المطورين
موارد المطورين

حزم SDK

ثبّت RunAPI SDK مكتوباً بأنواع، وصادق عليه بمفتاح API، واختر دورة حياة المهمة المناسبة لتطبيقك.

توفر حزم RunAPI SDKs عملاء مكتوبين لعائلات النماذج المدعومة في JavaScript وPython وPHP وJava وRuby وGo. اختر حزمة اللغة المناسبة لعائلة النماذج التي يستدعيها تطبيقك.

تثبيت SDK نموذج

ثبّت الحزمة التي تتوافق مع لغتك وعائلة النموذج. على سبيل المثال، ثبّت Suno JavaScript SDK:

SHELL
npm install @runapi.ai/[email protected]

تتوفر عائلة النماذج ذاتها عبر مدير الحزم لكل وقت تشغيل مدعوم:

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]

في Java، أضف وحدة Suno باستخدام Gradle أو 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>

مصادقة العميل

عيِّن RUNAPI_API_KEY في البيئة قبل إنشاء عميل. تستخدم حزمة SDK مفتاح API الخاص بـ RunAPI لنفس سياق الحساب الخاص بطلبات REST وسير عمل CLI.

SHELL
export RUNAPI_API_KEY="runapi_..."

أنشئ المفاتيح ودوّرها في دليل المصادقة . احتفظ بالمفاتيح في مدير الأسرار الخاص بك بدلاً من الاحتفاظ بها في شيفرة المصدر للتطبيق.

العمل مع الملفات والتحميلات

يكشف كل Provider Client عن موارد files الدائمة وموارد uploads متعددة الأجزاء من حزمته الأساسية. لا يزال الأسلوب files.create الحالي يُنشئ عنوان URL مؤقتاً؛ استخدم files.createFile في JavaScript وJava وPHP، وfiles.create_file في Python وRuby، أو Files.CreateFile في Go لإنشاء كائن File دائم.

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

استخدم uploads.create وaddPart وcomplete وcancel عندما يكون الطلب مقسمًا إلى Parts. يستخدم Python وRuby add_part؛ ويستخدم Go AddPart. راجع Files and Uploads للاطلاع على الحدود والأمثلة بـ REST ودورة الحياة الكاملة.

نسخ الصوت بشكل متزامن

يرفع 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",
});

راجع مرجع Audio Transcription API للاطلاع على تنسيقات الملفات والحقول الخاصة بكل نموذج وتنسيقات الاستجابة.

العمل مع المهام غير المتزامنة

كثير من عمليات الوسائط غير متزامنة. استخدم create لإرسال مهمة واستقبال معرّفها فورًا، وget لاسترداد حالتها الحالية، أو run للإرسال والاستطلاع حتى تبلغ حالة نهائية. في معالج طلبات الويب، يُفضَّل استخدام create مع callback أو استطلاع 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

أنشئ 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,
});

اختر سير العمل التالي

استخدم SDK عندما تستفيد تطبيقاتك من منشئي الطلبات المكتوبة بأنواع ومساعدي Task الأصليين للغة. استخدم RunAPI CLI لأتمتة shell والفحوصات المحلية وتصحيح عمليات الاستدعاء. للاطلاع على حقول الطلب الدقيقة واستجابات Task والأخطاء، استخدم مرجع API.

Vidu Q4

توفر حزم Vidu تحويل الصورة إلى فيديو والإشارة إلى الفيديو الموارد مع مساعدي المهام في الإنشاء والاسترداد وغير المتزامنين. استخدم vidu-q4-image-to-video أو vidu-q4-reference-to-video لـ الموارد المقابلة. أسماء الحزم هي @runapi.ai/vidu لـ JavaScript، runapi-vidu لـ Python وRuby، runapi-ai/vidu لـ PHP، ai.runapi:runapi-vidu لـ Java و github.com/runapi-ai/vidu-sdk/go ل Go.

راجع المتطلبات الخاصة بالصور المرجعية وملفات MP3 في دليل واجهة برمجة تطبيقات المهام。 راجع أيضًا أسعار الصورة إلى الفيديو · أسعار المراجع إلى الفيديو。