> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/api-reference/ai/ai-model-hub/audio/create-transcription.md).

# Create transcription

Transcribe an audio file into text, following the OpenAI Audio API wire format. The audio is uploaded as `multipart/form-data`.

`response_format` selects how the transcript comes back: `json` wraps it in an object, `text` returns it as a plain `text/plain` body, and `verbose_json` adds the duration and per-segment timings. Whether `verbose_json` is available at all is model-specific, and it is rejected with a `400` for models that cannot produce timings.

```json
{"openapi":"3.0.3","info":{"title":"IONOS CLOUD - OpenAI compatible AI Model Hub API","version":"1.0.0"},"tags":[{"name":"Audio","description":"Transcribe speech audio into text."}],"servers":[{"url":"https://openai.inference.de-txl.ionos.com","description":"Berlin"}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Please provide header value as 'Bearer <token>' and don't forget\nto add 'Bearer' HTTP Authorization Scheme before the token.\n"}},"schemas":{"TranscriptionRequest":{"type":"object","description":"Request payload for transcribing audio. Sent as `multipart/form-data`, with the\naudio itself as the binary file part `file`.\n","required":["model","file"],"properties":{"model":{"type":"string","description":"Model identifier to use for transcription.","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9._/-]+$"},"file":{"type":"string","format":"binary","description":"The audio to transcribe, uploaded as a file part, of at most 15 MiB. A larger file is rejected with a 413. FLAC, MP3, MP4, MPEG, M4A, Ogg, WAV and WebM are accepted."},"language":{"type":"string","description":"Language of the input audio as an ISO-639-1 code, such as `en` or `de`. Supplying it improves accuracy and latency. Omit it to have the language detected."},"prompt":{"type":"string","description":"Text to guide the transcript's style, or to supply vocabulary the audio is likely to contain. How much it changes the result is model-specific."},"response_format":{"type":"string","description":"Format of the transcript. `json` wraps the text in an object, `text` returns\nit as a plain body, and `verbose_json` adds the duration and per-segment\ntimings. `verbose_json` is model-specific and is rejected with a `400` for\nmodels that cannot produce timings.\n","enum":["json","text","verbose_json"],"default":"json"},"temperature":{"type":"number","format":"double","description":"Sampling temperature. Higher values make the transcript more varied, lower values more deterministic.","minimum":0,"maximum":1,"default":0},"seed":{"type":"integer","description":"Seed for deterministic sampling. Repeated requests with the same seed and\nparameters return the same transcript on a best-effort basis. It only has\nan effect when `temperature` is above 0: at the default of 0 decoding is\ngreedy and already deterministic.\n\nThis is an extension, not part of the OpenAI Audio API. OpenAI SDK clients\nsend it through `extra_body` (for example `extra_body={\"seed\": 42}` in\nPython), which for this multipart endpoint arrives as the form field `seed`.\n"},"stream":{"type":"boolean","description":"If true, stream the transcript as Server-Sent Events. Not supported: a request\nwith `stream` set to true is rejected with a 400. Omit the field or set it to\n`false`.\n","default":false}}},"TranscriptionResponse":{"type":"object","description":"Transcript of the supplied audio. Which fields are present depends on the\nrequest's `response_format`: `json` returns `text` and `usage`, and\n`verbose_json` returns `text` with `duration`, `language` and `segments`.\n","required":["text"],"properties":{"text":{"type":"string","description":"The transcribed text."},"usage":{"$ref":"#/components/schemas/TranscriptionUsage"},"language":{"type":"string","description":"Language of the input audio, detected when it was not supplied. Present\nonly for `verbose_json`, when the model reports it.\n"},"duration":{"type":"number","format":"double","description":"Length of the input audio in seconds. Present, and always set, for\n`verbose_json`.\n"},"segments":{"type":"array","description":"The transcript split into timed segments. Present only for `verbose_json`,\nand absent there too for models that do not report timings.\n","items":{"$ref":"#/components/schemas/TranscriptionSegment"}}}},"TranscriptionUsage":{"type":"object","description":"How much audio was transcribed, which is what the request is billed on.","required":["type","seconds"],"properties":{"type":{"type":"string","description":"The quantity `seconds` measures.","enum":["duration"]},"seconds":{"type":"integer","description":"Length of the input audio in seconds, rounded up to a whole second."}}},"TranscriptionSegment":{"type":"object","description":"One timed span of the transcript.","required":["id","start","end","text"],"properties":{"id":{"type":"integer","description":"Position of the segment in the transcript, starting at zero."},"seek":{"type":"integer","description":"Offset the decoder seeked to for this segment."},"start":{"type":"number","format":"double","description":"Start time of the segment in seconds."},"end":{"type":"number","format":"double","description":"End time of the segment in seconds."},"text":{"type":"string","description":"Text of the segment."},"tokens":{"type":"array","description":"Token ids the segment's text decoded from.","items":{"type":"integer"}},"temperature":{"type":"number","format":"double","description":"Sampling temperature the segment was produced with."},"avg_logprob":{"type":"number","format":"double","description":"Average log probability of the segment. Values below -1 indicate the transcript for this span is unreliable."},"compression_ratio":{"type":"number","format":"double","description":"Compression ratio of the segment's text. Values above 2.4 indicate repetitive output."},"no_speech_prob":{"type":"number","format":"double","description":"Probability that the segment contains no speech. Reported only by models that measure it."}}},"Error":{"type":"object","description":"Error response.","properties":{"httpStatus":{"type":"integer","description":"HTTP status code of the operation as specified by RFC 7231."},"messages":{"type":"array","description":"List of error messages.","items":{"type":"object","properties":{"errorCode":{"type":"string","description":"Stable, machine-readable classification of the failure. Branch on this\nrather than on `message`, which is meant for humans and may be reworded.\n\nClient errors, safe to act on:\n\n- `VALIDATION_ERROR` (400) a field is missing, malformed or out of the\n  documented range. The message names the field.\n- `INVALID_JSON` (400) the body is not valid JSON.\n- `INVALID_MULTIPART` (400) the multipart form could not be parsed.\n- `INVALID_TOKEN` (401) the `Authorization` header is larger than 8 KiB.\n  Every other 401 carries one of the authentication codes instead:\n  `paas-auth-1` (the `Authorization` header is missing or does not hold a\n  `Bearer` token), `paas-token-1` (the token was not accepted) or\n  `paas-auth-2` (the token could not be verified as a customer token).\n- `INSUFFICIENT_PRIVILEGES` (403) the token is valid but its contract\n  lacks the privilege required to use this API.\n- `MODEL_NOT_SUPPORTED` (404) the model is unknown. A known model that lacks\n  the capability this endpoint or request needs is rejected with a 400\n  `VALIDATION_ERROR` naming the models that have it.\n- `ROUTE_NOT_FOUND` (404) no endpoint exists at the requested path.\n- `METHOD_NOT_ALLOWED` (405) the endpoint exists but does not accept the\n  HTTP method used.\n- `RESOURCE_LIMIT_ERROR` (413) the request exceeds a documented size or\n  count limit.\n- `RATE_LIMIT_EXCEEDED` (429) the contract's rate limit is exhausted.\n  Wait the number of seconds in `Retry-After` before retrying.\n- `SERVICE_OVERLOADED` (503) too many large requests are already being\n  handled at once. Applies only above a size threshold, or to a request\n  sent with chunked transfer encoding. An ordinary request is never\n  refused this way. Retry after the interval in `Retry-After`.\n- `CLIENT_DISCONNECTED` (499) you closed the connection before the\n  response was ready. You never receive this code, since the connection\n  is already gone. It identifies the request in usage records. Tokens\n  generated before the disconnect are still billed.\n\nThe model refused or could not be reached:\n\n- `UPSTREAM_REJECTED` the model rejected the request. The status is the\n  one it returned, and the message carries its explanation. Usually a 4xx\n  and usually worth fixing rather than retrying. An image or video URL in\n  the request that answers with a client error, such as 404, comes back\n  as 422 with this code: check that the URL exists and is publicly\n  reachable.\n- `UPSTREAM_NOT_IMPLEMENTED` (422) the model understood the request and\n  does not implement part of it. Retrying does not help. The same request\n  may succeed against a different model.\n- `UPSTREAM_UNAVAILABLE` (502) the model could not be reached, or stopped\n  before it finished answering. Retrying is reasonable. A partial answer\n  is never returned in its place, and nothing is billed for it. An image or\n  video URL whose host cannot be reached, times out or answers with a\n  server error comes back this way too.\n- `UPSTREAM_TIMEOUT` (504) the model did not answer within the time allowed\n  for it. The work may have been too expensive:\n  prefer a smaller request or a different model over retrying the same\n  one unchanged.\n\nAn internal error occurred (500). The code identifies where it happened\nand is not a contract to branch on. Treat these alike:\n`CHAT_COMPLETION_ERROR`, `COMPLETION_ERROR`, `EMBEDDING_ERROR`,\n`IMAGE_ERROR`, `RERANK_ERROR`, `RESPONSES_ERROR`, `TRANSCRIPTION_ERROR`,\n`CONVERSION_ERROR`.\n\nNew codes may be added, so treat an unrecognized value as a generic\nfailure of its HTTP status class rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable explanation, intended for logs and for showing to a\ndeveloper. Wording may change between releases, so branch on `errorCode`.\n"}},"additionalProperties":false}}},"required":["httpStatus","messages"],"additionalProperties":false},"OpenAIError":{"type":"object","description":"OpenAI-compatible error response.","required":["error"],"properties":{"error":{"type":"object","description":"The error details.","required":["message","type"],"properties":{"message":{"type":"string","description":"Human-readable explanation of the error."},"type":{"type":"string","description":"Error category, for example `invalid_request_error`."},"code":{"type":"string","description":"Machine-readable sub-classification of `type`. Used by the 529 overload\nresponse to distinguish a per-user throttle (`user_overloaded`) from a\nsystem-wide capacity shortage (`server_overloaded`), so you do not have to\nparse the `message` text.\n"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier for this request. Quote it when reporting a problem to support.","schema":{"type":"string"}},"X-Gateway-Version":{"description":"Build version of the API that served the response.","schema":{"type":"string"}},"X-RateLimit-Limit-Requests":{"description":"How many requests per interval your contract's rate limit allows for this\nrequest. The value, and the length of the interval, depend on your contract.\nAbsent when no rate-limit check ran, for example on a request refused for a\nmalformed body.\n","schema":{"type":"integer"}},"X-RateLimit-Remaining-Requests":{"description":"How many of those requests are still unused. It counts down from\n`X-RateLimit-Limit-Requests`, never exceeds it, and refills continuously over the\ninterval. Once it reaches 0, slow down: further requests may be refused with a\n429 until it refills. Absent when no rate-limit check ran.\n","schema":{"type":"integer"}},"X-RateLimit-Reset-Requests":{"description":"The time until the rate limit is back at its initial state, with\n`X-RateLimit-Remaining-Requests` equal to the limit again, as a duration such as\n`200ms`, `1.5s` or `6m0s`. Requests refill gradually, so the remaining count\nrises well before then. Absent when no rate-limit check ran.\n","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"### Bad Request\nThe request sent to the API was malformed.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"### Unauthorized\nThe request is missing authorization information or the authorization information provided are expired.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"### Forbidden\nThe user issuing the request does not have the needed permissions.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"### Not Found\nThe requested model or endpoint does not exist. A model that exists but lacks the\ncapability the request needs is rejected with a 400 instead.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"### Payload Too Large\nThe request exceeds a size limit. The request body is limited to 16 MiB, an inline\nbase64 data URI to 12 MiB decoded, and an uploaded image or mask to 10 MiB. On\n`/v1/chat/completions`, `/v1/embeddings`, and `/v1/rerank`, a message, query, or\ndocument is limited to 2048 content parts. Count limits, such as the number of\ndocuments, are stated with each field. Pass large media as a remote HTTP or HTTPS URL\ninstead of inline base64: a URL does not count against the size limits, though it\nstill counts as a content part.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"### Unprocessable Entity\nThe request was well-formed but contains semantic errors.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"### Too Many Requests\nYour contract's rate limit is exhausted. Wait the number of seconds in `Retry-After`\nbefore retrying, rather than a delay of your own. The OpenAI SDKs do this\nautomatically. Limits are contract-specific.\n","headers":{"X-RateLimit-Limit-Requests":{"$ref":"#/components/headers/X-RateLimit-Limit-Requests"},"X-RateLimit-Remaining-Requests":{"$ref":"#/components/headers/X-RateLimit-Remaining-Requests"},"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"},"Retry-After":{"description":"Seconds to wait before retrying. Other requests under your contract count\nagainst the same limit, so a retry can still be refused.\n","schema":{"type":"integer"}},"X-RateLimit-Reset-Requests":{"$ref":"#/components/headers/X-RateLimit-Reset-Requests"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"### Internal Server Error\nThe request could not be completed because of an internal error. The request was\nnot necessarily rejected, so a retry is safe for idempotent calls. If it persists,\nquote the value of the `X-Request-Id` response header when contacting support.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadGateway":{"description":"### Bad Gateway\nThe model could not be reached, or stopped before it finished answering. No partial\nanswer is returned in its place, and nothing is billed for it. Retrying is\nreasonable. An image or video URL in the request whose host cannot be reached,\ntimes out or answers with a server error is also answered this way.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceOverloaded":{"description":"### Service Overloaded (503)\nToo many large requests are already being handled at once. This applies only\nto a request above a size threshold, or one sent with chunked transfer\nencoding. An ordinary-sized request is never refused this way. Always retry\nusing the `Retry-After` header, not a fixed delay, to avoid a synchronized\nretry storm. For sustained traffic in media, keep individual requests small:\npass large media in a JSON body as a remote HTTP or HTTPS URL rather than\ninline base64, and keep a file upload small, for example by sending audio in\na compressed format such as MP3 or Opus. The message gives the advice that\nfits how the request was sent.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GatewayTimeout":{"description":"### Gateway Timeout\nThe model did not answer within the time allowed for it. The request may\nhave reached the model and may even have been served, so a retry is only safe for\nidempotent calls. Retrying the same request unchanged tends to time out again: the\nwork itself is usually what was too slow, so prefer a smaller request (fewer or\nsmaller images, a shorter prompt, a lower `n`) or a model that can serve it.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Overloaded":{"description":"### Capacity Exhausted (529)\nThe service is temporarily overloaded. This is a non-standard status,\nmatching the convention used by other LLM providers for the same\ncondition: capacity is exhausted, not a client error (429) and not an\noutage (503). `error.code` distinguishes a per-user throttle\n(`user_overloaded`) from a system-wide capacity shortage\n(`server_overloaded`). If you check only the status, treat both\nalike. Always retry using the `Retry-After` header, not a\nfixed delay, to avoid a synchronized retry storm.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIError"}}}}}},"paths":{"/v1/audio/transcriptions":{"post":{"operationId":"v1AudioTranscriptionsPost","summary":"Create transcription","description":"Transcribe an audio file into text, following the OpenAI Audio API wire format.\nThe audio is uploaded as `multipart/form-data`.\n\n`response_format` selects how the transcript comes back: `json` wraps it in an\nobject, `text` returns it as a plain `text/plain` body, and `verbose_json` adds\nthe duration and per-segment timings. Whether `verbose_json` is available at all\nis model-specific, and it is rejected with a `400` for models that cannot\nproduce timings.\n","tags":["Audio"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/TranscriptionRequest"}}}},"responses":{"200":{"description":"Successful operation. The body is JSON unless `response_format` is `text`,\nin which case it is the transcript on its own as `text/plain`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionResponse"}},"text/plain":{"schema":{"type":"string","description":"The transcript, returned when `response_format` is `text`."}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"},"X-RateLimit-Limit-Requests":{"$ref":"#/components/headers/X-RateLimit-Limit-Requests"},"X-RateLimit-Remaining-Requests":{"$ref":"#/components/headers/X-RateLimit-Remaining-Requests"},"X-RateLimit-Reset-Requests":{"$ref":"#/components/headers/X-RateLimit-Reset-Requests"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceOverloaded"},"504":{"$ref":"#/components/responses/GatewayTimeout"},"529":{"$ref":"#/components/responses/Overloaded"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/api-reference/ai/ai-model-hub/audio/create-transcription.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
