Skip to main content
Version: v1.6.41-dev3 🚧

h2oGPTe REST API: OpenAPI specification file

Overview​

The h2oGPTe OpenAPI specification file outlines the structure and functionality of the h2oGPTe REST API, detailing available endpoints, request and response formats, and authentication requirements.

Using the OpenAPI specification file for the h2oGPTe REST API, we have generated SDKs in multiple programming languages to help you quickly integrate with the API. Below are the available SDKs:

  • Python SDK - Download Python SDK
  • JavaScript SDK - Download JavaScript SDK
  • Go SDK - Download Go SDK

How we generated the SDKs​

The available SDKs were developed using the OpenAPI Generator CLI, a robust tool designed to create client libraries directly from OpenAPI specifications.

Installation​

pip install openapi-generator-cli==7.10.0

SDK Setup Guide​

Python
You are currently viewing: Python SDK
All code examples and instructions below are for Python

General CLI structure​

openapi-generator-cli generate \
  -i rest_api_spec_h2ogpte.yaml \
  -g python \
  -o sdk \
  --additional-properties=packageName=h2ogpte_rest_client,packageVersion=1.6.2,projectName=h2ogpte-rest-client

Prerequisites​

  1. Create a folder for your Python SDK. Paste the following commands in your terminal:

    mkdir python-sdk
    cd python-sdk

  2. Download the OpenAPI specification file: Download api-spec.yaml and move it to the python-sdk folder.

  3. Set up a Python environment with Python 3.8 or later:

    python3 -m venv venv
    source venv/bin/activate
    pip install openapi-generator-cli==7.10.0

Generate SDK​

In the python-sdk directory, run the following command (CLI) to create the Python SDK using the OpenAPI Generator CLI:

openapi-generator-cli generate \
  -i rest_api_spec_h2ogpte.yaml \
  -g python \
  -o sdk \
  --additional-properties=packageName=h2ogpte_rest_client,packageVersion=1.6.2,projectName=h2ogpte-rest-client
note

The CLI creates a folder named sdk containing the Python SDK.

Install Dependencies​

  1. Navigate to the SDK directory and install dependencies:

    cd sdk
    pip install -r requirements.txt

  2. Install the Python SDK:

    pip install setuptools
    python setup.py install

Test SDK with Collection Creation​

Create a test Collection to verify the Python SDK installation:

create_a_collection.py
# This example with the Python SDK creates a new Collection with the following 
# name and description (while testing whether the Python SDK was properly installed): 
# Name = The name of my Collection
# Description = The description of my Collection
import h2ogpte_rest_client
import os
from h2ogpte_rest_client.rest import ApiException
from pprint import pprint

configuration = h2ogpte_rest_client.Configuration(
    # This line specifies the URL where Enterprise h2oGPTe is hosted. 
    # The address should be the location where the API key was created.
    host="https://h2ogpte.genai.h2o.ai/",
    # This line specifies the API key for authentication.
    access_token=os.environ["BEARER_TOKEN"]
)

with h2ogpte_rest_client.ApiClient(configuration) as api_client:
    api_instance = h2ogpte_rest_client.CollectionsApi(api_client)
    
    collection_create_request = h2ogpte_rest_client.CollectionCreateRequest(
        name="The name of my Collection",
        description="The description of my Collection"
    ) 

    try:
        api_response = api_instance.create_collection(collection_create_request)
        print("The response of CollectionsApi->create_collection:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling CollectionsApi->create_collection: %s\n" % e)

Set up authentication:

Before you can run the Python script, you need to export a global API key within the sdk directory:

export BEARER_TOKEN="sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Run the test:

Within the sdk directory, run the following command:

python3 create_a_collection.py

Expected output:

The response of CollectionsApi->create_collection:

Collection(id='091c6ab1-a031-4eb7-9e3e-7d0939911d00', name='The name of my Collection', description='The description of my Collection', embedding_model='BAAI/bge-large-en-v1.5', document_count=0, document_size=0, updated_at=datetime.datetime(2024, 12, 3, 21, 39, 49, 442087, tzinfo=TzInfo(UTC)), user_count=0, is_public=False, username='sergio.perez@h2o.ai', sessions_count=0)

