Documents

Chat Completion Endpoints Documentation

Chat Completion Endpoints

This document describes the available chat completion API endpoints in Alchemyst AI API v1.

Table of Contents

OpenAI-Compatible Chat Completion Endpoint

Endpoint

`POST /api/v1/proxy/{proxyUrl}/{OpenAIAPIKey}/chat/completions`

Description: Provides an OpenAI-compatible API interface for chat completions.

Required Parameters (Request Body):

  • `model` (string): The model to use for completion.
  • `messages` (array): List of chat messages (each with `role` and `content`).

Security:

  • Bearer Authentication (JWT)

Response Example: ```json { "id": "string", "object": "string", "created": 1234, "choices": [ ... ] } ```

Google Gemini Proxy Chat Completion Endpoint

Endpoint

`POST /api/v1/proxy/{geminiUrl}/v1beta/models/{modelNameAndTask}`

Description: Proxy endpoint for Google Gemini API, with input validation and error handling.

Required Parameters (Request Body):

  • `contents` (array): List of content objects, each typically including `parts` (with `text`).
  • `generationConfig` (object, optional): Configuration for things like temperature, topK, etc.
  • `safetySettings` (array, optional): List of safety setting objects specifying harm categories and thresholds.

Security:

  • Bearer Authentication (JWT)

Alchemyst Chat Generation Endpoints

Generate a Chat Completion

`POST /api/v1/chat/generate`

Description: Generates a chat response given a chat history and persona.

Query Parameters (all optional):

  • `chatId`: Existing chat to append to.
  • `username`: Username of user (for integrations).
  • `source`: Source platform/integration.
  • `title`: Title for chat history.

Request Body:

  • `chat_history` (array, required): Array of chat message objects.
  • `persona` (string, optional): Persona for generation (e.g., "maya").
  • `tools` (object, optional): Tool options.
  • `scope` (string, optional): Default "internal".
  • `stream` (boolean, optional): Whether to stream response.
  • `voice` (boolean, optional): For voice integration.
  • `fastContext` (array, optional): Contextual data.

Responses:

  • 201: Chat generated successfully (includes `result`, `chatId`, `title`, `researchMode`, `stream`).

Direct Chat (Non-Streaming)

`POST /api/v1/chat`

Description: Processes a chat request and generates a response based on `chat_history` and optional `persona`.

Request Body:

  • `chat_history` (array, required)
  • `persona` (string, optional)

Response Example: ```json { "result": { "message": "...", "persona": "maya" }, "metadata": { "timeTaken": 200 } } ```

Chat History and Management Endpoints

  • `GET /api/v1/chat/history`: Retrieve all user chat histories.
  • `GET /api/v1/chat/fetch/{chatId}`: Fetch a specific chat history by ID.
  • `POST /api/v1/chat/fork`: Fork a chat history up to a specific message.
  • `PUT /api/v1/chat/{chatId}/pin`: Pin or unpin a chat by ID.
  • `PATCH /api/v1/chat/{chatId}`: Update properties (title, pinned status).
  • `DELETE /api/v1/chat/{chatId}`: Delete a chat history by ID.
  • `POST /api/v1/chat/new`: Save a new chat history (provide title and messages).

Streaming Chat Completion Endpoint

Endpoint

`POST /api/v1/chat/generate/stream`

Description: Streams back AI-generated responses, thinking steps, and metadata using Server-Sent Events (SSE).

Required Fields (Request Body):

  • `chat_history` (array): Required array of messages.
  • Optional: `chatId`, `persona`, `scope`, `tools`.

Streaming Format Example: ```text data: {"type":"thinking_update","content":"Planning response"} data: {"type":"final_response","content":"Here"s your answer..."} data: {"type":"metadata","content":{"chatId":"...","title":"..."}} data: [DONE] ```

Related Terms

  • Persona: Specifies which AI persona to use for completion (e.g., "maya").
  • Chat History: Array of role-content messages, e.g.,`[{ "role": "user", "content": "Hi" }, { "role": "assistant", "content": "Hello!" }]`.
  • Streaming Response: Use the streaming endpoint for incremental response updates.
  • Bearer Authentication: Most endpoints require Bearer JWT tokens in Authorization header.
  • Metadata: Some endpoints provide additional metadata in the response.

Example Usage

OpenAI-Compatible Completion

```http POST /api/v1/proxy/your_backend_url/{OpenAIAPIKey}/chat/completions Authorization: Bearer Content-Type: application/json { "model": "gpt-3.5-turbo", "messages": [ { "role": "system", "content": "You are a helpful AI." }, { "role": "user", "content": "Hello!" } ] } ```

Alchemyst Chat Completion

```http POST /api/v1/chat/generate Authorization: Bearer Content-Type: application/json { "chat_history": [ { "role": "user", "content": "What's the weather like?" } ], "persona": "maya" } ```

For all endpoints, ensure to provide the required authentication and data as specified above. For more details on persona options and advanced configurations, refer to the full API documentation.