API Reference

Chat completions

The primary inference endpoint, OpenAI-compatible chat with streaming, tools, JSON mode, reasoning, and vision.

Endpoint

POST https://inference.pearlresearch.ai/v1/chat/completions

Request body

Parameter	Type	Notes
model	string	Required. A catalog model ID, e.g. `deepseek-ai/DeepSeek-V4-Pro`, the `id` field from `GET /models`.
messages	array	Required. The conversation, oldest first. Roles: `system`, `user`, `assistant`, `tool`. A user message's `content` is a string, or an array of `text` / `image_url` parts on vision models (images as base64 data URIs only, see Vision).
max_tokens	integer	Cap on generated tokens, on reasoning models the thinking counts against it. Hitting the cap sets `finish_reason: "length"`. Per-model ceilings are the `max_output_length` on `GET /models`.
temperature	number	Sampling temperature, 0–2. Lower is more deterministic.
top_p	number	Nucleus sampling mass, 0–1.
top_k	integer	Sample only from the k most likely tokens (0–1024). A Pearl extension, pass via `extra_body` in the OpenAI SDKs.
min_p	number	Drop tokens below this probability relative to the top token (0–1). Extension via `extra_body`; not all models, check `supported_sampling_parameters`.
frequency_penalty	number	−2 to 2. Positive values discourage token repetition by frequency.
presence_penalty	number	−2 to 2. Positive values discourage reusing tokens that already appeared.
stop	string[]	Up to 4 non-empty sequences that end generation when produced.
seed	integer	Best-effort determinism for repeated sampling, not a reproducibility guarantee.
stream	boolean	Stream the response as server-sent events, see Streaming and the chunk shape below.
response_format	object	`{"type": "text"}` (default) or `{"type": "json_object"}` for JSON mode. The stricter `json_schema` type is not available.
tools	array	Function tool definitions (`{"type": "function", "function": {…}}`) the model may call, see Function calling.
reasoning	object	The one reasoning control on reasoning models: `{"enabled": bool, "effort": string, "max_tokens": int}`, all members optional. Effort is `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`, resolved per model; `{"effort": "none"}` disables thinking entirely (the reply then carries no `reasoning`). Omission keeps the model default, which on GLM-5.2 is adaptive thinking. Via `extra_body` in the OpenAI Python SDK. Provider-native switches (`reasoning_effort`, `thinking`, `chat_template_kwargs.enable_thinking`, and their siblings) return `400` on key presence.

Parameters not listed here are outside the documented surface, some OpenAI parameters may be accepted, but their behavior isn't guaranteed. Per-model parameter support is listed in supported_sampling_parameters on GET /models.

Example request

curl https://inference.pearlresearch.ai/v1/chat/completions \
  -H "Authorization: Bearer $PEARL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5.2",
    "messages": [
      {"role": "system", "content": "You are terse."},
      {"role": "user", "content": "Why is the sky blue?"}
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

Response

Field	Type	Notes
id	string	Completion ID, log it for request-level forensics.
object	string	`chat.completion`, or `chat.completion.chunk` when streaming.
created	integer	Unix timestamp (seconds).
model	string	The model that served the request.
choices[0].message	object	`role` + `content`; reasoning models add `reasoning`, tool use adds `tool_calls` (with `content: null`).
choices[0].finish_reason	string	`stop` (natural end or stop sequence), `length` (hit `max_tokens`), or `tool_calls`.
usage	object	`prompt_tokens`, `completion_tokens`, `total_tokens`, what you're billed on. Worker-dependent details: `prompt_tokens_details.cached_tokens` and `completion_tokens_details.reasoning_tokens`.
system_fingerprint	string	Identifies the serving build; useful when reporting issues.

Example response

{
  "id": "chatcmpl-2de22e60-5d2a-48e7-acfa-28c53fd9da40",
  "object": "chat.completion",
  "created": 1785229039,
  "model": "zai-org/GLM-5.2",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "logprobs": null,
      "message": {
        "role": "assistant",
        "content": "Rayleigh scattering. …",
        "reasoning": "The user wants a terse answer. The dominant effect is …"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 92,
    "total_tokens": 113,
    "prompt_tokens_details": {"cached_tokens": 0}
  },
  "system_fingerprint": "vllm-0.25.1-dp8-ep-3d6b3b17"
}

Streaming response

With stream: true the response is a server-sent-event stream of chat.completion.chunk objects terminated by data: [DONE]. Each chunk's choices[0].delta carries the increment (content, reasoning, or tool_calls fragments); the last content chunk carries finish_reason:

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1785229039,"model":"zai-org/GLM-5.2","choices":[{"index":0,"delta":{"content":" scattering"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1785229039,"model":"zai-org/GLM-5.2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Errors

Error responses are JSON with a request_id. The status codes and retry guidance live in the Inference API overview.