Chat API v3: Od jednoduchého dotazu po streaming a vision

Základní informace

🔐 Autentizace

API Key

Endpoint vyžaduje API klíč s oprávněním (scope) ayeto.chat.

Hlavička pro autentizaci

uni-api-key: <YOUR_API_KEY>

Formát API klíče

API klíč má následující formát:

ayeto-{64_random_hex_characters}

Příklad:

ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Scopes

Pro použití chat endpointu musí mít API klíč scope: - ayeto.chat - specifický scope pro chat - * - wildcard scope (přístup ke všem endpointům)

Chybové odpovědi autentizace

🔒 Bezpečnost: Při neplatném API klíči je aplikována bezpečnostní prodleva pro ochranu proti brute-force útokům.

📥 Request Body - ChatRequest

⚠️ Důležité: Musí být zadáno buď assistant_id NEBO model. Jedno z těchto polí je povinné.

📎 Přílohy - EncodedData

Pro přiložení dokumentů nebo obrázků použijte pole documents:

⚠️ Omezení: V jednom requestu může být pouze jeden obrázek s vision: true.

📤 Response - BasicLLMMessageView

Příklad response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1735815581000,
  "role": "assistant",
  "content": "Ahoj! Jsem v pořádku, děkuji za optání. Jak mohu pomoci?",
  "reasoning_content": null,
  "model": "gpt-4o",
  "img_gen": null
}

🖼️ Image Generation Response - ImgGenMessage

Pokud je image: true, odpověď obsahuje objekt img_gen:

📡 Streaming Response (SSE)

Pokud je stream: true, endpoint vrací Server-Sent Events (SSE) stream.

Hlavičky streaming odpovědi

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

Formát Stream Chunk - StreamChunk

Každý chunk je JSON objekt na samostatném řádku:

Formát Stream Error - StreamError

Pokud během streamování dojde k chybě:

Příklad streaming odpovědi

{"timestamp": 1735815581000, "data": "Ahoj", "error": null}
{"timestamp": 1735815581050, "data": ",", "error": null}
{"timestamp": 1735815582100, "data": " jak", "error": null}
{"timestamp": 1735815582150, "data": " se", "error": null}
{"timestamp": 1735815582200, "data": " máš", "error": null}
{"timestamp": 1735815583000, "data": "?", "error": null}

Příklad streaming chyby

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

🔧 cURL Příklady

1. Základní chat s modelem

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": "Ahoj, jak se máš?"
  }'

2. Chat s existující konverzací

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": "Pokračuj v předchozím tématu."
  }'

3. Chat s asistentem

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": "Pomoz mi s analýzou dat."
  }'

4. Chat s přílohou (dokument)

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": "Analyzuj tento dokument.",
    "documents": [
      {
        "filename": "report.txt",
        "data": "data:text/plain;base64,VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
        "size": 25,
        "mime_type": "text/plain",
        "vision": false
      }
    ]
  }'

5. Chat s obrázkem (Vision)

# Nejprve zakódujte obrázek do base64
IMAGE_BASE64=$(base64 -w 0 photo.jpg)  # Linux
# nebo: 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\": \"Co vidíš na tomto obrázku?\",
    \"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. Generování obrázku

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": "Nakresli západ slunce nad horami ve stylu impresionismu.",
    "image": true
  }'

7. Streaming odpověď

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": "Napiš krátký příběh o robotovi.",
    "stream": true
  }'

💡 Tip: Flag -N (nebo --no-buffer) vypne bufferování pro real-time zobrazení streamu.

8. Streaming s zpracováním chunků (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": "Vysvětli kvantovou fyziku.",
    "stream": true
  }' | while IFS= read -r line; do
    echo "$line" | jq -r '.data // empty' | tr -d '\n'
  done
echo ""

9. Chat v kontextu organizace

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": "Jaké jsou naše firemní cíle?"
  }'

10. Chat s omezením tokenů

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": "Shrň historii počítačů.",
    "max_tokens": 500
  }'

11. Chat s dynamickými nástroji a relevantní historií

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": "Vyhledej informace o počasí v Praze.",
    "relevant_history": true,
    "dynamic_tools": true
  }'

12. Chat s odstraněním tool calls z odpovědi

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": "Spočítej 2+2 pomocí kalkulačky.",
    "remove_tool_calls": true
  }'

13. Kompletní příklad s více parametry

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": "Analyzuj přiložený dokument a vytvoř shrnutí.",
    "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 pro 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 zpráva"
  }'

⚠️ Chybové stavy

Příklad chybové odpovědi

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

🔄 Validační pravidla

1. Model vs Assistant: Musí být zadáno assistant_id NEBO model (ne obojí prázdné).
2. Vision limit: Maximálně jeden dokument s vision: true na request.
3. Max tokens: Pokud je zadáno, musí být v rámci limitů modelu.
4. Konverzace: Pokud existuje konverzace s daným ID, musí patřit aktuálnímu uživateli.
5. API Key scope: API klíč musí mít scope ayeto.chat nebo *.