LLM API

Chat Completions

Spice provides an OpenAI compatible chat completion AI at https://data.spiceai.io/v1/chat/completions. Authorize with the endpoint using a Project API key.

The project requires a configured and deployed model to respond to chat completion requests.

For more information about using chat completions, refer to the OpenAI documentation.

Create Chat Completion

POST/v1/chat/completions

Creates a model response for the given chat conversation.

Header parameters

Name	Type	Required	Description
`X-API-Key`	string	Yes	Your project API key. See API keys.

Request body

Required

Create a chat completion request using a language model.

application/json

audioobject | null
Parameters for audio output. Required when audio output is requested with modalities: ["audio"]. Learn more.
2 properties
- formatstringRequired
  Specifies the output audio format. Must be one of wav, aac, mp3, flac, opus, or pcm16.
  - Allowed values: wav, aac, mp3, flac, opus, pcm16
- voice"alloy" | "ash" | "ballad" | "coral" | "echo" | "fable" | "nova" | "onyx" | "sage" | "shimmer" | objectRequired
  The voice the model uses to respond. Supported voices are alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, and shimmer.
  11 options
  One of
  "alloy"string
  Value: alloy
  "ash"string
  Value: ash
  "ballad"string
  Value: ballad
  "coral"string
  Value: coral
  "echo"string
  Value: echo
  "fable"string
  Value: fable
  "nova"string
  Value: nova
  "onyx"string
  Value: onyx
  "sage"string
  Value: sage
  "shimmer"string
  Value: shimmer
  object with otherobject
  otherstringRequired
frequency_penaltynumber (float) | null
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
function_call"none" | "auto" | object | null
Deprecated in favor of tool_choice.

Controls which (if any) function is called by the model. none means the model will not call a function and instead generates a message. auto means the model can pick between generating a message or calling a function. Specifying a particular function via {"name": "my_function"} forces the model to call that function.

none is the default when no functions are present. auto is the default if functions are present.
3 options
One of
"none"string
The model does not call a function, and responds to the end-user.
Value: none
"auto"string
The model can pick between an end-user or calling a function.
Value: auto
object with Functionobject
Forces the model to call the specified function.
FunctionobjectRequired
Forces the model to call the specified function.
1 property
namestringRequired
functionsarray of object | nullDeprecated
Deprecated in favor of tools.

A list of functions the model may generate JSON inputs for.
3 properties
- descriptionstring | null
  A description of what the function does, used by the model to choose when and how to call the function.
- namestringRequired
  The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
- parametersanyRequired
  The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.
  
  Omitting parameters defines a function with an empty parameter list.
