Chat API v3: From a Simple Query to Streaming and Vision

Basic Information

🔐 Authentication

API Key

The endpoint requires an API key with permission (scope) ayeto.chat.

Authentication Header

uni-api-key: <YOUR_API_KEY>

API Key Format

The API key has the following format:

ayeto-{64_random_hex_characters}

Example:

ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Scopes

To use the chat endpoint, the API key must have one of the following scopes: - ayeto.chat - specific scope for chat - * - wildcard scope (access to all endpoints)

Authentication Error Responses

🔒 Security: When an invalid API key is used, a security delay is applied to protect against brute-force attacks.

📥 Request Body - ChatRequest

⚠️ Important: Either assistant_id OR model must be provided. One of these fields is required.

📎 Attachments - EncodedData

To attach documents or images, use the documents field:

⚠️ Limitation: Only one image with vision: true is allowed in a single request.

📤 Response - BasicLLMMessageView

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1735815581000,
  "role": "assistant",
  "content": "Hello! I’m doing well, thank you for asking. How can I help?",
  "reasoning_content": null,
  "model": "gpt-4o",
  "img_gen": null
}

🖼️ Image Generation Response - ImgGenMessage

If image: true, the response contains an img_gen object:

📡 Streaming Response (SSE)

If stream: true, the endpoint returns a Server-Sent Events (SSE) stream.

Streaming Response Headers

Content-Type: text/event-stream
Transfer-Encoding: chunked

Stream Chunk Format - StreamChunk

Each chunk is a JSON object on a separate line:

Stream Error Format - StreamError

If an error occurs during streaming:

Example streaming response

{"timestamp": 1735815581000, "data": "Hello", "error": null}
{"timestamp": 1735815581050, "data": ",", "error": null}
{"timestamp": 1735815582100, "data": " how", "error": null}
{"timestamp": 1735815582150, "data": " are", "error": null}
{"timestamp": 1735815582200, "data": " you", "error": null}
{"timestamp": 1735815583000, "data": "?", "error": null}

Example streaming error

{"timestamp": 1735815590000, "data": null, "error": {"status": 500, "text": "Internal Server Error", "detail": "Model timeout"}}

🔧 cURL Examples

1. Basic chat with a model

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Hello, how are you?"
  }'

2. Chat with an existing conversation

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "gpt-4o",
    "message": "Continue the previous topic."
  }'

3. Chat with an assistant

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "123e4567-e89b-12d3-a456-426614174000",
    "message": "Help me with data analysis."
  }'

4. Chat with an attachment (document)

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Analyze this document.",
    "documents": [
      {
        "filename": "report.txt",
        "data": "data:text/plain;base64,VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
        "size": 25,
        "mime_type": "text/plain",
        "vision": false
      }
    ]
  }'

5. Chat with an image (Vision)

# First encode the image to base64
IMAGE_BASE64=$(base64 -w 0 photo.jpg)  # Linux
# or: IMAGE_BASE64=$(base64 -i photo.jpg)  # macOS

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-4o\",
    \"message\": \"What do you see in this image?\",
    \"documents\": [
      {
        \"filename\": \"photo.jpg\",
        \"data\": \"data:image/jpeg;base64,${IMAGE_BASE64}\",
        \"size\": $(stat -f%z photo.jpg 2>/dev/null || stat -c%s photo.jpg),
        \"mime_type\": \"image/jpeg\",
        \"vision\": true
      }
    ]
  }"

6. Image generation

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "message": "Draw a sunset over mountains in the style of Impressionism.",
    "image": true
  }'

7. Streaming response

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "gpt-4o",
    "message": "Write a short story about a robot.",
    "stream": true
  }'

💡 Tip: The -N (or --no-buffer) flag disables buffering for real-time stream display.

8. Streaming with chunk processing (Bash + jq)

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -N -s \
  -d '{
    "model": "gpt-4o",
    "message": "Explain quantum physics.",
    "stream": true
  }' | while IFS= read -r line; do
    echo "$line" | jq -r '.data // empty' | tr -d '\n'
  done
echo ""

9. Chat in organization context

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "gpt-4o",
    "message": "What are our company goals?"
  }'

10. Chat with token limit

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Summarize the history of computers.",
    "max_tokens": 500
  }'

11. Chat with dynamic tools and relevant history

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "123e4567-e89b-12d3-a456-426614174000",
    "message": "Find weather information in Prague.",
    "relevant_history": true,
    "dynamic_tools": true
  }'

12. Chat with tool calls removed from the response

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "123e4567-e89b-12d3-a456-426614174000",
    "message": "Calculate 2+2 using a calculator.",
    "remove_tool_calls": true
  }'

13. Complete example with multiple parameters

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "assistant_id": "abcd1234-e89b-12d3-a456-426614174000",
    "message": "Analyze the attached document and create a summary.",
    "max_tokens": 1000,
    "relevant_history": true,
    "dynamic_tools": true,
    "stream": false,
    "remove_tool_calls": true,
    "documents": [
      {
        "filename": "report.pdf",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "size": 102400,
        "mime_type": "application/pdf",
        "vision": false
      }
    ]
  }'

14. Verbose curl for debugging

curl -v -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Test message"
  }'

⚠️ Error States

Example error response

{
  "detail": "API key is invalid"
}

🔄 Validation Rules

1. Model vs Assistant: assistant_id OR model must be provided (not both empty).
2. Vision limit: Maximum of one document with vision: true per request.
3. Max tokens: If provided, it must be within the model’s limits.
4. Conversation: If a conversation with the given ID exists, it must belong to the current user.
5. API Key scope: The API key must have scope ayeto.chat or *.