# Create a text completion

```http
POST /completions
```

Base URL: `https://ai.aur.lu/v1`

Operation ID: `createInferenceCompletion`

Authentication: PortalToken (HTTP bearer)

Generate text from a prompt. Requires the execute:inference:requests
permission and access to inference. Prepaid accounts must have positive
inference credit. Select a model from GET /models; support depends on
the selected model.

With stream=true, the response is an SSE stream of JSON text completion
chunks with choices[].text, followed by data: [DONE]. Clients must accept
usage-only chunks with an empty choices array. Errors before streaming
use an HTTP error response; an interrupted stream is not a complete response.

## Request body (required)

Content type: `application/json`

Supported options and defaults depend on the selected model.

- `model` (string, required) — Exact public ID or compatibility alias from GET /models.
- `stream` (boolean, default: `false`)
- `stream_options` (object)
  - `include_usage` (boolean) — Streaming responses include usage information. Clients must accept usage-only chunks with an empty choices array.
- `max_tokens` (integer) — Maximum generated tokens; model-dependent limits apply.
- `temperature` (number) — Sampling temperature; range and default depend on the selected model.
- `top_p` (number) — Nucleus sampling probability.
- `n` (integer) — Number of choices where supported.
- `stop` (one of string | array of string) — Stop sequence or sequences where supported.
  - `variant 1` (string, nullable)
  - `variant 2` (array of string)
- `presence_penalty` (number)
- `frequency_penalty` (number)
- `seed` (integer<int64>)
- `user` (string) — Optional end-user identifier.
- `prompt` (one of string | array of string | array of integer | array of array of integer, required) — Text, a batch of texts, token IDs, or a batch of token ID sequences; model support varies.
  - `variant 1` (string)
  - `variant 2` (array of string)
  - `variant 3` (array of integer)
  - `variant 4` (array of array of integer)
- `echo` (boolean)
- `suffix` (string, nullable)
- `logprobs` (integer, nullable)
- `best_of` (integer)

Example:

```json
{
  "model": "deepseek/deepseek-v4-flash",
  "prompt": "Once upon a time",
  "max_tokens": 128
}
```

## Responses

### 200 — A JSON text completion, or SSE chunks when stream=true. Streaming ends with data: [DONE].

- `X-Aurora-Resolved-Model` (string) — Canonical model selected for this request. The response body retains the requested model ID or alias.

Content type: `application/json`

- `id` (string, required)
- `object` (string, required, one of: `text_completion`)
- `created` (integer<int64>, required) — Unix timestamp in seconds.
- `model` (string, required) — Public model ID.
- `usage` (object, nullable)
  - `prompt_tokens` (integer<int64>)
  - `completion_tokens` (integer<int64>)
  - `total_tokens` (integer<int64>)
  - `prompt_tokens_details` (object)
    - `cached_tokens` (integer<int64>)
  - `completion_tokens_details` (object)
- `choices` (array of object, required)
  - items (object)
    - `index` (integer)
    - `text` (string)
    - `finish_reason` (string, nullable)
    - `logprobs` (object, nullable)

Example:

```json
{
  "id": "cmpl-example",
  "object": "text_completion",
  "created": 1788998400,
  "model": "deepseek/deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "text": ", there was a friendly dragon.",
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 7,
    "total_tokens": 11
  }
}
```

Content type: `text/event-stream`

SSE data frames contain JSON chunks with id, object=text_completion, created, model, choices (index, text, finish_reason, logprobs), and optional usage.

Type: `string`

Example:

```text
data: {"id":"cmpl-example","object":"text_completion","created":1788998400,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"text":", there was a friendly dragon.","finish_reason":null,"logprobs":null}]}

data: {"id":"cmpl-example","object":"text_completion","created":1788998400,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"text":"","finish_reason":"stop","logprobs":null}]}

data: {"id":"cmpl-example","object":"text_completion","created":1788998400,"model":"deepseek/deepseek-v4-flash","choices":[],"usage":{"prompt_tokens":4,"completion_tokens":7,"total_tokens":11}}

data: [DONE]
```

### 400 — Invalid request. Send an application/json body with the required fields.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 401 — Missing, invalid, or expired bearer token.

Content type: `application/json`

- `message` (string, required)

### 402 — Insufficient prepaid inference credit. Add credits in the Portal before retrying.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

Example:

```json
{
  "error": {
    "message": "insufficient prepaid inference credit",
    "type": "billing_error"
  }
}
```

### 403 — Missing required permission or account access to inference.

Content type: `application/json`

- `variant 1` (object, example: `{"message":"Missing permission execute:inference:requests"}`)
  - `message` (string, required)
- `variant 2` (object, example: `{"error":{"message":"insufficient prepaid inference credit","type":"billing_error"}}`)
  - `error` (object, required)
    - `message` (string, required)
    - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 404 — Unknown or unavailable model, or unsupported endpoint. Refresh GET /models to discover available IDs.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

Example:

```json
{
  "error": {
    "message": "model not found",
    "type": "invalid_request_error"
  }
}
```

### 429 — Request rate limit exceeded. Retry after a delay.

Content type: `application/json`

Type: `any`

### 500 — The service could not process the request.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 502 — The service could not complete the inference request. Retry after a delay.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 503 — Service is temporarily unavailable. Retry after the indicated delay.

- `Retry-After` (integer) — Suggested delay in seconds before retrying.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

Example:

```json
{
  "error": {
    "message": "service temporarily unavailable",
    "type": "service_unavailable"
  }
}
```