logit_biasmap of integer (int32) | null
Modify the likelihood of specified tokens appearing in the completion.

Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
logprobsboolean | null
Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.
max_completion_tokensinteger (int32) | null
An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
- Minimum: 0
max_tokensinteger (int32) | nullDeprecated
The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is now deprecated in favor of max_completion_tokens, and is not compatible with o-series models.
- Minimum: 0
messagesarray of objectRequired
A list of messages comprising the conversation so far. Depending on the model you use, different message types (modalities) are supported, like text, images, and audio.
6 options
One of
role: developerobject
contentstring | array of objectRequired
The contents of the developer message.
2 options
One of
stringstring
array of objectarray of object
textstringRequired
typestringRequired
Value: text
namestring | null
An optional name for the participant. Provides the model information to differentiate between participants of the same role.
rolestringRequired
Value: developer
role: systemobject
contentstring | array of objectRequired
The contents of the system message.
2 options
One of
stringstring
The text contents of the system message.
array of objectarray of object
An array of content parts with a defined type. For system messages, only type text is supported.
textstringRequired
typestringRequired
Value: text
namestring | null
An optional name for the participant. Provides the model information to differentiate between participants of the same role.
rolestringRequired
Value: system
role: userobject
contentstring | array of objectRequired
The contents of the user message.
2 options
One of
stringstring
The text contents of the message.
array of objectarray of object
An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text, image, or audio inputs.
One of
type: textobject
textstringRequired
typestringRequired
Value: text
type: image_urlobject
image_urlobjectRequired
2 properties
detailstring | null
Specifies the detail level of the image. Learn more in the Vision guide.
Allowed values: auto, low, high
urlstringRequired
Either a URL of the image or the base64 encoded image data.
typestringRequired
Value: image_url
type: input_audioobject
Learn about audio inputs.
input_audioobjectRequired
2 properties
datastringRequired
Base64 encoded audio data.
formatstringRequired
The format of the encoded audio data. Currently supports "wav" and "mp3".
Allowed values: wav, mp3
typestringRequired
Value: input_audio
type: fileobject
fileobjectRequired
3 properties
file_datastring | null
The base64 encoded file data, used when passing the file to the model as a string.
file_idstring | null
The ID of an uploaded file to use as input.
filenamestring | null
The name of the file, used when passing the file to the model as a string.
typestringRequired
Value: file
namestring | null
An optional name for the participant. Provides the model information to differentiate between participants of the same role.
rolestringRequired
Value: user
role: assistantobject
audioobject | null
Data about a previous audio response from the model. Learn more.
1 property
idstringRequired
Unique identifier for a previous audio response from the model.
contentstring | array of object | null
The contents of the assistant message. Required unless tool_calls or function_call is specified.
2 options
One of
stringstring
The text contents of the message.
array of objectarray of object
An array of content parts with a defined type. Can be one or more of type text, or exactly one of type refusal.
One of
type: textobject
textstringRequired
typestringRequired
Value: text
type: refusalobject
refusalstringRequired
The refusal message generated by the model.
typestringRequired
Value: refusal
function_callobject | null
Deprecated and replaced by tool_calls. The name and arguments of a function that should be called, as generated by the model.
2 properties
argumentsstringRequired
The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
namestringRequired
The name of the function to call.
namestring | null
An optional name for the participant. Provides the model information to differentiate between participants of the same role.
refusalstring | null
The refusal message by the assistant.
tool_callsarray of object | null
2 options
One of
type: functionobject
functionobjectRequired
The function that the model called.
2 properties
argumentsstringRequired
The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
namestringRequired
The name of the function to call.
idstringRequired
The ID of the tool call.
typestringRequired
Value: function
type: customobject
custom_toolobjectRequired
The custom tool that the model called.
2 properties
inputstringRequired
The input for the custom tool call generated by the model.
namestringRequired
The name of the custom tool to call.
idstringRequired
The ID of the tool call.
typestringRequired
Value: custom
rolestringRequired
Value: assistant
role: toolobject
Tool message
contentstring | array of objectRequired
The contents of the tool message.
2 options
One of
stringstring
The text contents of the tool message.
array of objectarray of object
An array of content parts with a defined type. For tool messages, only type text is supported.
textstringRequired
typestringRequired
Value: text
tool_call_idstringRequired
rolestringRequired
Value: tool
role: functionobject
contentstring | null
The return value from the function call, to return to the model.
namestringRequired
The name of the function to call.
rolestringRequired
Value: function
metadataany
Developer-defined tags and values used for filtering completions in the dashboard.
modalitiesarray of string | null
Output types that you would like the model to generate. Most models are capable of generating text, which is the default:

["text"] The gpt-4o-audio-preview model can also be used to generate audio. To request that this model generate both text and audio responses, you can use:

["text", "audio"]
- Allowed values: text, audio
modelstringRequired
Model ID used to generate the response, like gpt-4o or o3. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
ninteger (int32) | null
How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs.
- Minimum: 0
parallel_tool_callsboolean | null
Whether to enable parallel function calling during tool use.
predictionobject | null
Configuration for a Predicted Output, which can greatly improve response times when large parts of the model response are known ahead of time. This is most common when you are regenerating a file with only minor changes to most of the content.
2 properties
- contentstring | array of objectRequired
  The type of the predicted content you want to provide. This type is currently always content.
  2 options
  One of
  stringstring
  The content used for a Predicted Output. This is often the text of a file you are regenerating with minor changes.
  array of objectarray of object
  An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text inputs.
  textstringRequired
