Documents

Generate API Documentation for Chat Completions on Alchemyst AI

Chat Completion API for Alchemyst AI

Overview

This document describes which API endpoint should be used for chat completions on the Alchemyst AI platform, with technical usage details based exclusively on the provided OpenAPI documentation.

Recommended API Endpoints

Several endpoints in the Alchemyst AI API can be used for chat completions, with differences in compatibility and feature set:

1. OpenAI Compatible Chat Completions (Proxy Endpoint)

Endpoint:

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

Description:

This endpoint provides an OpenAI compatible interface for chat completions. It acts as a proxy and supports parameters and structure similar to OpenAI's API.

Authentication:

  • Bearer token (`Authorization: Bearer `)

Required Parameters (JSON Body):

  • `model` (string): The model to use for completion
  • `messages` (array): List of messages in format:
    • `role`: "system" | "user" | "assistant"
    • `content`: message string

Example JSON Request:

```json { "model": "gpt-3.5-turbo", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ] } ```

Success Response (200):

  • Standard OpenAI-compatible response with `id`, `object`, `created`, `choices`, etc.

Use Case:

  • Use this endpoint if you want to quickly migrate OpenAI-based chat applications to Alchemyst AI or require strict OpenAI API format compatibility.

2. Native Chat Completion Endpoints

a. General Chat Generation

  • `POST /api/v1/chat/generate`
  • Provides more flexibility (e.g., persona selection, additional context, tool integration).

Required Parameters (JSON Body):

  • `chat_history` (array): Required.
  • Optional: `chatId`, `persona`, `tools`, `scope`, `stream`, `voice`, `fastContext`.

Response:

  • 201 Created: Object with `result`, `chatId`, `title`, etc.

b. Streaming Chat Completion

  • `POST /api/v1/chat/generate/stream`
  • Used for real-time/streamed AI-generated responses (e.g., live chat experience).

Required Parameters (JSON Body):

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

Response:

  • 200 OK: Event stream with updates (`thinking_update`, `final_response`, `metadata`).

Endpoint Comparison Table

Endpoint Compatibility Supports Streaming Persona/Advanced Features
/api/v1/proxy/{proxyUrl}/{OpenAIAPIKey}/chat/completions OpenAI Compatible No Limited/None
/api/v1/chat/generate Alchemyst Native No Yes
/api/v1/chat/generate/stream Alchemyst Native Yes Yes

Summary & Recommendation

  • For OpenAI compatibility: Use `POST /api/v1/proxy/{proxyUrl}/{OpenAIAPIKey}/chat/completions` for a drop-in replacement of existing OpenAI chat completion workflows.
  • For advanced and persona/context-aware features: Use `POST /api/v1/chat/generate` (for basic completion) or `POST /api/v1/chat/generate/stream` (for streaming responses).

Example Usage: OpenAI-Style Request

```http POST /api/v1/proxy/{proxyUrl}/{OpenAIAPIKey}/chat/completions Authorization: Bearer Content-Type: application/json

{ "model": "gpt-3.5-turbo", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What can you do?"} ] } ```

References

Please ensure your authorization token and required parameters are provided for successful requests. For more nuanced use cases (like persona or integrated tools), consult endpoints `/api/v1/chat/generate` and `/api/v1/chat/generate/stream`.