Yapay Zeka Ses Üretimi

Bir metin açıklamasından kısa müzik klipleri (30 saniyeye kadar) oluşturun. Platform, ses üretmek için Google Lyria'yı kullanıyor ve oluşturulan dosyaya zaman sınırlı bir URL döndürüyor.

İki giriş noktası mevcuttur:

Path	When to use
Chao tool (`media.audio.generate`)	Inside an AI chat session — let the model decide when to generate based on the conversation
REST API (`POST /ai/generative-media/context-runs`)	Direct, programmatic invocation — optionally enriched with personal context

Ses oluşturmak, etkin planda ai.audio.generate yetkisini gerektirir.

Chao Takım Yolu

Tanım

Bir oturuma kullanıcı mesajı gönderin. Niyet tespitini atlamak ve doğrudan ses oluşturma aracına yönlendirmek için "capabilityKey"i "ai.audio.generate" olarak ayarlayın.

Uç noktalar

Method	Path	Description	Auth	Rate Limit
POST	`/ai/sessions/:sessionId/messages`	Send a message that triggers audio generation	JWT + Entitlement	20/min
GET	`/ai/sessions/:sessionId/messages/:messageId/stream`	SSE stream of progress and completion events	JWT + Entitlement	20/min

Rica etmek

Talep Gövdesi

Field	Type	Required	Description
`content`	string	Yes	Free-text description of the music to generate
`capabilityKey`	string	Yes	Set to `ai.audio.generate`
`durationSeconds`	number	No	Target clip length in seconds (5–30). Default: 20. Clamped to 30; ignored if ≤ 0
`bpm`	number	No	Beats per minute (40–220). Clamped to range; omitted from the request if missing or ≤ 0
`styleTokens`	string[]	No	Genre, instrument, or mood hints (e.g. `["jazz", "piano", "late night"]`). Max 10 items
`effortMode`	string	No	`basic`, `thinking`, or `pro`
`idempotencyKey`	string	No	Client-generated key to deduplicate retries

Kimliği doğrulanmış istek aktöre bilgi sağlar. İstek gövdeleri hiçbir zaman "accountId", "chainerId" veya "workspaceId" içermemelidir.

Cevap

json

{
  "data": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "userMessage": {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "role": "user",
      "content": "A calm jazz piano piece for late-night focus sessions.",
      "createdAt": "2026-05-22T10:00:00Z",
      "toolCalls": []
    },
    "assistantMessage": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "role": "assistant",
      "content": "",
      "createdAt": "2026-05-22T10:00:00Z",
      "runId": "550e8400-e29b-41d4-a716-446655440012",
      "status": "pending",
      "toolCalls": [],
      "modelName": "Lyria",
      "providerKey": "google"
    },
    "run": {
      "id": "550e8400-e29b-41d4-a716-446655440012",
      "status": "running"
    }
  }
}

SSE Olay Sırası

text

event: run.started
event: tool.started      toolKey=media.audio.generate
event: tool.progress     message="Generating audio..."      activityType=audio_generation
event: tool.completed    toolKey=media.audio.generate  data={ audioUrl, durationSeconds, ... }
event: message.delta     (assistant prose summarising the result)
event: message.completed
event: run.settlement.completed

SSE — `tool.completed` Yükü

json

{
  "eventId": 4,
  "type": "tool.completed",
  "runId": "550e8400-e29b-41d4-a716-446655440012",
  "stepId": "tc_abc123",
  "timestamp": "2026-05-22T10:00:28Z",
  "payload": {
    "toolKey": "media.audio.generate",
    "callId": "tc_abc123",
    "executionMs": 22400,
    "success": true,
    "data": {
      "success": true,
      "audioUrl": "https://media.chainabit.com/ai-generated/audio/...wav",
      "durationSeconds": 20,
      "mimeType": "audio/wav"
    }
  }
}

Hata Yanıtları

HTTP	Meaning
400	Schema validation failed (e.g. `bpm` outside 40–220, `durationSeconds` > 30, sending image-capability fields like `aspectRatio`)
401	Missing or invalid JWT
402	Insufficient credits to reserve the requested duration
403	Plan does not include `ai.audio.generate`
404	`sessionId` not found
429	Rate limit exceeded

Yetenek farkındalığına sahip 400 örneği — ses özelliğine sahip bir görüntü alanı gönderme:

json