- typestringRequired
  - Value: content
presence_penaltynumber (float) | null
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
prompt_cache_keystring | null
Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the user field. Learn more.
reasoning_effortstring | null
Constrains effort on reasoning for reasoning models. Currently supported values are minimal, low, medium, and high. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Note: The gpt-5-pro model defaults to (and only supports) high reasoning effort.
- Allowed values: none, minimal, low, medium, high, xhigh
response_formatobject | null
An object specifying the format that the model must output.

Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.
3 options
One of
type: textobject
The type of response format being defined: text
typestringRequired
Value: text
type: json_objectobject
The type of response format being defined: json_object
typestringRequired
Value: json_object
type: json_schemaobject
The type of response format being defined: json_schema
json_schemaobjectRequired
4 properties
descriptionstring | null
A description of what the response format is for, used by the model to determine how to respond in the format.
namestringRequired
The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
schemaany
The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.
strictboolean | null
Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true. To learn more, read the Structured Outputs guide.
typestringRequired
Value: json_schema
safety_identifierstring | null
A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies.

The IDs should be a string that uniquely identifies each user. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more.
seedinteger (int64) | nullDeprecated
This feature is in Beta.

If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.

Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend.
service_tierstring | null
Specifies the processing type used for serving the request.
- If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.
- If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
- If set to 'flex' or 'priority', then the request will be processed with the corresponding service tier.
- When not set, the default behavior is 'auto'.
When the service_tier parameter is set, the response body will include the service_tier value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.
- Allowed values: auto, default, flex, scale, priority
stopstring | array of string | null
Not supported with latest reasoning models o3 and o4-mini.

Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
storeboolean | null
Whether or not to store the output of this chat completion request for use in our model distillation or evals products.

Supports text and image inputs. Note: image inputs over 8MB will be dropped.
streamboolean | null
If set to true, the model response data will be streamed to the client as it is generated using server-sent events. See the Streaming section below for more information, along with the streaming responses guide for more information on how to handle the streaming events.
stream_optionsobject | null
Options for streaming response. Only set this when you set stream: true.
2 properties
- include_obfuscationboolean | null
  When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an obfuscation field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream. You can set include_obfuscation to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API.
- include_usageboolean | null
  If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array.
  
  All other chunks will also include a usage field, but with a null value. NOTE: If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request.
temperaturenumber (float) | null
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

We generally recommend altering this or top_p but not both.
tool_choiceobject | null
Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool. none is the default when no tools are present. auto is the default if tools are present.
4 options
One of
type: allowed_toolsobject
allowed_toolsarray of objectRequired
2 properties
modestringRequired
Constrains the tools available to the model to a pre-defined set.

auto allows the model to pick from among the allowed tools and generate a message.

required requires the model to call one or more of the allowed tools.
Allowed values: auto, required
toolsarray of anyRequired
A list of tool definitions that the model should be allowed to call.

For the Chat Completions API, the list of tool definitions might look like:

[ { "type": "function", "function": { "name": "get_weather" } }, { "type": "function", "function": { "name": "get_time" } } ]
typestringRequired
Value: allowed_tools
type: functionobject
Specifies a tool the model should use. Use to force the model to call a specific function.
functionobjectRequired
1 property
namestringRequired
The name of the function to call.
typestringRequired
Value: function
type: customobject
customobjectRequired
1 property
namestringRequired
The name of the custom tool to call.
typestringRequired
Value: custom
type: modeobject
Allowed values: none, auto, required
typestringRequired
Value: mode
toolsarray of object | null
A list of tools the model may call. You can provide either custom tools or function tools.
2 options
One of
type: functionobject
A function tool that can be used to generate a response.
functionobjectRequired
4 properties
descriptionstring | null
A description of what the function does, used by the model to choose when and how to call the function.
namestringRequired
The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
parametersany
The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.

