# Parasail Chat Completions

Parasail provides a fully OpenAI-compatible chat completions endpoint. Point your existing OpenAI SDK at Parasail's base URL—no code changes needed beyond the URL and API key.

## Endpoint compatibility matrix

The table below shows which Parasail products serve each OpenAI-compatible endpoint. All endpoints share the same base URL (`https://api.parasail.io/v1`) and the same bearer-token authentication.

| Endpoint                     | Serverless | Dedicated | Batch |
|------------------------------|------------|-----------|-------|
| `POST /v1/chat/completions`  | Yes        | Yes       | Yes   |
| `POST /v1/completions`       | Yes        | Yes       | Yes   |
| `POST /v1/embeddings`        | Yes        | Yes       | Yes   |
| `POST /v1/responses`         | Yes        | Not documented | No |
| `GET /v1/models`             | Yes        | Yes       | N/A (listing endpoint) |

Batch serves the `/v1/chat/completions` and `/v1/embeddings` endpoints through JSONL input files. See the [Batch API reference](https://docs.parasail.io/parasail-docs/api-reference/batch-api).

This repository documents Responses API usage for the standard gateway and serverless docs. Dedicated Responses API support is not documented.

## Endpoint

```
POST https://api.parasail.io/v1/chat/completions
```

## Authentication

All requests use bearer-token authentication. Pass your API key in the `Authorization` header:

```
Authorization: Bearer <PARASAIL_API_KEY>
```

The OpenAI SDK reads this from the `api_key` argument. See [Authentication](https://docs.parasail.io/parasail-docs/api-reference/authentication) for how to create and store a key.

## Request

### Python (OpenAI SDK)

```
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.parasail.io/v1",
    api_key=os.environ["PARASAIL_API_KEY"],
)

response = client.chat.completions.create(
    model="parasail-deepseek-r1",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of New York?"}
    ],
    max_completion_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)
```

### cURL

```
curl https://api.parasail.io/v1/chat/completions \
  -H "Authorization: Bearer $PARASAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "parasail-deepseek-r1",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of New York?"}
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'
```

## Request parameters

| Parameter          | Type     | Default    | Description  |
|--------------------|----------|------------|--------------|
| `model`            | string   | required   | Model ID (for example, `parasail-deepseek-r1`) or HuggingFace ID |
| `messages`         | array    | required   | Array of message objects with `role` and `content` |
| `temperature`      | float    | 1.0        | Controls randomness (0 = greedy decoding) |
| `top_p`           | float    | 1.0        | Nucleus sampling probability mass |
| `top_k`            | int      | -1         | Limits token selection to top-k tokens (pass in `extra_body`) |
| `max_tokens`       | int      | None       | Maximum tokens to generate |
| `repetition_penalty` | float  | 1.0        | Penalizes repeated tokens |
| `presence_penalty` | float    | 0.0        | Increases likelihood of new tokens |
| `frequency_penalty` | float   | 0.0        | Penalizes frequently occurring tokens |
| `seed`             | int      | None       | Fixed seed for reproducible results |
| `stream`           | boolean  | false      | Stream tokens as they're generated |
| `tools`            | array    | None       | Tool/function definitions for function calling |
| `tool_choice`      | string   | "auto"    | "auto", "required", "none", or specific tool |

These fields follow the OpenAI schema. For exhaustive field semantics, see the [OpenAI chat completions reference](https://platform.openai.com/docs/api-reference/chat/create). For sampling-parameter guidance, see [full parameter details](https://docs.parasail.io/parasail-docs/api-reference/parameters).

## Message roles

| Role      | Description                                            |
|-----------|--------------------------------------------------------|
| `system`  | Sets the model's behavior and persona                   |
| `user`    | The user's input                                      |
| `assistant` | The model's previous response (for multi-turn conversations) |

## Response

A successful request returns a `chat.completion` object. The response shape matches OpenAI:

```
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1727900000,
  "model": "parasail-deepseek-r1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Albany is the capital of New York."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 9,
    "total_tokens": 33
  }
}
```

| Field                      | Description                                   |
|----------------------------|-----------------------------------------------|
| `id`                       | Unique identifier for the completion           |
| `choices[].message.content` | The generated text                             |
| `choices[].finish_reason`  | Why generation stopped (`stop`, `length`, `tool_calls`) |
| `usage`                    | Prompt, completion, and total token counts    |

## Streaming

Set `stream: true` to receive tokens as they are generated. The response is a stream of server-sent events. Each event's data is a `chat.completion.chunk` object whose `choices[].delta` carries the incremental content; the stream ends with a `data: [DONE]` line.

```
stream = client.chat.completions.create(
    model="parasail-deepseek-r1",
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

## Error responses

Errors use OpenAI-compatible status codes and a JSON body with an `error` object (`message`, `type`, `code`).

| Status Code | Description                                                                          |
|-------------|--------------------------------------------------------------------------------------|
| `400`      | Malformed request—invalid JSON, missing required field, or unsupported parameter value |
| `401`      | Missing or invalid API key                                                           |
| `403`      | API key lacks access to the requested model or resource                               |
| `404`      | Model or endpoint not found                                                           |
| `429`      | Rate limit or quota exceeded—back off and retry                                      |
| `500`      | Internal server error—retry with exponential backoff                                  |

## Chat completions vs text completions

Parasail supports both endpoints:

- `/v1/chat/completions`—for dialog-based interactions (chatbots, assistants)
- `/v1/completions`—for single-prompt completion (translation, code generation, email drafting)

## Model availability

List available serverless models:

```
curl https://api.parasail.io/v1/models \
  -H "Authorization: Bearer $PARASAIL_API_KEY"
```

## Next steps

- [Chat completions guide](https://docs.parasail.io/parasail-docs/guides/chat-completions)—messages, roles, base vs instruct models, chat templates
- [Tool/function calling guide](https://docs.parasail.io/parasail-docs/guides/tool-function-calling)—function calling tutorial
- [Structured output guide](https://docs.parasail.io/parasail-docs/guides/structured-output)—JSON-formatted responses
- [Parameters reference](https://docs.parasail.io/parasail-docs/api-reference/parameters)—sampling parameters in depth
- [Serverless overview](https://docs.parasail.io/parasail-docs/products/overview)—using third-party tools like Cline and AnythingLLM