> 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/chat-completions/create-chat-completion.md).

# Create chat completion

Generate a chat completion for the given messages, following the OpenAI Chat Completions API wire format.

Set `stream: true` to receive a Server-Sent Events stream. Each event carries a `chat.completion.chunk` object. When `stream_options.include_usage` is `true`, the final chunk before `[DONE]` includes a `usage` field with token counts.

```json
{"openapi":"3.0.3","info":{"title":"IONOS CLOUD - OpenAI compatible AI Model Hub API","version":"1.0.0"},"tags":[{"name":"Chat Completions","description":"Generate chat completions following the OpenAI Chat Completions API."}],"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":{"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","description":"ID of the model to use."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionMessage"},"description":"List of messages forming the conversation so far. At most 500 messages. A longer\nconversation is rejected with a 413.\n","minItems":1,"maxItems":500},"response_format":{"description":"The format the model must output. Which formats a model supports is\nmodel-specific.\n","oneOf":[{"$ref":"#/components/schemas/ResponseFormatText"},{"$ref":"#/components/schemas/ResponseFormatJsonObject"},{"$ref":"#/components/schemas/ResponseFormatJsonSchema"}]},"temperature":{"type":"number","description":"Sampling temperature between 0 and 2.","minimum":0,"maximum":2},"top_p":{"type":"number","description":"Nucleus sampling probability mass, greater than 0 and at most 1. A value outside\nthat range, including exactly 0, is rejected with a 400.\n","minimum":0,"exclusiveMinimum":true,"maximum":1},"n":{"type":"integer","description":"Number of chat completion choices to generate. When omitted, the model chooses.","minimum":1},"stream":{"default":false,"type":"boolean","description":"If true, stream partial results as Server-Sent Events."},"stop":{"description":"Up to 4 sequences at which generation stops.","oneOf":[{"type":"string"},{"type":"array","maxItems":4,"items":{"type":"string"}}]},"max_tokens":{"type":"integer","description":"Maximum number of tokens to generate. For a reasoning model, the reasoning counts\ntoward this limit and comes before the answer. If the limit is reached while the\nmodel is still reasoning, the response has `finish_reason` `length`, an empty\n`content`, and the reasoning so far in `reasoning`. A lower `reasoning_effort`\nleaves more of the limit for the answer.\n","minimum":1},"max_completion_tokens":{"type":"integer","description":"Maximum number of tokens to generate, including any reasoning, as for `max_tokens`.\nOpenAI's replacement for the deprecated `max_tokens`. Avoid setting both in one\nrequest: which of the two applies is model-specific. The accepted range is\nmodel-specific.\n"},"presence_penalty":{"type":"number","description":"Penalize tokens that have appeared so far in the text.","minimum":-2,"maximum":2},"frequency_penalty":{"type":"number","description":"Penalize tokens based on their frequency in the text.","minimum":-2,"maximum":2},"logit_bias":{"type":"object","description":"Per-token likelihood adjustment, keyed by token ID. OpenAI defines values from -100\n(effectively banned) to 100 (effectively required). The accepted range and its\neffect are model-specific.\n","additionalProperties":{"type":"integer"}},"logprobs":{"type":"boolean","description":"Whether to return log probabilities of the output tokens."},"top_logprobs":{"type":"integer","description":"Number of most-likely tokens to return at each position, when `logprobs` is true.","minimum":0,"maximum":20},"user":{"type":"string","description":"Opaque identifier for your end user."},"reasoning_effort":{"type":"string","description":"How much reasoning to do before answering, for reasoning-capable models. Accepted\nvalues are model-specific. A value the model does not accept is rejected with a 400.\n"},"tools":{"type":"array","description":"List of tools the model may call.","items":{"$ref":"#/components/schemas/ChatCompletionTool"}},"tool_choice":{"description":"Controls which tool, if any, the model calls. `none` means no tool call, `auto` lets\nthe model decide, and `required` forces a tool call. A named tool object forces a\nspecific function.\n\nWhich values a model honors is model-specific. A model may answer with a normal\nmessage instead of the tool call that `required` or a named function asks for. The\nvalue is not checked, so how any other value is answered is also model-specific.\n","oneOf":[{"type":"string","enum":["none","auto","required"]},{"$ref":"#/components/schemas/ChatCompletionNamedToolChoice"}]},"stream_options":{"type":"object","description":"Options for streaming. Applies only when `stream` is true.","properties":{"include_usage":{"type":"boolean","description":"If true, the final SSE chunk includes a `usage` field with token counts."}}},"seed":{"type":"integer","description":"Seed for deterministic sampling. Repeated requests with the same seed and\nparameters return the same completion on a best-effort basis. Support is\nmodel-specific.\n"},"parallel_tool_calls":{"type":"boolean","description":"Whether the model may emit more than one tool call in a single turn. Whether it is\nhonored is model-specific.\n"}},"required":["model","messages"],"description":"Request body for `POST /v1/chat/completions` (OpenAI Chat Completions API)."},"ChatCompletionMessage":{"type":"object","description":"A single message in the conversation.\n\n`content` is required on every message except an `assistant` message carrying\n`tool_calls`, which the OpenAI schema allows to send `content` as null or omit it\nentirely. Such a message must be replayed with its `tool_calls` intact, because a\nlater `tool` message's `tool_call_id` is matched against them.\n","properties":{"role":{"type":"string","description":"The role of the message author. Support for `developer`, which OpenAI uses in\nplace of `system` for some models, is model-specific: a model that does not\nrecognize the role rejects the request with a 400. Use `system` for the widest\ncompatibility.\n","enum":["system","developer","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionContentPart"},"minItems":1,"maxItems":2048}],"description":"Message content. Either a plain string, or an ordered array of content parts\nfor multi-modal input (text plus `image_url` parts, `video_url` parts, or both).\n\nImage and video parts are only accepted on `user` messages, and only for\nmodels advertising the matching capability. For other models, the request is\nrejected with a 400 naming the models that support it.\n"},"name":{"type":"string","description":"An optional name for the participant."},"tool_calls":{"type":"array","description":"Tool calls previously generated by the model, replayed on an `assistant` message\nwhen continuing a tool-calling conversation. Echo them back exactly as received,\nids included.\n","items":{"$ref":"#/components/schemas/ChatCompletionToolCall"},"nullable":true},"tool_call_id":{"type":"string","description":"Tool call ID this message is responding to. Required when role is `tool`."}},"required":["role"]},"ChatCompletionContentPart":{"type":"object","description":"A single content part: text, an image reference, or a video reference.","required":["type"],"properties":{"type":{"type":"string","description":"Discriminator for the content type.","enum":["text","image_url","video_url"]},"text":{"type":"string","description":"Text content when `type` is `text`."},"image_url":{"$ref":"#/components/schemas/ChatCompletionImageURL"},"video_url":{"$ref":"#/components/schemas/ChatCompletionVideoURL"}}},"ChatCompletionImageURL":{"type":"object","description":"Image reference. Either a public HTTP or HTTPS URL, which must be reachable from the\ninternet, or an inline base64 data URI (`data:image/...;base64,...`) of at most 12 MiB\ndecoded.\n","required":["url"],"properties":{"url":{"type":"string","description":"HTTP or HTTPS URL, or base64 data URI, of the image."},"detail":{"type":"string","description":"Fidelity hint for image processing. Both its effect and whether it is honored at\nall are model-specific. Omit it to leave the choice to the model.\n","enum":["auto","low","high"]}}},"ChatCompletionVideoURL":{"type":"object","description":"Video reference. Either a public HTTP or HTTPS URL, which must be reachable from the\ninternet, or an inline base64 data URI (`data:video/...;base64,...`) of at most 12 MiB\ndecoded. Prefer a remote URL for long clips: the whole request body is limited to\n16 MiB, and a base64 payload is about 4/3 the size of the media it carries.\n","required":["url"],"properties":{"url":{"type":"string","description":"HTTP or HTTPS URL, or base64 data URI, of the video."}}},"ChatCompletionToolCall":{"type":"object","description":"A tool call generated by the model.","required":["id","type","function"],"properties":{"id":{"type":"string","description":"Unique identifier for this tool call."},"type":{"type":"string","description":"Always `function`.","enum":["function"]},"function":{"type":"object","description":"The function the model called.","required":["name","arguments"],"properties":{"name":{"type":"string","description":"The name of the function to call."},"arguments":{"type":"string","description":"JSON-encoded arguments to pass to the function."}}}}},"ResponseFormatText":{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"]},"ResponseFormatJsonObject":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["json_object"]}}},"ResponseFormatJsonSchema":{"type":"object","required":["type","json_schema"],"properties":{"type":{"type":"string","enum":["json_schema"]},"json_schema":{"type":"object","additionalProperties":true,"description":"The JSON schema the model must conform to.","required":["name","schema"],"properties":{"name":{"type":"string","description":"Identifier for the schema definition."},"schema":{"type":"object","additionalProperties":true,"description":"The JSON Schema object the output must conform to."},"strict":{"type":"boolean","description":"Whether the model must follow the schema exactly. Whether it is honored, and\nits default when omitted, are model-specific.\n"}}}}},"ChatCompletionTool":{"type":"object","description":"A tool the model may call.","required":["type","function"],"properties":{"type":{"type":"string","description":"Always `function`. The value is not checked, and how another type is answered is\nmodel-specific.\n","enum":["function"]},"function":{"type":"object","description":"The function the model may call.","required":["name"],"properties":{"name":{"type":"string","description":"The name of the function to call."},"description":{"type":"string","description":"Description of what the function does."},"parameters":{"type":"object","additionalProperties":true,"description":"The parameters the function accepts, described as a JSON Schema object."}}}}},"ChatCompletionNamedToolChoice":{"type":"object","description":"Forces the model to call a specific function.","required":["type","function"],"properties":{"type":{"type":"string","description":"Always `function`.","enum":["function"]},"function":{"type":"object","description":"The function to call.","required":["name"],"properties":{"name":{"type":"string","description":"The name of the function to call."}}}}},"ChatCompletionResponse":{"type":"object","description":"Response body for a non-streaming `POST /v1/chat/completions` request.","required":["id","object","created","model","choices"],"properties":{"id":{"type":"string","description":"Unique identifier for this chat completion."},"object":{"type":"string","description":"Always `chat.completion`."},"created":{"type":"integer","description":"Unix timestamp of when the completion was created."},"model":{"type":"string","description":"Model used to generate the completion."},"choices":{"type":"array","description":"List of generated chat completion choices.","items":{"$ref":"#/components/schemas/ChatCompletionChoice"}},"usage":{"$ref":"#/components/schemas/CompletionUsage"}}},"ChatCompletionChoice":{"type":"object","description":"A single generated chat completion choice.","required":["finish_reason","logprobs"],"properties":{"index":{"type":"integer","description":"Index of this choice in the list."},"message":{"$ref":"#/components/schemas/ChatCompletionResponseMessage"},"finish_reason":{"type":"string","nullable":true,"description":"Reason the generation stopped, for example `stop`, `length`, or `tool_calls`. Null while a\nstreamed choice is still generating, and on the rare completion for which no\nreason is available.\n"},"logprobs":{"type":"object","nullable":true,"additionalProperties":true,"description":"Log-probability information for the choice, when requested."}}},"ChatCompletionResponseMessage":{"type":"object","description":"The message generated by the model.","required":["role","content"],"properties":{"role":{"type":"string","description":"Always `assistant`.","enum":["assistant"]},"content":{"type":"string","nullable":true,"description":"The text content of the message. Null when the model answers with `tool_calls` or\na `refusal` only. Empty when it writes no answer, for example when a reasoning\nmodel reaches `max_tokens` before it finishes reasoning.\n"},"reasoning":{"type":"string","nullable":true,"description":"Reasoning trace emitted by reasoning-capable models, when present."},"refusal":{"type":"string","nullable":true,"description":"Refusal message emitted by the model, when it declines to answer."},"tool_calls":{"type":"array","nullable":true,"description":"Tool calls generated by the model, if any.","items":{"$ref":"#/components/schemas/ChatCompletionToolCall"}}}},"CompletionUsage":{"type":"object","description":"Token usage statistics for the completion request.","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer","description":"Number of tokens in the prompt.","minimum":0},"completion_tokens":{"type":"integer","description":"Number of tokens in the generated completion.","minimum":0},"total_tokens":{"type":"integer","description":"Total tokens consumed by the request.","minimum":0},"completion_tokens_details":{"$ref":"#/components/schemas/CompletionTokensDetails"}}},"CompletionTokensDetails":{"type":"object","description":"Breakdown of `completion_tokens`, present when the model reports one.","properties":{"reasoning_tokens":{"type":"integer","description":"Tokens the model spent reasoning before its answer. They are already counted in\n`completion_tokens`.\n","minimum":0}}},"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-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-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-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/chat/completions":{"post":{"operationId":"v1ChatCompletionsPost","summary":"Create chat completion","description":"Generate a chat completion for the given messages, following the OpenAI Chat Completions\nAPI wire format.\n\nSet `stream: true` to receive a Server-Sent Events stream. Each event carries a\n`chat.completion.chunk` object. When `stream_options.include_usage` is `true`, the final\nchunk before `[DONE]` includes a `usage` field with token counts.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Successful operation. Returns `ChatCompletionResponse` for non-streaming requests,\nor a `text/event-stream` of `chat.completion.chunk` objects when `stream: true`.\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"},"X-RateLimit-Reset-Requests":{"$ref":"#/components/headers/X-RateLimit-Reset-Requests"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Sent when `stream: true`. A Server-Sent Events stream: each event is a\n`data: ` line carrying one `chat.completion.chunk` JSON object, followed by a\nblank line. Each chunk has the fields of `ChatCompletionResponse`, with\n`delta` in place of `message` on each choice. The stream ends with\n`data: [DONE]`.\n"}}}},"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"}},"tags":["Chat Completions"]}}}}
```


---

# 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/chat-completions/create-chat-completion.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.