Omitting parameters defines a function with an empty parameter list.
strictboolean | null
Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the parameters field. Only a subset of JSON Schema is supported when strict is true. Learn more about Structured Outputs in the function calling guide.
typestringRequired
Value: function
type: customobject
A custom tool that processes input using a specified format.
customobjectRequired
3 properties
descriptionstring | null
Optional description of the custom tool, used to provide more context.
formatobjectRequired
The input format for the custom tool. Default is unconstrained text.
2 options
One of
type: textobject
Unconstrained free-form text.
typestringRequired
Value: text
type: grammarobject
A grammar defined by the user.
grammarobjectRequired
2 properties
definitionstringRequired
The grammar definition.
syntaxstringRequired
The syntax of the grammar definition. One of lark or regex.
Allowed values: lark, regex
typestringRequired
Value: grammar
namestringRequired
The name of the custom tool, used to identify it in tool calls.
typestringRequired
Value: custom
top_logprobsinteger (int32) | null
An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.
- Minimum: 0
top_pnumber (float) | null
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.
userstring | nullDeprecated
This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. Learn more.
verbositystring | null
Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are low, medium, and high.
- Allowed values: low, medium, high
web_search_optionsobject | null
This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
2 properties
- search_context_sizestring | null
  High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
  - Allowed values: low, medium, high
- user_locationobject | null
  Approximate location parameters for the search.
  2 properties
  - approximateobjectRequired
    Approximate location parameters for the search.
    4 properties
    citystring | null
    Free text input for the city of the user, e.g. San Francisco.
    countrystring | null
    The two-letter ISO country code of the user, e.g. US.
    regionstring | null
    Free text input for the region of the user, e.g. California.
    timezonestring | null
    The IANA timezone of the user, e.g. America/Los_Angeles.
  - typestringRequired
    Value: approximate

Example request

curl -X POST "https://data.spiceai.io/v1/chat/completions" \
  -H "X-API-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "developer",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "stream": false
  }'

Responses