{
  "error": {
    "code": "bad_request",
    "message": "aspectRatio is only valid for ai.image.generate",
    "details": {
      "fields": [
        { "field": "aspectRatio", "message": "aspectRatio is only valid for ai.image.generate", "capabilityKey": "ai.image.generate" }
      ]
    }
  }
}

Parametreler ayrıca "parametreler" altında yuvalanmış olarak da gönderilebilir (yeni kod için tercih edilir) - bkz. Mesajlar: Yetenek Parametreleri.

Kod Örnekleri

Mesaj Gönderme

Oturum Oluştur yanıtındaki "id"yi "$SESSION_ID" olarak kullanın.

cURL — prompt onlycURL — with parametersJavaScriptPython

bash

curl -X POST "$BASE_URL/ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A calm jazz piano piece for late-night focus sessions.",
    "capabilityKey": "ai.audio.generate"
  }'

bash

curl -X POST "$BASE_URL/ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Upbeat pop background music for a workout video.",
    "capabilityKey": "ai.audio.generate",
    "durationSeconds": 25,
    "bpm": 128,
    "styleTokens": ["guitar", "synth", "energetic"]
  }'

javascript

const sessionId = process.env.SESSION_ID; // id of the AI session to send the message to

const res = await fetch(
  `${BASE_URL}/ai/sessions/${sessionId}/messages`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: "Ambient electronic music for deep focus.",
      capabilityKey: "ai.audio.generate",
      durationSeconds: 30,
      bpm: 80,
      styleTokens: ["ambient", "electronic", "minimal"],
    }),
  },
);
const { data } = await res.json();
const { assistantMessage, run } = data;
console.log("Run id:", run.id, "stream:", assistantMessage.id);

python

import os
import requests

session_id = os.environ["SESSION_ID"]  # id of the AI session to send the message to

res = requests.post(
    f"{BASE_URL}/ai/sessions/{session_id}/messages",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "content": "A cinematic orchestral piece with rising tension.",
        "capabilityKey": "ai.audio.generate",
        "durationSeconds": 20,
        "bpm": 90,
        "styleTokens": ["cinematic", "orchestral", "strings"],
    },
)
body = res.json()["data"]
assistant_id = body["assistantMessage"]["id"]
run_id = body["run"]["id"]

Yanıtın Akışı

Yukarıdakiyle aynı "$SESSION_ID"yi ve mesaj gönderme yanıtındaki "assistantMessage.id"yi ("data.assistantMessage.id") "$MESSAGE_ID" olarak kullanın.

JavaScript — EventSourcePython — sseclient

javascript

const sessionId = process.env.SESSION_ID; // same session used to send the message
const assistantId = process.env.MESSAGE_ID; // assistantMessage.id from the send-message response

const stream = new EventSource(
  `${BASE_URL}/ai/sessions/${sessionId}/messages/${assistantId}/stream`,
  { withCredentials: true },
);

stream.addEventListener("tool.progress", (event) => {
  const { payload } = JSON.parse(event.data);
  if (payload.activityType === "audio_generation") {
    console.log("progress:", payload.message);
  }
});

stream.addEventListener("tool.completed", (event) => {
  const { payload } = JSON.parse(event.data);
  if (payload.toolKey === "media.audio.generate") {
    console.log("Audio ready:", payload.data.audioUrl);
    stream.close();
  }
});

stream.addEventListener("run.settlement.completed", () => stream.close());

python

import os
import sseclient, requests, json

session_id = os.environ["SESSION_ID"]  # same session used to send the message
assistant_id = os.environ["MESSAGE_ID"]  # assistantMessage.id from the send-message response

response = requests.get(
    f"{BASE_URL}/ai/sessions/{session_id}/messages/{assistant_id}/stream",
    headers={"Authorization": f"Bearer {TOKEN}"},
    stream=True,
)
client = sseclient.SSEClient(response)
for event in client.events():
    if event.event == "tool.completed":
        payload = json.loads(event.data)["payload"]
        if payload["toolKey"] == "media.audio.generate":
            print("audio:", payload["data"]["audioUrl"])
            break

Doğrudan REST Yolu

Tanım

