---
title: "Text generation"
method: POST
path: "/v1/completions"
tags: ["Generation API"]
---

# Text generation

`POST /v1/completions`

## Request

- Base URL: `https://api.writer.com`
- URL: `https://api.writer.com/v1/completions`
- Auth: HTTP bearer

Generate text completions using the specified model and prompt. This endpoint is useful for text generation tasks that don't require conversational context.

## Request body

- CompletionsRequest
  - `model` string, required: The [ID of the model](https://dev.writer.com/home/models) to use for generating text. This can be a Palmyra model such as `palmyra-x5` or `palmyra-x4`, or the ID of an [external model](https://dev.writer.com/home/external-models) configured for your organization.
  - `prompt` string, required: The input text that the model will process to generate a response.
  - `max_tokens` integer: The maximum number of tokens that the model can generate in the response.
  - `temperature` number, double: Controls the randomness of the model's outputs. Higher values lead to more random outputs, while lower values make the model more deterministic.
  - `top_p` number, double: Used to control the nucleus sampling, where only the most probable tokens with a cumulative probability of top_p are considered for sampling, providing a way to fine-tune the randomness of predictions.
  - `stop` union: Specifies stopping conditions for the model's output generation. This can be an array of strings or a single string that the model will look for as a signal to stop generating further tokens.
    - string[]
    - string
  - `best_of` integer: Specifies the number of completions to generate and return the best one. Useful for generating multiple outputs and choosing the best based on some criteria.
  - `random_seed` integer: A seed used to initialize the random number generator for the model, ensuring reproducibility of the output when the same inputs are provided.
  - `stream` boolean: Determines whether the model's output should be streamed. If true, the output is generated and sent incrementally, which can be useful for real-time applications.

## Response `200`

Successful response

- CompletionsResponse
  - `choices` CompletionsChoice[], required: A list of choices generated by the model, each containing the text of the completion and associated metadata such as log probabilities.
    - `text` string, required: The generated text output from the model, which forms the main content of the response.
    - `log_probs` Logprobs, nullable
      - `content` LogprobsToken[], nullable, required
        - `token` string, required
        - `logprob` number, double, required
        - `bytes` integer[]
        - `top_logprobs` TopLogProb[], required
          - `token` string, required
          - `logprob` number, double, required
          - `bytes` integer[]
      - `refusal` LogprobsToken[], nullable, required
        - `token` string, required
        - `logprob` number, double, required
        - `bytes` integer[]
        - `top_logprobs` TopLogProb[], required
          - `token` string, required
          - `logprob` number, double, required
          - `bytes` integer[]
  - `model` string: The identifier of the model that was used to generate the responses in the 'choices' array.

## Changes

- **2025-02-25** `3d3b2fe43375`: 1 breaking
  - the response property `choices/items/log_probs` became nullable for the status `200`
- **2024-10-04** `2ad4cffb18a0`: 2 info
  - the response property `choices/items/log_probs/content` became required for the status `200`
  - the response property `choices/items/log_probs/refusal` became required for the status `200`
- **2024-10-03** `4a11c63c7cb5`: 1 breaking, 4 warning, 3 info
  - removed the required property `items/data` from the response with the `200` status (media type: text/event-stream)
  - removed the optional property `choices/items/log_probs/text_offset` from the response with the `200` status (media type: application/json)
  - removed the optional property `choices/items/log_probs/token_log_probs` from the response with the `200` status (media type: application/json)
  - removed the optional property `choices/items/log_probs/tokens` from the response with the `200` status (media type: application/json)
  - …4 more
- **2024-09-24** `5d34056e0e74`: 1 warning, 1 info
  - removed the optional property `items/data/choices/items/message/tool_calls` from the response with the `200` status
  - removed the `tool_calls` enum value from the `items/data/choices/items/finish_reason` response property for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/writer/apis/writer-api/changes/v1/completions/post.md)

---

[API](https://skmtc.dev/writer/apis/writer-api.md) - [All operations](https://skmtc.dev/writer/apis/writer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/writer/apis/writer-api/revisions/59865afc5779?raw)