---
title: "Chat Completions"
method: POST
path: "/v1/chat/completions"
tags: ["Generative Models"]
---

# Chat Completions

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.jina.ai`
- URL: `https://api.jina.ai/v1/chat/completions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/jina/apis/jina-search-foundation-api/docs/v1/chat/completions/post.ts> (a function with typed inputs; its response is checked against the schema)

Transcribe a document image. Send the page as an `image_url` content part and the reply is its text; `response_format` with a `json_schema` constrains that to a schema instead.

## Request body

- ChatCompletionRequest: The public request body. Every field here reaches the engine.
  - `messages` ChatMessage[], required
    - `role` 'system' | 'developer' | 'user' | 'assistant', required
    - `content` union
      - string
      - union[]
        - union
          - TextContentPart
            - `type` 'text', required
            - `text` string, required
          - ImageContentPart
            - `type` 'image_url', required
            - `image_url` ImageURL, required
              - …
  - `model` 'jina-ocr-v1', required: The model to use.
  - `stream` boolean
  - `stream_options` StreamOptions
    - `include_usage` boolean: Report token usage in the stream. When set, every chunk carries `usage: null` and a final chunk carries the totals. When unset, no chunk mentions usage and the final chunk is not sent at all.
  - `max_completion_tokens` integer, nullable
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `stop` union
    - string
    - string[]
  - `seed` integer, nullable
  - `logprobs` boolean, nullable
  - `top_logprobs` integer, nullable
  - `logit_bias` object, nullable
  - `response_format` union
    - ResponseFormatText
      - `type` 'text', required
    - ResponseFormatJSONObject
      - `type` 'json_object', required
    - ResponseFormatJSONSchema
      - `type` 'json_schema', required
      - `json_schema` JSONSchemaSpec, required
        - `name` string, required
        - `schema` object, nullable

## Response `200`

An OpenAI chat completion, or a stream of `chat.completion.chunk` events when `stream` is true.

- unknown

## Other responses

- `400`: Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`
- `401`: Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`
- `403`: Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`
- `404`: Not Found: `RESOURCE_NOT_FOUND`
- `409`: Conflict: `CONFLICT_RESOURCE_BUSY`
- `422`: The request body failed schema validation. `errors` names each field.
- `429`: Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`
- `500`: Internal Server Error: `INTERNAL_ERROR`
- `503`: Service Unavailable: `SERVICE_UNAVAILABLE`
- `504`: Gateway Timeout: `SERVICE_TIMEOUT`

## Changes

- **2026-10-10** `e1c9fccc2a1a`: 13 breaking, 12 warning, 12 info
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `401`
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `403`
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `429`
  - response property `errors` list-of-types was widened by adding types `null` to media type `application/json` of response `422`
  - …33 more
- **2026-09-10** `d16aa597a85d`: 2 breaking, 3 info
  - added required request body
  - the response's body type changed from `object` to no type for status `200`
  - api tag `Generative Models` added
  - api tag `Search Foundation Models` removed
  - …1 more
- **2026-04-14** `a92cc1f233eb`: 2 info
  - api tag `Search Foundation Models` added
  - api tag `Vision Language Models` removed
- **2026-02-04** `9bb79ddff926`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/jina/apis/jina-search-foundation-api/changes/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/jina/apis/jina-search-foundation-api.md) - [All operations](https://skmtc.dev/jina/apis/jina-search-foundation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jina/apis/jina-search-foundation-api/revisions/e1c9fccc2a1a?raw)