Baseten Messages API
The Messages API from Baseten — 1 operation(s) for messages.
OpenAPI Specification
openapi: 3.1.0
info:
title: Baseten LLM Inference Chat Completions Messages API
version: 1.0.0
description: OpenAI-compatible API for Baseten Model APIs. Use this endpoint to interact with hosted LLMs.
servers:
- url: https://inference.baseten.co
description: Baseten Inference API.
security:
- ApiKeyAuth: []
tags:
- name: Messages
paths:
/v1/messages:
post:
operationId: createMessage
summary: Create a message
description: Creates a response message for the provided conversation. Compatible with the Anthropic Messages API, so the Anthropic SDK works against this endpoint by changing `base_url` and overriding the default `x-api-key` header with `Authorization`.
tags:
- Messages
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessagesRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/MessagesResponse'
'400':
description: 'Bad request: invalid parameters.'
'401':
description: 'Unauthorized: invalid or missing API key. The Anthropic SDK''s default `x-api-key` header is not accepted — pass `Authorization: Bearer <BASETEN_API_KEY>` or `Authorization: Api-Key <BASETEN_API_KEY>`.'
'404':
description: Model not found or does not support the Messages API.
'429':
description: Rate limit exceeded.
'500':
description: Internal server error.
x-codeSamples:
- lang: python
label: Python
source: "import anthropic\nimport os\n\nAPI_KEY = os.environ[\"BASETEN_API_KEY\"]\n\nclient = anthropic.Anthropic(\n base_url=\"https://inference.baseten.co\",\n api_key=API_KEY,\n default_headers={\"Authorization\": f\"Bearer {API_KEY}\"},\n)\n\nresponse = client.messages.create(\n model=\"deepseek-ai/DeepSeek-V4-Pro\",\n max_tokens=1024,\n messages=[\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n)\n\nprint(response.content[0].text)"
- lang: bash
label: cURL
source: "curl https://inference.baseten.co/v1/messages \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Api-Key $BASETEN_API_KEY\" \\\n -d '{\n \"model\": \"deepseek-ai/DeepSeek-V4-Pro\",\n \"max_tokens\": 1024,\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ]\n }'"
components:
schemas:
InputMessage:
additionalProperties: false
type: object
required:
- role
- content
title: InputMessage
description: A message in the conversation.
properties:
role:
type: string
enum:
- user
- assistant
description: The role of the message author. System prompts are passed via the top-level `system` field, not as a message.
content:
anyOf:
- type: string
- type: array
items:
anyOf:
- $ref: '#/components/schemas/TextBlock'
- $ref: '#/components/schemas/ToolUseBlock'
- $ref: '#/components/schemas/ToolResultBlock'
description: The message content. Pass a string for text-only messages or an array of content blocks for messages that include tool calls or tool results.
ToolDefinition:
additionalProperties: false
type: object
required:
- name
- input_schema
title: ToolDefinition
description: A tool the model can call.
properties:
name:
type: string
description: A unique name for the tool.
description:
type: string
description: A description of what the tool does. The model uses this to decide when to call it.
input_schema:
type: object
additionalProperties: true
description: A JSON Schema object describing the tool's expected input.
ToolUseBlock:
additionalProperties: false
type: object
required:
- type
- id
- name
- input
title: ToolUseBlock
description: A tool use content block generated by the model.
properties:
type:
const: tool_use
type: string
description: The block type, always `tool_use`.
id:
type: string
description: A unique identifier for this tool call. Use this as `tool_use_id` in the matching tool result.
name:
type: string
description: The name of the tool being called.
input:
type: object
additionalProperties: true
description: The arguments passed to the tool, matching the tool's `input_schema`.
TextBlock:
additionalProperties: false
type: object
required:
- type
- text
title: TextBlock
description: A text content block.
properties:
type:
const: text
type: string
description: The block type, always `text`.
text:
type: string
description: The text content.
MessagesResponse:
additionalProperties: false
type: object
required:
- id
- type
- role
- content
- model
- stop_reason
- usage
title: MessagesResponse
description: The message response returned by the model.
properties:
id:
type: string
description: A unique identifier for this message, such as `msg_abc123`.
type:
const: message
type: string
description: The object type, always `message`.
role:
const: assistant
type: string
description: The role of the generated message, always `assistant`.
content:
type: array
items:
anyOf:
- $ref: '#/components/schemas/TextBlock'
- $ref: '#/components/schemas/ToolUseBlock'
description: An array of content blocks generated by the model. Text responses contain a single `text` block; responses that invoke tools contain `tool_use` blocks.
model:
type: string
description: The model slug that produced the response.
stop_reason:
type: string
enum:
- end_turn
- max_tokens
- stop_sequence
- tool_use
description: 'Why the model stopped generating: `end_turn` (natural stop), `max_tokens` (hit the `max_tokens` limit), `stop_sequence` (matched a `stop_sequences` entry), or `tool_use` (model invoked a tool).'
stop_sequence:
type: string
nullable: true
description: The stop sequence that was matched, if `stop_reason` is `stop_sequence`. Otherwise `null`.
usage:
$ref: '#/components/schemas/Usage'
description: Token usage statistics for the request.
Usage:
additionalProperties: true
type: object
title: Usage
description: Token usage statistics.
properties:
input_tokens:
type: integer
description: The number of input tokens processed.
output_tokens:
type: integer
description: The number of output tokens generated.
ToolResultBlock:
additionalProperties: false
type: object
required:
- type
- tool_use_id
- content
title: ToolResultBlock
description: A tool result content block supplied by the user in response to a tool call.
properties:
type:
const: tool_result
type: string
description: The block type, always `tool_result`.
tool_use_id:
type: string
description: The `id` of the `tool_use` block this result responds to.
content:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/TextBlock'
description: The tool's output. Pass a string for simple results or an array of text blocks for structured output.
is_error:
type: boolean
default: false
description: Set to `true` if the tool call raised an error.
MessagesRequest:
additionalProperties: false
type: object
required:
- model
- messages
- max_tokens
title: MessagesRequest
description: Request body for creating a message.
properties:
model:
type: string
title: Model
description: The model slug to use. Find available models at [Model APIs](https://app.baseten.co/model-apis/create).
messages:
type: array
title: Messages
description: The conversation history as an ordered list of input messages. Alternating `user` and `assistant` roles are expected; the final message must be from the `user`.
items:
$ref: '#/components/schemas/InputMessage'
max_tokens:
type: integer
minimum: 1
title: Max Tokens
description: The maximum number of tokens to generate in the response. Required by the Messages API. The response may be shorter if it finishes naturally or hits a stop sequence.
system:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/TextBlock'
title: System
description: A system prompt that sets the model's behavior. Pass either a single string or an array of text content blocks.
temperature:
type: number
minimum: 0
maximum: 1
default: 1
title: Temperature
description: 'Controls randomness. Lower values are more deterministic. Range: 0 to 1.'
top_p:
type: number
exclusiveMinimum: 0
maximum: 1
title: Top P
description: 'Nucleus sampling: only consider tokens with cumulative probability up to this value.'
top_k:
type: integer
minimum: 0
title: Top K
description: Limits token selection to the top K most probable tokens at each step.
stop_sequences:
type: array
items:
type: string
title: Stop Sequences
description: Custom text sequences that will stop generation. When a stop sequence is hit, `stop_reason` is `stop_sequence` and `stop_sequence` contains the matched string.
stream:
type: boolean
default: false
title: Stream
description: If `true`, the response is streamed as server-sent events. Each event has a `type` such as `message_start`, `content_block_delta`, or `message_stop`.
tools:
type: array
items:
$ref: '#/components/schemas/ToolDefinition'
title: Tools
description: A list of tools the model may call. Each tool has a `name`, `description`, and `input_schema` (a JSON Schema object).
tool_choice:
$ref: '#/components/schemas/ToolChoice'
description: Controls which tool (if any) the model must call.
metadata:
type: object
title: Metadata
description: An object describing metadata about the request. Supports `user_id` for abuse detection.
properties:
user_id:
type: string
description: An external identifier for the end user.
ToolChoice:
oneOf:
- type: object
required:
- type
properties:
type:
const: auto
type: string
description: The model decides whether to call a tool.
disable_parallel_tool_use:
type: boolean
default: false
description: If `true`, restricts the model to calling at most one tool per response.
- type: object
required:
- type
properties:
type:
const: any
type: string
description: The model must call a tool but may pick which one.
- type: object
required:
- type
- name
properties:
type:
const: tool
type: string
description: The model must call the named tool.
name:
type: string
description: The exact name of the tool to call.
- type: object
required:
- type
properties:
type:
const: none
type: string
description: The model must not call any tool.
title: ToolChoice
description: Controls which tool (if any) the model calls.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'Use `Api-Key` as the scheme in the Authorization header: `Authorization: Api-Key YOUR_API_KEY`.'