API reference
Realtime
Create a short-lived credential or call on your server before connecting a client. Keep the project API key out of browser code.
How it fits together
- 01Exchange a WebRTC SDP offer for an OpenAI Realtime answer
- 02Mint a short-lived OpenAI Realtime client secret
Select an action to see its complete inputs, request, response, and status codes.
Exchange a WebRTC SDP offer for an OpenAI Realtime answer
POST
/v1/realtime/callsProduction base URL
https://api.mahvashai.irAuthenticationProject API key or user JWT
ResponseDirect OpenAI-style response
Content type
application/jsonParameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
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. |
client_secret | Body | string | Required | Supported | Short-lived realtime client secret. |
sdp | Body | string | Required | Supported | WebRTC SDP offer. |
session_id | Body | string | Required | Mahvash extension | Mahvash realtime session identifier. |
Request
curl -X POST 'https://api.mahvashai.ir/v1/realtime/calls' \
-H "Authorization: Bearer $MAHVASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_secret": "ek_...",
"sdp": "v=0\\r\\no=- 0 0 IN IP4 127.0.0.1\\r\\n...",
"session_id": "3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'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 |
|---|---|
| 201 | Exchange a WebRTC SDP offer for an OpenAI Realtime answer. |
| 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. |
Mint a short-lived OpenAI Realtime client secret
POST
/v1/realtime/client_secretsProduction base URL
https://api.mahvashai.irAuthenticationProject API key or user JWT
ResponseDirect OpenAI-style response
Content type
application/jsonParameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
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. |
expires_after | Body | object | Optional | Mahvash extension | Short-lived credential lifetime. |
model | Body | string | Optional | Conditional | Logical realtime model. |
session | Body | object | Optional | Conditional | Bounded realtime session configuration. |
A compatible model and provider route are required for conditional fields.
Request
curl -X POST 'https://api.mahvashai.ir/v1/realtime/client_secrets' \
-H "Authorization: Bearer $MAHVASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expires_after": {
"anchor": "created_at",
"seconds": 60
}
}'Response
{
"id": "<id>",
"object": "realtime.session",
"model": "<model-id>",
"expires_at": 1750000000,
"client_secret": {
"value": "<value>",
"expires_at": 1750000000
},
"session_id": "<id>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 200 | Mint a short-lived OpenAI Realtime client secret. |
| 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. |