---
title: "Completions"
method: POST
path: "/v1/completions"
tags: ["completions"]
---

# Completions

`POST /v1/completions`

Perform a text Completion request.

## Request body

- TextCompletionRequestPayload
  - `model` string, nullable — https://docs.pulze.ai/overview/models Specify the model you'd like Pulze to use. (optional). Can be the full model name, or a subset for multi-matching. Defaults to our dynamic routing, i.e. best model for this request.
  - `max_tokens` integer, nullable — The maximum number of tokens that the response can contain.
  - `temperature` number, nullable — Optionally specify the temperature for this request only. Leave empty to allow Pulze to guess it for you.
  - `top_p` number, nullable — https://octo.ai/docs/text-gen-solution/rest-api#input-parameters A value between 0.0 and 1.0 that controls the probability of the model generating a particular token.
  - `tools` ToolFunctionInput[], nullable
    - `type` 'function'
    - `function` ToolFunctionDetail, required
      - `name` string, required — A unique name for the function
      - `description` string, nullable — A description of the function. Might help the LLM to figure out the structure and parameters
      - `parameters` FunctionParameters, required
        - `type` string — Following JSON schema, this must be 'object'.
        - `properties` object, required — JSON schema's properties
        - `required` string[], nullable, required — List of required parameters
  - `tool_choice` union
    - 'none' | 'auto'
    - ToolChoice
      - `type` 'function' | 'json_object', nullable — (Note: Not supported by all models yet) // `json_object`: If you instruct the model to return a JSON object, the model will respond in a valid JSON format. || `function`: If you set this to function, you must also pass the `function` parameter with extra information. ||
      - `function` ToolChoiceFunction
        - `name` string, required — The name of the function you'd like the code to call
  - `n` integer, nullable — How many completions to generate for each prompt. @default 1
  - `stream` boolean, nullable — Specify if you want the response to be streamed or to be returned as a standard HTTP request. Currently we only support streaming for OpenAI-compatible models.
  - `logprobs` integer, nullable — COMING SOON https://platform.openai.com/docs/api-reference/completions/create#completions/create-logprobs Include the log probabilities on the logprobs most likely tokens, as well the chosen tokens.
  - `stop` union — Stop responding when this sequence of characters is generated. Leave empty to allow the model to decide.
    - string
    - string[]
  - `presence_penalty` number, nullable — https://platform.openai.com/docs/api-reference/completions/create#completions/create-presence_penalty Increase the model's likelihood to talk about new topics
  - `frequency_penalty` number, nullable — https://platform.openai.com/docs/api-reference/completions/create#completions/create-frequency_penalty Increase the model's likelihood to not repeat tokens/words
  - `best_of` integer, nullable — The number of responses to _generate_. Out of those, it will return the best `n`.
  - `logit_bias` object, nullable — COMING SOON https://platform.openai.com/docs/api-reference/completions/create#completions/create-logit_bias Modify the likelihood of specified tokens appearing in the completion. See here for a detailed explanation on how to use: https://help.openai.com/en/articles/5247780-using-logit-bias-to-define-token-probability
  - `response_format` RequestResponseFormat
    - `type` 'text' | 'json_object', required
  - `prompt` union, required — The prompt text sent (for a /completions request)
    - string
    - string[]

## Response `200`

Successful Response

- PulzeEngineResponseCompletion — The response returned to the user by the (text) Completions endpoint
  - `choices` ResponseCompletionChoice[], required
    - `index` integer, required
    - `finish_reason` string, nullable — The reason the model stopped generating tokens. Possible values: "stop", "length", "content_filter", "function_call", "max_tokens", ...
    - `text` string, required
    - `logprobs` integer, nullable
  - `created` integer — Creation timestamp -- in milliseconds (!)
  - `metadata` PulzeEngineResponseMetadata
    - `app_id` string — The ID of the app this request belongs to
    - `model` ModelParts
      - `model` string, required — The name of the model. Can belong to many providers
      - `provider` string, nullable — The provider for the model.
      - `owner` string, nullable — The owner of the model. Sometimes, for a provider/model combination, many instances exist, trained on different data
      - `namespace` string, required — The fully qualified (namespaced) model name
      - `at` string, nullable — Extra model settings inferred from namespace
    - `costs` PulzeEngineTokens
      - `total_tokens` number
      - `prompt_tokens` number
      - `completion_tokens` number
    - `cost_savings` PulzeEngineTokens
      - `total_tokens` number
      - `prompt_tokens` number
      - `completion_tokens` number
    - `generated_artifacts` PulzeGeneratedArtifacts
      - `items` object[] — Generated artifacts
    - `search_results` PulzeSearchResults
      - `items` object[] — Search results
    - `latency` number, nullable — The time it took for the Provider to return a response
    - `labels` object, nullable — Custom labels (metadata) sent along in the request
    - `error` string, nullable — If an error occurs, it will be stored here
    - `scores` RankedScoringModels
      - `best_models` object[]
      - `candidates` object[], nullable
    - `score` number, nullable — The score for the currently used LLM
    - `temperature` union — Temperature used for the request
      - number
      - integer
    - `max_tokens` integer, nullable — Maximum number of tokens that can be used in the request+response.Leave empty to make it automatic, and set to `-1` to use the maximum context size (model-dependent)
    - `status_code` integer, nullable — Status code of the response
    - `retries` integer — The number of retries needed to get the answer. `null` or `0` means no retries were required
    - `extra` object, nullable — Extra data
    - `warning` string, nullable — Show a warning -- deprecation messages, etc.
  - `id` string — This ID gets generated by the database when we save the request
  - `usage` PulzeEngineTokens
    - `total_tokens` number
    - `prompt_tokens` number
    - `completion_tokens` number
  - `model` string, required — The fully qualified model name used by PulzeEngine
  - `object` 'text_completion' | 'chat.completion', required — The type of response object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pulze/apis/pulze-ai-api.md) · [All operations](https://skmtc.net/pulze/apis/pulze-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pulze/pulze-ai-api/revisions/a5e0b539abc5/schema)