Audio
Audio
POST /v1/audio/speech for text to speech and music, POST /v1/audio/transcriptions for speech to text.
Both endpoints take the OpenAI-compatible speech and transcription request bodies and return the matching responses. Speech and music models appear in the main catalog with audio in architecture.output_modalities.
Text to speech
POST /v1/audio/speech takes the standard speech body and returns audio bytes. Speech models are openai/gpt-audio-mini (fast) and openai/gpt-audio (higher quality); voices are alloy, ash, ballad, coral, echo, sage, shimmer and verse. The response is audio/wav (24 kHz mono); pass response_format: "pcm16" for the raw samples. instructions sets the delivery; by default the model reads the text verbatim.
curl --fail-with-body https://api.pre.dev/v1/audio/speech \
-H "Authorization: Bearer $PREDEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-audio-mini", "input": "Your build is ready.", "voice": "alloy"}' \
-o ready.wavimport fs from 'node:fs/promises';
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'https://api.pre.dev/v1', apiKey: process.env.PREDEV_API_KEY! });
const speech = await client.audio.speech.create({
model: 'openai/gpt-audio-mini',
input: 'Your build is ready.',
voice: 'alloy',
});
await fs.writeFile('ready.wav', Buffer.from(await speech.arrayBuffer()));import os
from openai import OpenAI
client = OpenAI(base_url="https://api.pre.dev/v1", api_key=os.environ["PREDEV_API_KEY"])
with client.audio.speech.with_streaming_response.create(
model="openai/gpt-audio-mini",
input="Your build is ready.",
voice="alloy",
) as speech:
speech.stream_to_file("ready.wav")In a web app, serve the bytes from your own route and point an <audio> element at it; the Content-Type header names the format. A model id that does not produce audio returns 400 with the list of ids that do.
Music
The same endpoint composes music: send model: "google/lyria-3-clip-preview" (or google/lyria-3-pro-preview) with input set to the mood or style you want, for example "upbeat lo-fi for a launch video". Music models answer with an MP3 (audio/mpeg); voice is ignored. The header x-predev-audio-format carries the format on every speech response.
Transcription
POST /v1/audio/transcriptions is multipart/form-data with a file part and a model field.
curl --fail-with-body https://api.pre.dev/v1/audio/transcriptions \
-H "Authorization: Bearer $PREDEV_API_KEY" \
-F "model=$TRANSCRIBE_MODEL" \
-F "file=@meeting.m4a"import fs from 'node:fs';
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'https://api.pre.dev/v1', apiKey: process.env.PREDEV_API_KEY! });
const transcript = await client.audio.transcriptions.create({
model: process.env.TRANSCRIBE_MODEL!,
file: fs.createReadStream('meeting.m4a'),
});
console.log(transcript.text);import os
from openai import OpenAI
client = OpenAI(base_url="https://api.pre.dev/v1", api_key=os.environ["PREDEV_API_KEY"])
with open("meeting.m4a", "rb") as audio:
transcript = client.audio.transcriptions.create(model=os.environ["TRANSCRIBE_MODEL"], file=audio)
print(transcript.text)Set TRANSCRIBE_MODEL to a speech-to-text model such as openai/whisper-large-v3. Transcription models are not listed by GET /v1/models. Speech, music, and transcription calls return the usual x-predev-* headers and are charged from the model’s metered usage.
curl --fail-with-body https://api.pre.dev/v1/audio/speech \ -H "Authorization: Bearer $PREDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "openai/gpt-audio-mini", "input": "Your build is ready.", "voice": "alloy"}' \ -o ready.wavimport osfrom openai import OpenAIclient = OpenAI(base_url="https://api.pre.dev/v1", api_key=os.environ["PREDEV_API_KEY"])with client.audio.speech.with_streaming_response.create( model="openai/gpt-audio-mini", input="Your build is ready.", voice="alloy",) as speech: speech.stream_to_file("ready.wav")import fs from 'node:fs/promises';import OpenAI from 'openai';const client = new OpenAI({ baseURL: 'https://api.pre.dev/v1', apiKey: process.env.PREDEV_API_KEY });const speech = await client.audio.speech.create({ model: 'openai/gpt-audio-mini', input: 'Your build is ready.', voice: 'alloy',});await fs.writeFile('ready.wav', Buffer.from(await speech.arrayBuffer()));package mainimport ( "fmt" "net/http" "io/ioutil" "strings")func main() { url := "https://api.pre.dev/v1/audio/speech" body := strings.NewReader(`{ "model": "openai/gpt-audio-mini", "input": "Your build is ready.", "voice": "alloy" }`) req, _ := http.NewRequest("POST", url, body) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body))}import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{ "model": "openai/gpt-audio-mini", "input": "Your build is ready.", "voice": "alloy"}""");HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder() .uri(URI.create("https://api.pre.dev/v1/audio/speech")) .header("Content-Type", "application/json") .POST(body) .build();try { HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString()); System.out.println("Status code: " + response.statusCode()); System.out.println("Response body: " + response.body());} catch (Exception e) { e.printStackTrace();}using System;using System.Net.Http;using System.Text;var body = new StringContent("""{ "model": "openai/gpt-audio-mini", "input": "Your build is ready.", "voice": "alloy"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.pre.dev/v1/audio/speech", body);var responseBody = await response.Content.ReadAsStringAsync();use reqwest::{Result, Client};async fn main() -> Result<()> { let client = Client::new(); let url = "https://api.pre.dev/v1/audio/speech"; let body = r#"{ "model": "openai/gpt-audio-mini", "input": "Your build is ready.", "voice": "alloy" }"#; let res = client .post(url) .header("Content-Type", "application/json") .body(body) .send() .await? .text() .await?; println!("{}", res); Ok(())}"string"The workspace API key (pdk_…) from Integrations → Built-in in the pre.dev dashboard.
In: header
Header Parameters
Attribute this call to one of the workspace's projects. An id the workspace does not own is ignored.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
The audio: audio/wav for speech, audio/mpeg for music, or application/octet-stream with raw PCM16 samples (24 kHz mono) when response_format is pcm16.
TypeScript Definitions
Use the response body type in TypeScript.
binaryapplication/json
model or input is missing, the model does not produce audio, or the body is not valid JSON.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
Missing or invalid API key.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
The workspace cannot pay for this request. Nothing was sent to the model and nothing was charged.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
The request refers to a file, response or video job that is not this workspace's (not_found from pre.dev; nothing ran and nothing was charged), or the model could not serve the request (its own status and message, in the ModelError shape).
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
Too many requests. Wait Retry-After seconds when it is present. A rate_limit_exceeded refusal is per workspace per minute (600, or 30 on the free trial). An error from the model keeps the ModelError shape.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
Unexpected error.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
The model did not answer or returned no audio.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.
application/json
The credit balance could not be read, so nothing ran. Retry after Retry-After seconds.
TypeScript Definitions
Use the response body type in TypeScript.
An error raised by pre.dev, in the OpenAI error shape with an extra predev object (absent on catalog_unavailable from the catalog listings). Branch on error.code.