API reference

Audio

Speech generation, transcription, and translation are separate operations. Match input media and output format to the selected model.

How it fits together

01Synthesize speech and return the audio bytes
02Transcribe an uploaded recording
03Translate an uploaded recording into English

Select an action to see its complete inputs, request, response, and status codes.

Synthesize speech and return the audio bytes

POST/v1/audio/speech

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`input`	Body	string	Required	Supported	Text to synthesize, bounded by service configuration.
`instructions`	Body	string	Optional	Conditional	Delivery instructions, up to 4,096 characters.
`model`	Body	string	Required	Supported	Public logical speech model ID.
`response_format`	Body	string	Optional	Supported	mp3, opus, aac, flac, wav, or pcm.
`speed`	Body	number	Optional	Conditional	Playback rate, 0.25 to 4.0.
`user`	Body	string	Optional	Supported	Provider abuse-monitoring user identifier.
`voice`	Body	string	Required	Supported	Provider voice identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/audio/speech' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "input": "probe",
  "model": "tts-1",
  "voice": "alloy"
}'

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
200	Synthesize speech and return the audio bytes.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.

Transcribe an uploaded recording

POST/v1/audio/transcriptions

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typemultipart/form-data

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`file`	Form	string (binary)	Required	Supported	The recording to process.
`language`	Form	string	Optional	Supported	ISO language hint, up to 16 characters.
`model`	Form	string	Required	Supported	Public logical audio model ID.
`prompt`	Form	string	Optional	Conditional	Transcription hint, up to 4,096 characters.
`response_format`	Form	string	Optional	Supported	json, text, srt, verbose_json, or vtt.
`temperature`	Form	number	Optional	Supported	Sampling temperature, 0 to 1.
`timestamp_granularities`	Form	array<value>	Optional	Conditional	word and/or segment; requires response_format=verbose_json.
`user`	Form	string	Optional	Supported	Provider abuse-monitoring user identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/audio/transcriptions' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -F 'file=@./your-file' \
  -F 'model=whisper-1'

Response

{
  "text": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Transcribe an uploaded recording.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.

Translate an uploaded recording into English

POST/v1/audio/translations

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typemultipart/form-data

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`file`	Form	string (binary)	Required	Supported	The recording to process.
`model`	Form	string	Required	Supported	Public logical audio model ID.
`prompt`	Form	string	Optional	Conditional	Transcription hint, up to 4,096 characters.
`response_format`	Form	string	Optional	Supported	json, text, srt, verbose_json, or vtt.
`temperature`	Form	number	Optional	Supported	Sampling temperature, 0 to 1.
`user`	Form	string	Optional	Supported	Provider abuse-monitoring user identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/audio/translations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -F 'file=@./your-file' \
  -F 'model=whisper-1'

Response

A representative JSON response is not available for this endpoint. Handle the documented HTTP status and inspect the returned body according to your client workflow.

Status codes

HTTP	Details
200	Translate an uploaded recording into English.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.