Programatik kontrol istediğinizde veya ses üretimini kişisel bağlamla (örneğin, kullanıcının Chainies'i veya belleği) birleştirmek istediğinizde 'POST /ai/generative-media/context-runs'ı kullanın.

http

POST /ai/generative-media/context-runs
Authorization: Bearer $TOKEN
Content-Type: application/json

'ai.contextMedia.generate' ve 'ai.audio.generate' gerektirir.

Rica etmek

Talep Gövdesi

Field	Type	Required	Description
`prompt`	string	Yes	Music description — max 4000 chars
`mediaType`	string	Yes	Must be `"audio"`
`generationMode`	string	No	`context_aware`, `prompt_only`
`requestedContextSources`	string[]	No	Personal context sources to include (see Generative Media API)
`durationSeconds`	number	No	1–30 seconds
`bpm`	number	No	40–220 BPM
`styleTokens`	string[]	No	Max 10 items, max 60 chars each. Merged with context-derived style tokens
`sessionId`	UUID	No	Links the generation job to a chat session
`providerPreference`	string	No	Override provider routing
`modelPreference`	string	No	Override model within the provider

Cevap

json

{
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440010",
    "status": "completed",
    "mediaType": "audio",
    "generationMode": "prompt_only",
    "permissionRequired": false,
    "allowedContextSources": [],
    "blockedContextSources": [],
    "resultMediaId": "550e8400-e29b-41d4-a716-446655440020",
    "errorCode": null,
    "createdAt": "2026-05-22T10:00:00Z",
    "updatedAt": "2026-05-22T10:00:25Z"
  }
}

Ses dosyasını Files API aracılığıyla almak için resultMediaIdyi kullanın.

İş Durumu Değerleri

Status	Meaning
`pending`	Job accepted, generation not yet started
`permission_required`	No consented context sources; proceed with `prompt_only` or grant permissions
`running`	Generation in progress
`completed`	Audio generated and stored; `resultMediaId` is set
`generation_failed`	Lyria returned an error or empty result
`storage_failed`	Generation succeeded but R2 upload failed
`cancelled`	Cancelled by the user

Hata Yanıtları

HTTP	Meaning
400	Validation failed — e.g. `bpm` not in 40–220, `styleTokens` item exceeds 60 chars
401	Missing or invalid JWT
403	Plan does not include `ai.contextMedia.generate` or `ai.audio.generate`
429	Rate limit exceeded

Kod Örnekleri

cURL — prompt onlycURL — with context and styleJavaScriptPython

bash

curl -X POST "$BASE_URL/ai/generative-media/context-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A reflective lo-fi hip hop beat for studying.",
    "mediaType": "audio",
    "generationMode": "prompt_only",
    "durationSeconds": 25
  }'

bash

curl -X POST "$BASE_URL/ai/generative-media/context-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create background music that fits my mood today.",
    "mediaType": "audio",
    "generationMode": "context_aware",
    "requestedContextSources": ["preferences", "chainies"],
    "durationSeconds": 20,
    "bpm": 90,
    "styleTokens": ["calm", "acoustic", "morning"]
  }'

javascript

