---
title: "Create a chat completion"
method: POST
path: "/v2/ai/chat/completions"
tags: ["AI"]
---

# Create a chat completion

`POST /v2/ai/chat/completions`

OpenAI-compatible chat completions endpoint. Point any OpenAI SDK at baseURL `https://api.squarecloud.app/v2/ai` using your account API key, and call `chat.completions.create`.

Available on Standard, Pro and Enterprise plans. Each plan bounds requests per day, concurrency, pacing between requests and context/output size (Standard: 1,000 requests/day, 16k in / 4k out, 1 concurrent, 5s between requests. Pro: 5,000 requests/day, 24k / 6k, 1 concurrent, 2s. Enterprise: unlimited requests, 32k / 8k, 2 concurrent, no delay). Token usage is billed against your plan's daily AI budget, and each plan also has a daily fair-use allowance on the gateway sized for moderate use (Enterprise gets 5x the base allowance; both reset 00:00 UTC).

The model has a built-in `web_search` it can trigger on its own for current or external information; searches run server-side and only the final answer is returned. You may also declare your own `tools` (OpenAI function-calling format): the model's calls to them come back as a standard `finish_reason: "tool_calls"` response, and you send the results back as `role: "tool"` messages.

Streaming is not supported yet. Error responses use the OpenAI error shape (`{ error: { message, type, code } }`).

## Request body

- object
  - `model` string — Ignored; the response always reports `cubic`.
  - `messages` object[], required — Chat history: objects with `role` (system | user | assistant | tool) and string `content`. Assistant messages may carry `tool_calls`; tool messages need `tool_call_id`.
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
    - `content` string
    - `tool_call_id` string — Required on role "tool" messages.
    - `tool_calls` object[] — On assistant messages: the tool calls being answered.
  - `tools` object[] — Your own tools, in the OpenAI function-calling format: { type: "function", function: { name, description, parameters } }.
  - `tool_choice` unknown
  - `max_tokens` integer — Completion token cap; silently clamped to your plan's output ceiling.
  - `temperature` number
  - `stream` boolean — Must be false/omitted (streaming not supported yet).

## Response `200`

The completion, in the OpenAI chat.completion shape. When the model calls one of YOUR tools, `finish_reason` is `tool_calls` and the message carries `tool_calls` instead of text.

- object
  - `id` string, required
  - `object` string, required
  - `created` integer, required
  - `model` string, required
  - `choices` object[], required
    - `index` integer, required
    - `message` object, required
      - `role` string, required
      - `content` string, required
    - `finish_reason` string, required
  - `usage` object, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `400` — Malformed body, unsupported feature (stream), or the prompt exceeds your plan's context ceiling.
- `401` — The Authorization header is missing, malformed, or the credentials are not valid.
- `403` — The account's plan does not include the public AI API (Standard and up).
- `413` — The request body is larger than the maximum allowed size (100MB).
- `429` — Plan pacing or fair use: a request is already in flight (concurrent_limit_reached), the per-request delay has not elapsed (rate_limit_exceeded), the plan's daily request ceiling is reached (daily_request_limit_reached, resets 00:00 UTC), the plan's daily fair-use allowance on the gateway is reached (daily_spend_limit_reached, resets 00:00 UTC), or the daily AI token budget is spent (daily_limit_reached, resets 00:00 UTC).
- `500` — An unexpected error occurred while processing the request.
- `503` — All model capacity is busy; retry shortly.

---

[API](https://skmtc.dev/squarecloud/apis/square-cloud-api.md) · [All operations](https://skmtc.dev/squarecloud/apis/square-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/squarecloud/square-cloud-api/revisions/54b7733a6b95/schema)