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

# Create completion

Generate a text completion for the given prompt, following the OpenAI Completions API wire format.

Set `stream: true` to receive a Server-Sent Events stream. Each event carries a `text_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":"Completions","description":"Generate text completions following the OpenAI 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":{"CompletionRequest":{"type":"object","properties":{"model":{"type":"string","description":"ID of the model to use."},"prompt":{"description":"The prompt to generate completions for. Either a single string, or an array of\nstrings to complete independently in one request. The response then carries one\nchoice per prompt, in the order given.\n\nThe model continues the prompt as plain text, without a chat template. A model that\nonly works in its own chat format, for example `openai/gpt-oss-120b`, rarely stops\non its own when given a plain prompt and generates until `max_tokens`. Use\n`/v1/chat/completions` for such a model.\n","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"temperature":{"type":"number","description":"Sampling temperature between 0 and 2. Higher values produce more random output.","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","exclusiveMinimum":true,"minimum":0,"maximum":1},"n":{"type":"integer","description":"Number of completions to generate. When omitted, the model chooses.","minimum":1},"stream":{"type":"boolean","description":"If true, stream partial results as Server-Sent Events.","default":false},"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. When omitted, the model chooses. The models\nin the catalog stop after 16 tokens, as OpenAI's completions API does.\n","minimum":1},"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"}},"user":{"type":"string","description":"Opaque identifier for your end user."},"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."}}},"logprobs":{"type":"integer","nullable":true,"description":"Include the log probabilities of this many most-likely tokens, when set.","minimum":0},"suffix":{"type":"string","description":"Text to append after the completion. Support is model-specific."},"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"},"echo":{"type":"boolean","description":"If true, the prompt is echoed back at the start of the generated text. Support is\nmodel-specific.\n"}},"required":["model","prompt"],"description":"Request body for `POST /v1/completions` (OpenAI Completions API)."},"CompletionResponse":{"type":"object","description":"Response body for a non-streaming `POST /v1/completions` request.","required":["id","object","created","model","choices"],"properties":{"id":{"type":"string","description":"Unique identifier for this completion."},"object":{"type":"string","description":"Always `text_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 completions.","items":{"$ref":"#/components/schemas/CompletionChoice"}},"usage":{"$ref":"#/components/schemas/CompletionUsage"}}},"CompletionChoice":{"type":"object","description":"A single generated completion.","required":["finish_reason","logprobs"],"properties":{"text":{"type":"string","description":"The generated text."},"index":{"type":"integer","description":"Index of this choice in the list."},"finish_reason":{"type":"string","nullable":true,"description":"Reason the generation stopped, for example `stop` or `length`. Null while a streamed\nchoice is still generating, and on the rare completion for which no reason is\navailable.\n"},"logprobs":{"type":"object","nullable":true,"additionalProperties":true,"description":"Log-probability information for the choice, when requested."}}},"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/completions":{"post":{"operationId":"v1CompletionsPost","summary":"Create completion","description":"Generate a text completion for the given prompt, following the OpenAI Completions API wire\nformat.\n\nSet `stream: true` to receive a Server-Sent Events stream. Each event carries a\n`text_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/CompletionRequest"}}}},"responses":{"200":{"description":"Successful operation. Returns `CompletionResponse` for non-streaming requests, or a\n`text/event-stream` of completion chunks 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/CompletionResponse"}},"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 completion chunk JSON object, followed by a blank\nline. Each chunk has the fields of `CompletionResponse`, with each choice\ncarrying the text generated since the previous chunk. 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":["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/completions/create-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.