200OK
Chat completion generated successfully
application/json
Represents a chat completion response returned by model, based on the provided input.
- choicesarray of objectRequired
  A list of chat completion choices. Can be more than one if n is greater than 1.
  4 properties
  finish_reasonstring | null
  The reason the model stopped generating tokens. This will be stop if the model hit a natural stop point or a provided stop sequence, length if the maximum number of tokens specified in the request was reached, content_filter if content was omitted due to a flag from our content filters, tool_calls if the model called a tool, or function_call (deprecated) if the model called a function.
  Allowed values: stop, length, tool_calls, content_filter, function_call
  indexinteger (int32)Required
  The index of the choice in the list of choices.
  Minimum: 0
  logprobsobject | null
  Log probability information for the choice.
  2 properties
  contentarray of object | null
  A list of message content tokens with log probability information.
  4 properties
  bytesarray of integer (int32) | null
  A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.
  logprobnumber (float)Required
  The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.
  tokenstringRequired
  The token.
  top_logprobsarray of objectRequired
  List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.
  3 properties
  bytesarray of integer (int32) | null
  A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.
  logprobnumber (float)Required
  The log probability of this token.
  tokenstringRequired
  The token.
  refusalarray of object | null
  4 properties
  bytesarray of integer (int32) | null
  A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.
  logprobnumber (float)Required
  The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.
  tokenstringRequired
  The token.
  top_logprobsarray of objectRequired
  List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.
  3 properties
  bytesarray of integer (int32) | null
  A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.
  logprobnumber (float)Required
  The log probability of this token.
  tokenstringRequired
  The token.
  messageobjectRequired
  A chat completion message generated by the model.
  8 properties
  annotationsarray of object | null
  2 properties
  typestringRequired
  Value: url_citation
  url_citationobjectRequired
  4 properties
  end_indexinteger (int32)Required
  The index of the last character of the URL citation in the message.
  Minimum: 0
  start_indexinteger (int32)Required
  The index of the first character of the URL citation in the message.
  Minimum: 0
  titlestringRequired
  The title of the web resource.
  urlstringRequired
  The URL of the web resource.
  audioobject | null
  If the audio output modality is requested, this object contains data about the audio response from the model. Learn more.
  4 properties
  datastringRequired
  Base64 encoded audio bytes generated by the model, in the format specified in the request.
  expires_atinteger (int64)Required
  The Unix timestamp (in seconds) for when this audio response will no longer be accessible on the server for use in multi-turn conversations.
  Minimum: 0
  idstringRequired
  Unique identifier for this audio response.
  transcriptstringRequired
  Transcript of the audio generated by the model.
  contentstring | null
  The contents of the message.
  function_callobject | null
  Deprecated and replaced by tool_calls. The name and arguments of a function that should be called, as generated by the model.
  2 properties
  argumentsstringRequired
  The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
  namestringRequired
  The name of the function to call.
  reasoning_contentstring | null
  Reasoning / chain-of-thought content (e.g. extracted from a <think> block), kept separate from the user-facing content. Populated by reasoning models such as GLM, DeepSeek-R1, and QwQ.
  refusalstring | null
  The refusal message generated by the model.
  rolestringRequired
  The role of the author of this message.
  Allowed values: user, assistant, system, developer
  tool_callsarray of object | null
  The tool calls generated by the model, such as function calls.
  2 options
  One of
  type: functionobject
  functionobjectRequired
  The function that the model called.
  2 properties
  argumentsstringRequired
  The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
  namestringRequired
  The name of the function to call.
  idstringRequired
  The ID of the tool call.
  typestringRequired
  Value: function
  type: customobject
  custom_toolobjectRequired
  The custom tool that the model called.
  2 properties
  inputstringRequired
  The input for the custom tool call generated by the model.
  namestringRequired
  The name of the custom tool to call.
  idstringRequired
  The ID of the tool call.
  typestringRequired
  Value: custom
- createdinteger (int32)Required
  The Unix timestamp (in seconds) of when the chat completion was created.
  - Minimum: 0
- idstringRequired
  A unique identifier for the chat completion.
- modelstringRequired
  The model used for the chat completion.
- objectstringRequired
  The object type, which is always chat.completion.
- service_tierstring | null
  The service tier used for processing the request. This field is only included if the service_tier parameter is specified in the request.
  - Allowed values: auto, default, flex, scale, priority
- system_fingerprintstring | nullDeprecated
  This fingerprint represents the backend configuration that the model runs with.
  
  Can be used in conjunction with the seed request parameter to understand when backend changes have been made that might impact determinism.
- usageobject | null
  Usage statistics for the completion request.
  5 properties
  completion_tokensinteger (int32)Required
  Number of tokens in the generated completion.
  Minimum: 0
  completion_tokens_detailsobject | null
  Breakdown of tokens used in a completion.
  4 properties
  accepted_prediction_tokensinteger (int32) | null
  Minimum: 0
  audio_tokensinteger (int32) | null
  Audio input tokens generated by the model.
  Minimum: 0
  reasoning_tokensinteger (int32) | null
  Tokens generated by the model for reasoning.
  Minimum: 0
  rejected_prediction_tokensinteger (int32) | null
  When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits.
  Minimum: 0
  prompt_tokensinteger (int32)Required
  Number of tokens in the prompt.
  Minimum: 0
  prompt_tokens_detailsobject | null
  Breakdown of tokens used in the prompt.
  2 properties
  audio_tokensinteger (int32) | null
  Audio input tokens present in the prompt.
  Minimum: 0
  cached_tokensinteger (int32) | null
  Cached tokens present in the prompt.
  Minimum: 0
  total_tokensinteger (int32)Required
  Total number of tokens used in the request (prompt + completion).
  Minimum: 0
