# Kreatyw - API Documentation

Back to Editor

# Kreatyw API

Text generation API powered by N-gram language models

## Overview

The Kreatyw API provides a simple REST endpoint for generating text continuations using N-gram language models. The API uses Markov chains trained on source texts to predict and generate coherent text sequences.

## Base URL

    http://localhost:8000

## Endpoints

### POST /api/predict

Generate text continuation based on a given prompt.

### Request Body

Parameter | Type | Required | Description
--- | --- | --- | ---
prompt | string | Required | The starting text to continue from
n | integer | Optional | N-gram size (2-5). Default: 4. Higher values produce more coherent but less creative text.
temperature | float | Optional | Sampling temperature (0.1-2.0). Default: 1.6. Higher values increase randomness.
length | integer | Optional | Number of words to generate (1-500). Default: 5.

### Response

Field | Type | Description
--- | --- | ---
prediction | string | The generated text continuation

### Example Request

    curl -X POST http://localhost:8000/api/predict \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "Once upon a time",
        "n": 4,
        "temperature": 1.2,
        "length": 20
      }'

### Example Response

    {
      "prediction": "in a kingdom far away there lived a brave knight who sought adventure..."
    }

### JavaScript Example

    const response = await fetch('/api/predict', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: 'The old wizard',
        n: 3,
        temperature: 0.8,
        length: 15
      })
    });

    const data = await response.json();
    console.log(data.prediction);

### Python Example

    import requests

    response = requests.post('http://localhost:8000/api/predict',
        json={
            'prompt': 'In the beginning',
            'n': 4,
            'temperature': 1.0,
            'length': 25
        }
    )

    result = response.json()
    print(result['prediction'])

## Model Parameters

### N-gram Size (n)

Controls the context window size. Higher values use more context words to predict the next word:

- n=2 (Bigram): Uses 1 previous word for context. Very creative but less coherent.
- n=3 (Trigram): Uses 2 previous words. Balanced creativity and coherence.
- n=4 (Tetragram): Uses 3 previous words. More coherent, less random.
- n=5 (Pentagram): Uses 4 previous words. Most coherent, closest to training data.

### Temperature

Controls the randomness of predictions:

- Low (0.1-0.5): More deterministic, picks most likely words.
- Medium (0.6-1.0): Balanced between predictability and creativity.
- High (1.1-2.0): More random and creative, may produce unexpected results.

## Error Handling

The API returns standard HTTP status codes:

- 200 OK: Request successful
- 422 Unprocessable Entity: Invalid request parameters
- 500 Internal Server Error: Server error

## Rate Limits

Currently, there are no rate limits imposed on the API. For production use, consider implementing appropriate rate limiting.