Audio chat and music
A spoken answer, a song, on one route.
1. Pick a music model
A music model makes one finished piece from a description. There is no music route: the piece comes from /v1/chat/completions, with modalities set to ["audio"]. Copy its model IDModel IDThe name a request calls a model by, lab/model, copied from Models.More on Models → from its page in Models and send it in model as it stands.
| Model | Makes |
|---|---|
google/lyria-3-pro-preview | a full song |
google/lyria-3-clip-preview | a clip of 30 seconds |
2. Describe the piece
Describe the piece in the user message: the style, the instruments, the length. Yacine wants music for the clothing shop in Oran that his Souk Bot answers for, and sends one line.
import base64
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "google/lyria-3-pro-preview"
PROMPT = "An upbeat raï track, brass and darbuka, two minutes."
request = urllib.request.Request(
ADDRESS,
data=json.dumps(
{
"model": MODEL,
"messages": [{"role": "user", "content": PROMPT}],
"modalities": ["audio"],
"audio": {"format": "mp3"},
}
).encode(),
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
answer = json.load(response)
audio = answer["choices"][0]["message"]["audio"]
with open("song.mp3", "wb") as f:
f.write(base64.b64decode(audio["data"]))
print(answer["usage"]["cost"])| You send | Holds |
|---|---|
model | a music model's ID: a song or a clip |
messages | the description of the piece |
modalities | ["audio"]: asks for a piece, not words |
audio.format | the container of the piece, such as mp3 |
Every field: Chat.
Without "modalities": ["audio"], a music model refuses the request.
3. Save what comes back
200, with the whole piece inside the answer. Decode audio.data from base64 and write it to a file, as the samples do.
| Field | Holds |
|---|---|
choices[0].message.audio.data | the piece, base64, in the format asked for |
choices[0].message.audio.file_id | the stored copy of the piece, kept in your files: Files and storage |
choices[0].message.audio.expires_at | when the provider drops its own copy; ours stays |
usage | cost: the charge, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →. Tokens may ride along; they are not the charge |
Two headers come back.
| Header | Holds |
|---|---|
X-Generation-Id | the request's receipt: Receipt |
X-Balance-Available | your balanceBalanceWhat you can spend, in DA.More on Balance and charges → after this charge, in µDAµDAA millionth of a DA: 1 DA = 1 000 000 µDA.More on Balance and charges → |
A spoken answer
The same route answers in a voice: a conversation with modalities set to ["text", "audio"], and audio.voice naming the voice. The reply's words come back in audio.transcript, beside the audio.
No model that answers in a voice is on sale now. To turn text you already have into an audio file, see Speech.
What it cost
One piece, one charge, in DA, from your balance once the piece is delivered. The model is the price: a song on one, a clip on the other. The description's length and the piece's length never move it. usage.cost carries the charge; the model's page in Models gives the price.
These charge nothing:
| Case | Charged |
|---|---|
| the generation fails | nothing |
a 200 with no audio | nothing |
| the stream is cut before the piece ends | nothing: a partial piece is not a piece |
Errors
The body says why.
| Status | When |
|---|---|
| 400 | model or messages is missing, or a field has the wrong type |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; error.metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60 |
| 404 | model is not a model on sale |
| 429 | the API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →'s own rate limit is reached (metadata.limit_source is key), or the provider is limiting its rate; Retry-After says how many seconds to wait |
| 502 | the model is down, or answered with nothing usable |
What to do on each: Errors and retries.
Last modified on