chat completions.md

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.

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 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. For sampling-parameter guidance, see full parameter details.

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

See the OpenAI response object reference for every field.

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:

Model availability

List available serverless models:

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

Next steps