CLI Parameters​

  • -i: The path or URL to the OpenAPI spec (for example, openapi.yaml or https://example.com/openapi.yaml).
  • -g: The target programming language for the client (for example, python, javascript, go).
  • -o: The output directory for the generated files (for example, ./python-client).
  • --additional-properties: Additional settings for client generation (for example, usePromises=true for JavaScript).

For more information about generating SDKs in other languages, visit the OpenAPI Generator CLI documentation.

Authentication​

Global API Key
  • The value exported for the BEARER_TOKEN (Python), accessToken (JavaScript), or Authorization header (Go) should be a global API key.
  • To learn more about what is a global API key and how to create one, see APIs.
  • All URIs are relative to https://h2ogpte.genai.h2o.ai/. The global API key must be created on this platform to ensure successful requests.
  • Make sure to replace sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual API key.

OpenAI-compatible REST API​

This API provides OpenAI-style endpoints for chat completions, chat responses, and model listing for integration with OpenAI-based applications.

Endpoints​

POST /openai_api/v1/chat/completions : OpenAI-compatible chat completions endpoint.

POST /openai_api/v1/responses : OpenAI-compatible responses endpoint for new chat interactions.

GET /openai_api/v1/models : Lists available models for use with chat and completions endpoints.

Authentication​

Use the same API key authentication as the main REST API:

Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
note

Make sure to replace sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual API key.

Chat completions​

Endpoint: POST /openai_api/v1/chat/completions

Restrictions
  • Supported message types: Only developer, system, user, and assistant messages are supported.
  • Accepted content parts: Only text and image content parts are accepted as input for user messages (see OpenAI API reference for full OpenAI API capabilities).

Request:

{
  "model": "auto",
  "messages": [
    { "role": "user", "content": "What color is the sky?" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}

Response:

{
  "choices": [
    {
      "message": { "role": "assistant", "content": "The sky is typically blue during the day." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

Responses​

Endpoint: POST /openai_api/v1/responses

Restrictions
  • Accepted input: Only text input is accepted (see OpenAI API reference for full OpenAI API capabilities).

Request:

{
  "model": "auto",
  "input": "What color is the sky?",
  "instructions": "You are a helpful assistant.",
  "temperature": 0.7,
  "stream": false
}

Alternative Request with Chat History:

{
  "model": "auto",
  "input": [
    { "role": "user", "content": "What color is the sky?" },
    { "role": "assistant", "content": "The sky is blue." },
    { "role": "user", "content": "What was the answer, again?" }
  ],
  "stream": true
}

Response:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1677610602,
  "model": "auto",
  "status": "completed",
  "output": [
    {
      "id": "msg_123",
      "role": "assistant",
      "status": "completed",
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "The sky is typically blue during the day.",
          "annotations": []
        }
      ]
    }
  ],
  "error": null
}

List models​

Endpoint: GET /openai_api/v1/models

note

See OpenAI API reference for full OpenAI API capabilities.

Request:

GET /openai_api/v1/models
Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "created": 1677610602,
      "owned_by": "h2oai",
      "permission": [
        {
          "id": "modelperm-abc123",
          "object": "model_permission",
          "created": 1677610602,
          "allow_create_engine": false,
          "allow_sampling": true,
          "allow_logprobs": false,
          "allow_search_indices": false,
          "allow_view": true,
          "allow_fine_tuning": false,
          "organization": "*",
          "group": null,
          "is_blocking": false
        }
      ],
      "root": "gpt-3.5-turbo",
      "parent": null
    }
    // ... more models may be listed here
  ]
}

Compatibility​

  • OpenAI Python client: Compatible with basic chat completions, responses, and model listing endpoints. You can use the standard OpenAI Python library with these specific endpoints.
  • Cline VSCode extension: Supported with the OpenAI Compatible provider setting.
  • Streaming: Supported via the stream=true parameter (responses are streamed as per OpenAI's API).
Feedback