Documents

API for Chat Completions on Alchemyst AI

Alchemyst AI: Choosing the Right API for Chat Completions

Overview

This document provides detailed technical documentation on selecting and integrating with the correct API endpoint for chat completions on Alchemyst AI. It is tailored for developers and integrators seeking to add chat-based AI interactions, either using a native interface or an OpenAI-compatible API. All information is strictly derived from the provided context.

Available API Endpoints for Chat Completions

1. OpenAI-Compatible Endpoint

Endpoint

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

Description

  • Provides a temporary interface that closely mirrors the OpenAI API specification for chat completions.
  • Allows existing OpenAI-powered clients to forward requests to Alchemyst AI with minimal or no code changes.
  • Requires a `proxyUrl`, your `OpenAIAPIKey`, and a Bearer JWT for authentication.

Request Body

  • Must contain OpenAI-formatted parameters such as `model`, and `messages` array using roles: `system`, `user`, `assistant`.

Example Request Body

``` { "model": "maya-latest", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello, Maya!"} ] } ```

Response

  • Returns a response structure compatible with OpenAI's API ( includes `choices`, `created`, `object`, etc).
  • HTTP 200 on successful completion, HTTP 400 on validation errors.

2. Native Alchemyst AI Chat Completion Endpoints

a) /api/v1/chat/generate (Standard, Synchronous)

  • Method: `POST`
  • Authentication: Bearer JWT required (`Authorization: Bearer `).
  • Payload:
    • `chat_history`: Array of chat messages
    • Optional: `persona` (e.g., `maya`), `tools`, `scope` (`internal` or `external`), `stream`, `voice`, etc.

Example Request Body

``` { "chat_history": [ {"role": "user", "content": "Hi Maya!"}, {"role": "assistant", "content": "Hello! How can I help you today?"} ], "persona": "maya" } ```

Response

  • JSON object with `result`, `chatId`, `title`, and metadata.
  • HTTP 201 on success. Errors: 400 (bad request), 401 (unauthorized), 500 (server error).

b) /api/v1/chat/generate/stream (Streaming Results)

  • Method: `POST`
  • Description: Streams real-time chat completions. Responses are sent as `text/event-stream`, containing thinking steps, state updates, and final result.
  • Payload: Similar to synchronous endpoint.

Example Event Stream Output

``` data: {"type":"thinking_update","content":"Planning response"} data: {"type":"final_response","content":"Here's your answer..."} data: [DONE] ```

c) /api/v1/chat (Alternate Native Endpoint)

  • Method: `POST`
  • Purpose: Responds to chat completions based on provided chat history and persona.
  • Payload:
    • `chat_history` (array): List of messages (`user`, `assistant` roles).
    • `persona`: (string) -- e.g., `maya`.

Example Request Body

``` { "chat_history": [ {"role": "user", "content": "What can you do?"} ], "persona": "maya" } ```

Response

  • Returns `result` (message and persona), plus optional metadata.

Authentication

  • All endpoints require Bearer JWT authentication: `Authorization: Bearer <your_token>`

Summary Table

Endpoint OpenAI Compatible Streaming Notes
/api/v1/proxy/{proxyUrl}/{OpenAIAPIKey}/chat/completions Yes No For OpenAI-format clients
/api/v1/chat/generate No No Native, supports personas
/api/v1/chat/generate/stream No Yes Native, streaming, personas
/api/v1/chat No No Simple native chat completion

Best Practice

  • For OpenAI compatibility or migration: Use `/api/v1/proxy/{proxyUrl}/{OpenAIAPIKey}/chat/completions`.
  • For native Alchemyst features (personas, streaming, metadata): Use `/api/v1/chat/generate` or `/api/v1/chat/generate/stream`.

Example Authentication Header

``` Authorization: Bearer <your_JWT_token> ```

Notes

  • Ensure required fields (e.g., `chat_history`, `model`, `messages`) are present depending on endpoint.
  • The streaming endpoint provides advanced interaction with real-time updates.
  • Persona support (e.g., "maya") is available in native endpoints.

Conclusion

Alchemyst AI supports both OpenAI-compatible and native chat completion APIs. Choose the endpoint that best matches your integration requirements and development environment.