> ## Documentation Index
> Fetch the complete documentation index at: https://developer.swytcho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/completions — Swytcho Text Completions API

> Generate text by continuing a raw prompt string. Best for single-turn tasks: summarization, classification, code generation, and template-based workflows.

The `/v1/completions` endpoint takes a raw text prompt and returns one or more generated continuations. Unlike the chat endpoint, there is no message array or role structure — you supply a prompt string and the model completes it. This format is well-suited for single-turn tasks such as summarization, extraction, code generation, and template-based workflows.

## Endpoint

```text theme={null}
POST https://api.swytcho.com/v1/completions
```

## Request Parameters

<ParamField body="model" type="string" required>
  The ID of the model to use. Call [`GET /v1/models`](/api-reference/models) to retrieve the list of models available to your account.
</ParamField>

<ParamField body="prompt" type="string | array" required>
  The prompt(s) to complete. Pass a single string for one prompt or an array of strings to batch multiple prompts in a single request.
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens to generate per completion. Defaults to the model's context limit. Use this to cap response length and manage costs.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between `0` and `2`. Higher values produce more varied output; lower values produce more deterministic output. Defaults to `1`. Avoid combining with `top_p`.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling threshold between `0` and `1`. The model samples from the smallest token set whose cumulative probability exceeds this value. Defaults to `1`. Avoid combining with `temperature`.
</ParamField>

<ParamField body="stream" type="boolean">
  When `true`, the API streams token deltas as server-sent events and sends a final `[DONE]` message. Defaults to `false`.
</ParamField>

<ParamField body="stop" type="string | array">
  One or more sequences at which generation stops. Pass a single string or an array of up to four strings.
</ParamField>

<ParamField body="n" type="integer">
  The number of independent completions to generate for each prompt. Defaults to `1`. Note that generating multiple completions increases token usage proportionally.
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.swytcho.com/v1/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "swytcho-base",
      "prompt": "Summarize the benefits of renewable energy in three bullet points:",
      "max_tokens": 200,
      "temperature": 0.5
    }'
  ```

  ```python Python theme={null}
  import os
  from swytcho import Swytcho

  client = Swytcho(api_key=os.environ["SWYTCHO_API_KEY"])

  response = client.completions.create(
      model="swytcho-base",
      prompt="Summarize the benefits of renewable energy in three bullet points:",
      max_tokens=200,
      temperature=0.5,
  )

  print(response.choices[0].text)
  ```

  ```javascript Node.js theme={null}
  import Swytcho from "swytcho";

  const client = new Swytcho({ apiKey: process.env.SWYTCHO_API_KEY });

  const response = await client.completions.create({
    model: "swytcho-base",
    prompt: "Summarize the benefits of renewable energy in three bullet points:",
    max_tokens: 200,
    temperature: 0.5,
  });

  console.log(response.choices[0].text);
  ```
</CodeGroup>

## Response Fields

<ResponseField name="id" type="string">
  A unique identifier for this completion, prefixed with `cmpl-`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"text_completion"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (seconds) of when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model ID that was used to generate this response.
</ResponseField>

<ResponseField name="choices" type="array">
  An array of generated completion objects. Contains one element per prompt per `n`.

  <Expandable title="Choice object fields">
    <ResponseField name="index" type="integer">
      Zero-based index of this choice in the array.
    </ResponseField>

    <ResponseField name="text" type="string">
      The generated text continuation.
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      The reason generation stopped. One of `"stop"` (natural end or stop sequence hit), `"length"` (hit `max_tokens`), or `"content_filter"` (blocked by safety policy).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics for the request.

  <Expandable title="Usage object fields">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens in the input prompt(s).
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Number of tokens across all generated completions.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens consumed (`prompt_tokens` + `completion_tokens`).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "id": "cmpl-x9y8z7w6v5u4",
  "object": "text_completion",
  "created": 1717200100,
  "model": "swytcho-base",
  "choices": [
    {
      "index": 0,
      "text": "\n• Reduces greenhouse gas emissions and slows climate change.\n• Lowers long-term energy costs through fuel-free generation.\n• Creates local jobs in manufacturing, installation, and maintenance.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 17,
    "completion_tokens": 41,
    "total_tokens": 58
  }
}
```