--- title: Transcribe audio to text url: https://developers.wpengine.com/docs/ai/api/reference/operations/createtranscription/ image: https://developers.wpengine.com/og/docs/ai/api/reference/operations/createtranscription.png --- # Transcribe audio to text POST /v1/audio/transcriptions Select code sample ```php request('POST', 'https://api.ai.wpengine.com/v1/audio/transcriptions', [ 'body' => '{ "model": "google/gemini-3.5-flash", "audio": "example", "mime_type": "audio/wav", "language": "example" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` - Current environment Accepts base64-encoded audio data and returns a text transcription. Supports common audio formats including WAV, MP3, OGG, WebM, and FLAC. Maximum audio size is 25 MiB. Requires a valid WP Engine bearer token; API keys must carry the “transcribe:write” permission. ## Authorizations - **[bearerAuth](https://developers.wpengine.com/docs/ai/api/reference/#bearerauth)** ## Request Bodyrequired Media typeapplication/json object **model** Optional model identifier. Defaults to a Gemini model when omitted. string ### Example ``` google/gemini-3.5-flash ``` **audio** required Base64-encoded audio data. string **mime_type** MIME type of the audio (e.g. “audio/wav”, “audio/mp3”, “audio/ogg”). Defaults to “audio/wav”. string default: audio/wav **language** Optional ISO 639-1 language code hint for transcription (e.g. “en”, “es”, “fr”). string ## Responses ### 200 Transcription result Media typeapplication/json object **text** required The transcribed text. string **model** required The model used for transcription. string #### Example generated ```json { "text": "example", "model": "example" } ``` ### 400 Invalid request body or parameters. On agent create and update, error type “profile_unavailable” means the requested profile is not available to the caller. Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` ### 401 Missing or invalid bearer token Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` #### Headers **WWW-Authenticate** string ##### Example ``` Bearer realm="ai-services" ``` ### 402 The account’s credit balance is exhausted. Grant or top up credits before retrying. Distinct from 429, which is edge rate limiting. Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` ### 403 The token is valid, but the request is forbidden. Error type “permission_error” means the token’s scope/permission is insufficient or the authenticated user is not authorized for the target account; “entitlement_required” means the account may not use WP Engine AI, with error_code giving why when known (not_eligible, terms_required, not_enabled or suspended) and portal_url where to fix it; “account_required” means no billing account could be resolved; and “billing_account_pending” means billing isn’t set up for the account yet, usually because its setup after AI was turned on hasn’t finished. Retry shortly. On /v1/chat/completions when content moderation is enabled, and on /v1/sessions/{session_id}/events, error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched. Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` ### 413 Request body exceeds the 64 KiB limit Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` ### 429 Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body. Media typetext/html string ### 502 Upstream provider returned an error Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` ### 503 A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off. An entitlement lookup failure uses error type “entitlement_unavailable”. A model without complete rate coverage uses error type “model_unpriced”. A credit balance that can’t be read uses error type “balance_unavailable”. Media typeapplication/json object **error** required object **message** required string **type** required string **error_code** Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes. string **portal_url** Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured. string **code** required integer **request_id** required Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports. string #### Example ```json { "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" } } ``` ## Was this helpful? Thanks for the feedback! ```json {"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]} ```