Data Format

Input Format

Input has the following parts:

• Message history - includes past (context) and new (to be processed) user messages
• Audio files - contents of audio files referenced in message history
• Character - AI character to use for responses (string identifier OR custom character object)
• Character params - optional field, only applicable if character personality is a template (jinja). Note: context name is reserved for the RAG
• Generate audio - optional flag indicating whether audio should be generated for the response (default: true)

{
    "input": {
        "messages": [...],
        "audio_files": { ... },
        "character": "...",
        "character_params": { ... },
        "generate_audio": true|false
    }
}

Character Parameter

You can specify a character in two ways:

Option 1: Character Identifier (String)

Use a character identifier string to reference a predefined character:

{
    "input": {
        "character": "github:partner/character",
        "messages": [...]
    }
}

Option 2: Custom Character (Object)

Define a custom character configuration inline:

{
    "input": {
        "character": {
            "description": "{\"name\": \"Assistant\", \"voice\": \"...\"}",
            "personality": "You are a helpful assistant..."
        },
        "messages": [...]
    }
}

When using a custom character:

• description must be a JSON string containing the character configuration
• personality must be a string containing the system prompt

See the character editor app for valid configuration examples.

Legacy Support: The character_name field is still supported for backwards compatibility but is deprecated in favor of character.

Message History

Messages should be ordered chronologically, past (context) messages followed by 1 or more new (to be processed) user messages - distinguished by a flag.

All past messages should only have text, new messages might be either text or audio and should have unique id.

Past Message Format

{
    "id": 1,
    "originator": "bot|user",
    "text": "",
    "is_processed": false
}

New Message Format

{
    "id": 5,
    "type": "text|audio",
    "text": "",
    "audio_file_id": "",
    "is_processed": false
}

Audio Files

Audio files included in both input and output as base64-encoded. The only supported format is OGG, response is also OGG (Telegram compatible). Please note that max size for the whole payload is 5MB.

{
    "msg1": "",
    "msg2": ""
}

Output Format

Output includes all relevant messages:

1. New user messages with transcripts
2. Generated audio message with the transcript

{
    "messages": [...],
    "audio_files": {
        "response": ""
    }
}

New User Message Format

{
    "id": "",
    "type": "",
    "text": ""
}

Generated Message Format

{
    "type": "audio",
    "text": "",
    "audio_file_id": "response"
}