Example
```
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o-mini",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\n\nHello there, how may I assist you today?"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}
```
404Not Found
The specified model was not found
500Internal Server Error
An internal server error occurred while processing the chat completion
application/json
any
Example
```
{
  "error": "An internal server error occurred while processing the chat completion."
}
```

OpenAPIspiceai/spiceai v2.3.2

Text-to-SQL (NSQL)

POST/v1/nsql

Generate and optionally execute a natural-language text-to-SQL (NSQL) query.

This endpoint generates a SQL query using a natural language query (NSQL) and optionally executes it. The SQL query is generated by the specified model and executed if the Accept header is not set to application/sql. When stream is true, the response is streamed as Server-Sent Events (SSE).

Header parameters

Name	Type	Required	Description
`X-API-Key`	string	Yes	Your project API key. See API keys.
`Accept`	string	Yes	The format of the response, one of 'application/json' (default), 'application/vnd.spiceai.nsql.v1+json', 'application/sql', 'text/csv' or 'text/plain'. 'application/sql' will only return the SQL query generated by the model.

Request body

Required

Request body to generate an NSQL query

application/json

datasetsarray of string | null
Names of datasets to sample from when constructing model context; this is a sampling hint and does not restrict which tables queries can target. If omitted, all datasets are used.
modelstring | null
The name of the model to use for SQL generation. If omitted, Spice defaults to the only compatible LLM model configured in the Spicepod.
prompt_cache_keystring | null
Stable prompt-cache key forwarded to the configured NSQL model for provider-specific cache handling.
querystringRequired
The natural language query to be converted into SQL
sample_data_enabledboolean
Whether sample data is included in the context for SQL generation. Default: false
streamboolean
If true, streams the response instead of waiting for completion

Example request

curl -X POST "https://data.spiceai.io/v1/nsql" \
  -H "X-API-Key: <project-api-key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Get the top 5 customers by total sales",
    "stream": false,
    "sample_data_enabled": false,
    "datasets": [
      "sales_data"
    ],
    "prompt_cache_key": "sales-dashboard"
  }'

Responses

200OK

SQL query executed successfully

application/json

array of any

Example

[
  {
    "customer_id": "12345",
    "total_sales": 150000
  },
  {
    "customer_id": "67890",
    "total_sales": 125000
  }
]

application/sql

string

Example

            SELECT customer_id, SUM(total_sales)
            FROM sales_data
            GROUP BY customer_id
            ORDER BY SUM(total_sales) DESC
            LIMIT 5

application/vnd.spiceai.nsql.v1+json

any

Example

{
  "row_count": 2,
  "schema": {
    "fields": [
      {
        "name": "customer_id",
        "data_type": "String",
        "nullable": false,
        "dict_id": 0,
        "dict_is_ordered": false
      },
      {
        "name": "total_sales",
        "data_type": "Int64",
        "nullable": false,
        "dict_id": 0,
        "dict_is_ordered": false
      }
    ]
  },
  "data": [
    {
      "customer_id": "12345",
      "total_sales": 150000
    },
    {
      "customer_id": "67890",
      "total_sales": 125000
    }
  ],
  "sql": "SELECT customer_id, SUM(total_sales) AS total_sales\nFROM sales_data\nGROUP BY customer_id\nORDER BY total_sales DESC\nLIMIT 5"
}

text/event-stream

string

Example

data: {"row_count": 2, "schema": {...}, "data": [...], "sql": "SELECT ..."}

400Bad Request
Invalid request parameters
application/json
string
Example
```
"Model nsql not found"
```
500Internal Server Error
Internal server error
text/plain
string
Example
```
No query produced from NSQL model
```

OpenAPIspiceai/spiceai v2.3.2

List Models

GET/v1/models

