curl --request POST \
  --url https://inference.square1.dev/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "deepseek-v4-pro",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}
'

{
  "id": "<string>",
  "object": "chat.completion",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "assistant",
        "content": "<string>",
        "reasoning": "<string>",
        "tool_calls": [
          {
            "id": "<string>",
            "type": "function",
            "function": {
              "name": "<string>",
              "arguments": "<string>"
            }
          }
        ]
      },
      "finish_reason": "<string>"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  },
  "wellspring": {
    "request_id": "<string>",
    "session": {
      "used_pct": 123,
      "remaining_pct": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "resets_in_seconds": 123,
      "request_pct": 123
    },
    "weekly": {
      "used_pct": 123,
      "remaining_pct": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "resets_in_seconds": 123,
      "request_pct": 123
    },
    "rpm": {
      "limit": 123,
      "remaining": 123
    }
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

Chat

Create a chat completion

OpenAI-compatible chat completion. Supports streaming (SSE), tool calling (on models with supports_tools), vision input (on models with supports_images), and the reasoning_effort vendor extension (on models with supports_reasoning).

Accepted request fields are exactly the ones listed below. OpenAI fields not listed (n, presence_penalty, frequency_penalty, logprobs, seed, response_format, stream_options) are not part of the contract.

BYOK model syntax — a model value starting with @ routes the request through your own registered provider credential instead of the Square1 pool: @<provider>/<upstreamModelId> or @<provider>:<label>/<upstreamModelId>. See the BYOK guide.

POST

chat

completions

curl --request POST \
  --url https://inference.square1.dev/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "deepseek-v4-pro",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}
'

{
  "id": "<string>",
  "object": "chat.completion",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "assistant",
        "content": "<string>",
        "reasoning": "<string>",
        "tool_calls": [
          {
            "id": "<string>",
            "type": "function",
            "function": {
              "name": "<string>",
              "arguments": "<string>"
            }
          }
        ]
      },
      "finish_reason": "<string>"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  },
  "wellspring": {
    "request_id": "<string>",
    "session": {
      "used_pct": 123,
      "remaining_pct": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "resets_in_seconds": 123,
      "request_pct": 123
    },
    "weekly": {
      "used_pct": 123,
      "remaining_pct": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "resets_in_seconds": 123,
      "request_pct": 123
    },
    "rpm": {
      "limit": 123,
      "remaining": 123
    }
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "resets_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

A Square1 API key: Authorization: Bearer sq-arca-... (legacy ws-... keys remain valid). Create and rotate keys from the dashboard.

Body

application/json

model

string

required

A catalog model id from GET /v1/models, or a BYOK reference (@provider/model or @provider:label/model).

Examples:

"deepseek-v4-pro"

"@openai/gpt-5.1"

messages

(System message · object | User message · object | Assistant message · object | Tool result message · object)[]

required

System message
User message
Assistant message
Tool result message

Show child attributes

stream

boolean

default:false

temperature

number

max_tokens

integer

Output token cap. Clamped to the model's max_output_tokens.

top_p

number

stop

reasoning_effort

string

Vendor extension for models with supports_reasoning. The accepted values are per-model (subsets of none, low, high, max); an unsupported value returns 400 invalid_reasoning_effort with the allowed values in the message.

tools

object[]

Function tools (models with supports_tools only; otherwise 400 tools_not_supported). Up to 128 tools; names must match ^[a-zA-Z0-9_-]{1,64}$.

Show child attributes

tool_choice

Available options:

auto,

required,

none

parallel_tool_calls

boolean

Response

Completion result.

With stream: false the body is a single JSON object that carries the exact post-request quota receipt in the wellspring block.

With stream: true the body is a Server-Sent Events stream of data: lines, each a ChatCompletionChunk JSON object. The stream may interleave SSE comment lines (: ping) as keep-alive when the upstream is idle for more than 8 seconds — clients must ignore them. The final frames are: a chunk carrying usage and the wellspring receipt, then data: [DONE].

string

required

object

any

required

created

integer

required

model

string

required

choices

object[]

required

Show child attributes

usage

object

required

Show child attributes

wellspring

object

Per-request quota receipt (vendor extension, sibling of usage). Exact post-request figures — unlike the response headers, which are reservation-time estimates on streaming requests. In streams it arrives as its own frame immediately before data: [DONE]. This block is best-effort: on internal failure it is omitted rather than failing the request.

Show child attributes

Chat

Embeddings

Models

Illustration

Account

Create a chat completion

Authorizations

Body

Response