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 an App API key.

The App 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.

Authorizations

X-API-KEYstringRequired

Body

anyOptional

Responses

200

Chat completion generated successfully

application/json

anyOptional

404

The specified model was not found

500

An internal server error occurred while processing the chat completion

application/json

post/v1/chat/completions

POST /v1/chat/completions HTTP/1.1
Host: us-east-1-prod-aws-data.spiceai.io
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "developer",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "stream": false
}

{
  "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
    }
  }
}

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).

Authorizations

X-API-KEYstringRequired

Header parameters

AcceptstringRequired

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.

Body

anyOptional

Responses

200

SQL query executed successfully

itemsanyOptional

400

Invalid request parameters

application/json

500

Internal server error

text/plain

post/v1/nsql

POST /v1/nsql HTTP/1.1
Host: us-east-1-prod-aws-data.spiceai.io
X-API-KEY: YOUR_API_KEY
Accept: text
Content-Type: application/json
Content-Length: 132

{
  "query": "Get the top 5 customers by total sales",
  "model": "nql",
  "stream": false,
  "sample_data_enabled": true,
  "datasets": [
    "sales_data"
  ]
}

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

List Models

get

/v1/models

List all models, both machine learning and language models, available in the runtime.

Authorizations

X-API-KEYstringRequired

Query parameters

formatanyOptional

The format of the response (e.g., json or csv).

statusbooleanOptional

If true, includes the status of each model in the response.

metadata_fieldsstringOptional

A comma-separated list of metadata fields to include in the response (e.g., supports_responses_api)

Responses

200

List of models in JSON format

anyOptional

500

Internal server error occurred while processing models

application/json

get/v1/models

GET /v1/models HTTP/1.1
Host: us-east-1-prod-aws-data.spiceai.io
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "owned_by": "openai",
      "datasets": null,
      "status": "ready"
    },
    {
      "id": "text-embedding-ada-002",
      "object": "model",
      "owned_by": "openai-internal",
      "datasets": [
        "text-dataset-1",
        "text-dataset-2"
      ],
      "status": "ready"
    }
  ]
}