const res = await fetch(`${BASE_URL}/ai/generative-media/context-runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "Upbeat electronic music for a productivity sprint.",
    mediaType: "audio",
    generationMode: "prompt_only",
    durationSeconds: 15,
    bpm: 120,
    styleTokens: ["electronic", "upbeat", "synth"],
  }),
});
const { data } = await res.json();
console.log("Job:", data.jobId, "Status:", data.status);
if (data.status === "completed") {
  // Fetch the presigned audio URL via the files API using data.resultMediaId
}

python

import requests

res = requests.post(
    f"{BASE_URL}/ai/generative-media/context-runs",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A jazz trio improvisation, late night bar setting.",
        "mediaType": "audio",
        "generationMode": "prompt_only",
        "durationSeconds": 30,
        "bpm": 75,
        "styleTokens": ["jazz", "piano", "bass", "brushed-drums"],
    },
)
data = res.json()["data"]
print(f"Job {data['jobId']}: {data['status']}")

Parametre Davranışı

Süre

Varsayılan: durationSeconds atlandığında 20 saniye.
Maksimum: 30 saniye. 30'un üzerindeki değerler 30'a sabitlenir.
Geçersiz: ≤ 0 değerleri (sıfır ve negatif sayılar dahil) varsayılana (20 s) geri döner.
Yanıtta döndürülen gerçek süre, modelin ürettiğini yansıtır; bu süre, istenen değerden biraz farklı olabilir. Faturalandırma fiili süreye göre hesaplanır.

BPM

Aralık: 40–220. Bu aralığın dışındaki değerler en yakın sınıra sabitlenir.
Geçersiz: Sayısal olmayan değerler, sıfır ve negatif sayılar, oluşturma isteğinden sessizce çıkarılır. Model kendi temposunu çıkarır.
BPM atlandığında Lyria, istem ve stil belirteçlerine uygun bir tempo seçer.

Stil Jetonları

Türü, enstrümanı veya ruh halini tanımlayan serbest biçimli dizeler (ör. "caz", "piyano", "sinematik", "iyimser"").
Ana istemin yanında ağırlıklı istemler olarak Lyria'ya aktarıldı.
Bağlama duyarlı REST yolunda, kullanıcı tarafından sağlanan belirteçler, kullanıcının kişisel verilerinden oluşturulan bağlamdan türetilen belirteçlerle birleştirilir. Kullanıcı jetonları eklenir ve eşit ağırlıktadır.
Hiçbir sözcük kısıtlaması geçerli değildir; uzunluk sınırına bağlı olarak herhangi bir dize kabul edilir (belirteç başına 60 karakter, REST yoluyla maksimum 10 belirteç; Chao araç şeması aracılığıyla örtülü olarak maksimum 10 belirteç).

Faturalandırma

Ses üretimi süreye göre faturalandırılır:

Birim: dakika (durationSaniye / 60)
Krediler, üretim isteği gönderilmeden önce rezerve edilir.
Krediler, Lyria tarafından döndürülen fiili süre (ya da Lyria rapor etmezse talep edilen süre) kullanılarak işlenir.
Üretimin ses üretmemesi durumunda, ayrılan krediler serbest bırakılır ve herhangi bir ücret uygulanmaz.

Davranış Notları

Geriye dönük uyumluluk: Herhangi bir isteğe bağlı parametre olmadan { content,abilityKey: "ai.audio.generate" } gönderimi tam olarak eskisi gibi çalışır. Tüm yapılandırılmış parametreler isteğe bağlıdır.
Depolama: Oluşturulan ses, çalışma alanının R2 klasörüne yüklenir ve zaman sınırlı, önceden imzalanmış bir URL olarak döndürülür. Orijinalin süresi dolduğunda Files API aracılığıyla yeni bir URL alın.
Boş sonuç: Lyria hiçbir ses parçası üretmezse, araç boş bir "audioUrl" ile "success: false" değerini döndürür. Hiçbir ücret uygulanmaz.
Onay kapısı: Chao aracı "Onay gerektirir: doğru"dur; bir sohbet oturumunda ses oluşturma işlemi yürütülmeden önce kullanıcının bunu onaylaması gerekir.

İlgili

AI Mesajları — tüm AI yetenekleri tarafından kullanılan genel mesaj / akış hattı.
AI Oturumları — bir nesil çalıştırmayı barındıran oturumu oluşturun.
Generative Media API — kaynak başına izin kontrollerine sahip tam bağlama duyarlı medya hattı.
AI Video Generation — video oluşturmaya yönelik eşdeğer belgeler.
Files API — oluşturulan medyayı "resultMediaId" ile alır.

Yapay Zeka Ses Üretimi ​

Chao Takım Yolu ​

Tanım ​

Uç noktalar ​

Rica etmek ​

Talep Gövdesi ​

Cevap ​

SSE Olay Sırası ​

SSE — tool.completed Yükü ​

Hata Yanıtları ​

Kod Örnekleri ​

Mesaj Gönderme ​

Yanıtın Akışı ​

Doğrudan REST Yolu ​

Tanım ​

Rica etmek ​

Talep Gövdesi ​

Cevap ​

İş Durumu Değerleri ​

Hata Yanıtları ​

Kod Örnekleri ​

Parametre Davranışı ​

Süre ​

BPM ​

Stil Jetonları ​

Faturalandırma ​

Davranış Notları ​

İlgili ​

Yapay Zeka Ses Üretimi

Chao Takım Yolu

Tanım

Uç noktalar

Rica etmek

Talep Gövdesi

Cevap

SSE Olay Sırası

SSE — `tool.completed` Yükü

Hata Yanıtları

Kod Örnekleri

Mesaj Gönderme

Yanıtın Akışı

Doğrudan REST Yolu

Tanım

Rica etmek

Talep Gövdesi

Cevap

İş Durumu Değerleri

Hata Yanıtları

Kod Örnekleri

Parametre Davranışı

Süre

BPM

Stil Jetonları

Faturalandırma

Davranış Notları

İlgili