List all models, both machine learning and language models, available in the runtime. When status=true and a model is in Error, the response also includes:

error: structured code object with category, type, and stable code
error_message: user-visible details

Query parameters

Name	Type	Required	Description
`format`	string	No	The format of the response (e.g., `json` or `csv`). Allowed values: `json`, `csv`
`status`	boolean	No	If true, includes the status of each model in the response.
`metadata_fields`	string	No	A comma-separated list of metadata fields to include in the response (e.g., `supports_responses_api`)

Header parameters

Name	Type	Required	Description
`X-API-Key`	string	Yes	Your project API key. See API keys.

Example request

curl "https://data.spiceai.io/v1/models" \
  -H "X-API-Key: <project-api-key>"

Responses

200OK
List of models in JSON format
application/json
Response wrapper for the /v1/models endpoint (OpenAI-compatible format).
- dataarray of objectRequired
  The list of models
  8 properties
  datasetsarray of string | null
  The datasets associated with this model, if any
  errorobject | null
  An optional error type/code for the model status. Only populated when status=true and the model status is Error. Example: { "category": "model", "type": "auth", "code": "model.auth" }.
  3 properties
  categorystringRequired
  High-level component category where the error originated.
  Allowed values: dataset, model, worker, runtime
  codestringRequired
  Stable machine-readable code ({category}.{type}), e.g. dataset.auth.
  typestringRequired
  Canonical error type intended for programmatic handling.
  Allowed values: auth, connection, timeout, validation, not_found, permission, rate_limit, internal, unknown
  error_messagestring | null
  An optional error message describing why the model entered an error state. Only populated when status=true, the model status is Error, and an error message was recorded. This value is intended for user-visible display.
  idstringRequired
  The name/identifier of the model
  metadataobject | null
  Optional metadata fields, included when requested via query parameters
  1 property
  supports_responses_apibooleanRequired
  Whether this model supports the Responses API
  objectstringRequired
  The type of the object (always model)
  owned_bystringRequired
  The source from which the model was loaded (e.g., openai, spiceai)
  status"Initializing" | "Ready" | "Disabled" | object | "Refreshing" | "ShuttingDown" | "NotLoaded" | null
  The status of the model (e.g., Ready, Initializing, Error)
  Example: Ready
  7 options
  One of
  "Initializing"string
  The component is initializing and not yet ready
  Value: Initializing
  "Ready"string
  The component is ready to accept connections
  Value: Ready
  "Disabled"string
  The component is disabled and not running
  Value: Disabled
  object with Errorobject
  An error occurred in the component, with an optional error message
  Errorstring | nullRequired
  An error occurred in the component, with an optional error message
  "Refreshing"string
  The component is in the process of refreshing its state
  Value: Refreshing
  "ShuttingDown"string
  The component is in the process of shutting down
  Value: ShuttingDown
  "NotLoaded"string
  The component is configured but not loaded yet
  Value: NotLoaded
- objectstringRequired
  The type of the response (always list)
Example
```
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "owned_by": "openai",
      "datasets": null,
      "status": "ready",
      "error": null,
      "error_message": null
    },
    {
      "id": "text-embedding-ada-002",
      "object": "model",
      "owned_by": "openai-internal",
      "datasets": [
        "text-dataset-1",
        "text-dataset-2"
      ],
      "status": "error",
      "error": {
        "category": "model",
        "type": "auth",
        "code": "model.auth"
      },
      "error_message": "Invalid API key"
    }
  ]
}
```
text/csv
string
Example
```
id,object,owned_by,datasets,status,error,error_message
gpt-4,model,openai,,ready,,
text-embedding-ada-002,model,openai-internal,"text-dataset-1,text-dataset-2",error,model.auth,Invalid API key
```
500Internal Server Error
Internal server error occurred while processing models
application/json
any
Example
```
{
  "error": "App not initialized"
}
```

OpenAPIspiceai/spiceai v2.3.2