mirror of
https://github.com/moeru-ai/airi.git
synced 2026-08-14 08:52:42 +00:00
docs(en): refresh manual and provider guides (#2153)
This commit is contained in:
Columbina
+112
-11
@@ -142,7 +142,7 @@ export default defineConfig<ThemeConfig>({
|
||||
{
|
||||
text: 'Quick Start',
|
||||
items: [
|
||||
{ text: 'Desktop Version', link: withBase('/en/docs/manual/tamagotchi/') },
|
||||
{ text: 'Desktop ver.', link: withBase('/en/docs/manual/tamagotchi/') },
|
||||
{ text: 'Web Version', link: withBase('/en/docs/manual/web/') },
|
||||
],
|
||||
},
|
||||
@@ -151,30 +151,131 @@ export default defineConfig<ThemeConfig>({
|
||||
text: 'Configuration',
|
||||
items: [
|
||||
{ text: 'Configuration Guide', link: withBase('/en/docs/manual/config/') },
|
||||
{ text: 'Common Setup', link: withBase('/en/docs/manual/config/common') },
|
||||
{ text: 'Feature Configuration', collapsed: true, items: [
|
||||
{ text: 'Chat Models', link: withBase('/en/docs/manual/config/llm') },
|
||||
{ text: 'Audio Input and Output', link: withBase('/en/docs/manual/config/audio') },
|
||||
{ text: 'Vision', link: withBase('/en/docs/manual/config/vision') },
|
||||
{ text: 'Web Search', link: withBase('/en/docs/manual/config/web-search') },
|
||||
] },
|
||||
{ text: 'Service Providers', collapsed: true, items: [
|
||||
{ text: 'Chat', collapsed: true, items: [
|
||||
{ text: 'AIRI Official Provider', link: withBase('/en/docs/manual/config/providers/consciousness/official') },
|
||||
{ text: 'AIHubMix', link: withBase('/en/docs/manual/config/providers/consciousness/aihubmix') },
|
||||
{ text: 'Amazon Bedrock', link: withBase('/en/docs/manual/config/providers/consciousness/amazon-bedrock') },
|
||||
{ text: 'Anthropic', link: withBase('/en/docs/manual/config/providers/consciousness/anthropic') },
|
||||
{ text: 'Atlas Cloud', link: withBase('/en/docs/manual/config/providers/consciousness/atlascloud') },
|
||||
{ text: 'Azure AI Foundry', link: withBase('/en/docs/manual/config/providers/consciousness/azure-ai-foundry') },
|
||||
{ text: 'Azure OpenAI', link: withBase('/en/docs/manual/config/providers/consciousness/azure-openai') },
|
||||
{ text: 'BytePlus', link: withBase('/en/docs/manual/config/providers/consciousness/byteplus') },
|
||||
{ text: 'BytePlus Coding Plan', link: withBase('/en/docs/manual/config/providers/consciousness/byteplus-coding-plan') },
|
||||
{ text: 'Cerebras', link: withBase('/en/docs/manual/config/providers/consciousness/cerebras') },
|
||||
{ text: 'Comet API', link: withBase('/en/docs/manual/config/providers/consciousness/comet-api') },
|
||||
{ text: 'Google Gemini', link: withBase('/en/docs/manual/config/providers/consciousness/google-gemini') },
|
||||
{ text: 'xAI', link: withBase('/en/docs/manual/config/providers/consciousness/xai') },
|
||||
{ text: 'Cloudflare Workers AI', link: withBase('/en/docs/manual/config/providers/consciousness/cloudflare-workers-ai') },
|
||||
{ text: 'LM Studio (Local Model)', link: withBase('/en/docs/manual/config/providers/consciousness/lm-studio') },
|
||||
{ text: 'OpenPaths', link: withBase('/en/docs/manual/config/providers/consciousness/openpaths') },
|
||||
{ text: 'OpenRouter', link: withBase('/en/docs/manual/config/providers/consciousness/openrouter') },
|
||||
{ text: 'Ollama', link: withBase('/en/docs/manual/config/providers/consciousness/ollama') },
|
||||
{ text: 'DeepSeek', link: withBase('/en/docs/manual/config/providers/consciousness/deepseek') },
|
||||
{ text: 'OpenAI & Compatible APIs', link: withBase('/en/docs/manual/config/providers/consciousness/openai') },
|
||||
{ text: '302.AI', link: withBase('/en/docs/manual/config/providers/consciousness/302ai') },
|
||||
{ text: 'Fireworks.ai', link: withBase('/en/docs/manual/config/providers/consciousness/fireworks') },
|
||||
{ text: 'Featherless AI', link: withBase('/en/docs/manual/config/providers/consciousness/featherless') },
|
||||
{ text: 'Groq', link: withBase('/en/docs/manual/config/providers/consciousness/groq') },
|
||||
{ text: 'MiniMax', link: withBase('/en/docs/manual/config/providers/consciousness/minimax') },
|
||||
{ text: 'MiniMax Global', link: withBase('/en/docs/manual/config/providers/consciousness/minimax-global') },
|
||||
{ text: 'Mistral', link: withBase('/en/docs/manual/config/providers/consciousness/mistral') },
|
||||
{ text: 'Xiaomi MiMo', link: withBase('/en/docs/manual/config/providers/consciousness/mimo') },
|
||||
{ text: 'ModelScope', link: withBase('/en/docs/manual/config/providers/consciousness/modelscope') },
|
||||
{ text: 'Moonshot AI', link: withBase('/en/docs/manual/config/providers/consciousness/moonshot') },
|
||||
{ text: 'NVIDIA NIM', link: withBase('/en/docs/manual/config/providers/consciousness/nvidia') },
|
||||
{ text: 'n1n', link: withBase('/en/docs/manual/config/providers/consciousness/n1n') },
|
||||
{ text: 'Novita', link: withBase('/en/docs/manual/config/providers/consciousness/novita') },
|
||||
{ text: 'Perplexity', link: withBase('/en/docs/manual/config/providers/consciousness/perplexity') },
|
||||
{ text: 'Together.ai', link: withBase('/en/docs/manual/config/providers/consciousness/together') },
|
||||
{ text: 'Z.ai', link: withBase('/en/docs/manual/config/providers/consciousness/zhipu') },
|
||||
{ text: 'Volcengine Coding Plan', link: withBase('/en/docs/manual/config/providers/consciousness/volcengine-coding-plan') },
|
||||
] },
|
||||
{ text: 'Speech', collapsed: true, items: [
|
||||
{ text: 'Official Speech Provider', link: withBase('/en/docs/manual/config/providers/speech/official') },
|
||||
{ text: 'Alibaba Cloud Model Studio', link: withBase('/en/docs/manual/config/providers/speech/alibaba-cloud-model-studio') },
|
||||
{ text: 'Browser (Local)', link: withBase('/en/docs/manual/config/providers/speech/browser-local') },
|
||||
{ text: 'Comet API', link: withBase('/en/docs/manual/config/providers/speech/comet-api') },
|
||||
{ text: 'Deepgram', link: withBase('/en/docs/manual/config/providers/speech/deepgram') },
|
||||
{ text: 'Desktop (Local)', link: withBase('/en/docs/manual/config/providers/speech/desktop-local') },
|
||||
{ text: 'ElevenLabs', link: withBase('/en/docs/manual/config/providers/speech/elevenlabs') },
|
||||
{ text: 'Google Gemini', link: withBase('/en/docs/manual/config/providers/speech/google-gemini') },
|
||||
{ text: 'Bilibili / IndexTTS', link: withBase('/en/docs/manual/config/providers/speech/index-tts') },
|
||||
{ text: 'Kokoro TTS (Local)', link: withBase('/en/docs/manual/config/providers/speech/kokoro') },
|
||||
{ text: 'Microsoft Azure Speech', link: withBase('/en/docs/manual/config/providers/speech/azure-speech') },
|
||||
{ text: 'MiniMax Speech (Unavailable)', link: withBase('/en/docs/manual/config/providers/speech/minimax') },
|
||||
{ text: 'Xiaomi MiMo', link: withBase('/en/docs/manual/config/providers/speech/mimo') },
|
||||
{ text: 'OpenAI & Compatible APIs', link: withBase('/en/docs/manual/config/providers/speech/openai') },
|
||||
{ text: 'OpenRouter', link: withBase('/en/docs/manual/config/providers/speech/openrouter') },
|
||||
{ text: 'Player2', link: withBase('/en/docs/manual/config/providers/speech/player2') },
|
||||
{ text: 'Volcano Engine', link: withBase('/en/docs/manual/config/providers/speech/volcengine') },
|
||||
] },
|
||||
{ text: 'Transcription', collapsed: true, items: [
|
||||
{ text: 'Official Transcription Provider', link: withBase('/en/docs/manual/config/providers/transcription/official') },
|
||||
{ text: 'Aliyun NLS', link: withBase('/en/docs/manual/config/providers/transcription/aliyun') },
|
||||
{ text: 'Browser (Local)', link: withBase('/en/docs/manual/config/providers/transcription/browser-local') },
|
||||
{ text: 'Browser Web Speech API', link: withBase('/en/docs/manual/config/providers/transcription/web-speech-api') },
|
||||
{ text: 'Comet API', link: withBase('/en/docs/manual/config/providers/transcription/comet-api') },
|
||||
{ text: 'Desktop (Local)', link: withBase('/en/docs/manual/config/providers/transcription/desktop-local') },
|
||||
{ text: 'Xiaomi MiMo', link: withBase('/en/docs/manual/config/providers/transcription/mimo') },
|
||||
{ text: 'OpenAI & Compatible APIs', link: withBase('/en/docs/manual/config/providers/transcription/openai') },
|
||||
] },
|
||||
{ text: 'Artistry', collapsed: true, items: [
|
||||
{ text: 'ComfyUI (Local Workflow)', link: withBase('/en/docs/manual/config/providers/artistry/comfyui') },
|
||||
{ text: 'Nano Banana', link: withBase('/en/docs/manual/config/providers/artistry/nanobanana') },
|
||||
{ text: 'Replicate', link: withBase('/en/docs/manual/config/providers/artistry/replicate') },
|
||||
] },
|
||||
] },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Contributing',
|
||||
icon: 'lucide:users',
|
||||
text: 'Integration Services',
|
||||
icon: 'lucide:plug',
|
||||
items: [
|
||||
{
|
||||
text: 'Basic Setup',
|
||||
text: 'Games',
|
||||
items: [
|
||||
{ text: 'Environment Setup & Prerequisites', link: withBase('/en/docs/contributing/') },
|
||||
{ text: 'Minecraft Agent', link: withBase('/en/docs/integrations/minecraft') },
|
||||
{ text: 'Factorio', link: withBase('/en/docs/integrations/factorio') },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Messaging Platforms',
|
||||
items: [
|
||||
{ text: 'Satori Bot', link: withBase('/en/docs/integrations/satori') },
|
||||
{ text: 'Telegram Bot', link: withBase('/en/docs/integrations/telegram') },
|
||||
{ text: 'Discord Bot', link: withBase('/en/docs/integrations/discord') },
|
||||
{ text: 'X / Twitter (Unavailable)', link: withBase('/en/docs/integrations/x') },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Developer Guide',
|
||||
icon: 'lucide:code-2',
|
||||
items: [
|
||||
{
|
||||
text: 'Contributing',
|
||||
items: [
|
||||
{ text: 'Development Setup & First Contribution', link: withBase('/en/docs/contributing/') },
|
||||
{ text: 'Desktop App', link: withBase('/en/docs/contributing/tamagotchi') },
|
||||
{ text: 'Web UI', link: withBase('/en/docs/contributing/webui') },
|
||||
{ text: 'Web App', link: withBase('/en/docs/contributing/webui') },
|
||||
{ text: 'Documentation Site', link: withBase('/en/docs/contributing/docs') },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Games & Social Platforms',
|
||||
text: 'Desktop Debugging',
|
||||
items: [
|
||||
{ text: 'Minecraft', link: withBase('/en/docs/contributing/services/minecraft') },
|
||||
{ text: 'Satori Bot', link: withBase('/en/docs/contributing/services/satori') },
|
||||
{ text: 'Telegram Bot', link: withBase('/en/docs/contributing/services/telegram') },
|
||||
{ text: 'Discord Bot', link: withBase('/en/docs/contributing/services/discord') },
|
||||
{ text: 'Developer Tools', link: withBase('/en/docs/contributing/desktop-developer-tools') },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -24,6 +24,10 @@ details::details-content {
|
||||
overflow: clip;
|
||||
}
|
||||
|
||||
details[open]::details-content {
|
||||
height: auto;
|
||||
}
|
||||
|
||||
summary {
|
||||
cursor: pointer;
|
||||
transition: transform 200ms ease-in-out;
|
||||
|
||||
@@ -3,3 +3,11 @@ title: Design Guidelines
|
||||
description: How to contribute design to Project AIRI
|
||||
---
|
||||
|
||||
::: warning Work in progress
|
||||
This section is still under construction.
|
||||
:::
|
||||
|
||||
See the pages in the sidebar for more information:
|
||||
|
||||
- [Resources](./resources)
|
||||
- [Tools](./tools)
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: Desktop Developer Tools
|
||||
description: Use the diagnostic and validation tools under Settings → System → Developer in the Desktop ver.
|
||||
---
|
||||
|
||||
The **System → Developer** page in the Desktop ver. contains tools for development, troubleshooting, and validation of experimental features. These tools do not improve everyday chat or character interactions. You do not need to configure them after installation. Use them only to reproduce a problem, develop a feature, or collect diagnostics for a maintainer.
|
||||
|
||||
This page covers the desktop app only. The web app also has development pages, but its available features and runtime environment differ.
|
||||
|
||||
::: warning Know what you are testing
|
||||
Some tools capture the screen, use the microphone, register global shortcuts, open additional windows, or display raw network and plugin data. Stop capture streams and close unused windows after testing. Do not publicly share screenshots containing API keys, conversations, screen contents, or WebSocket data.
|
||||
:::
|
||||
|
||||
## Open the page and choose a tool
|
||||
|
||||
In the desktop app, open **Settings → System → Developer**. Quick actions and rendering switches appear at the top; links to individual diagnostic pages appear below.
|
||||
|
||||
Choose a tool based on what you need to investigate:
|
||||
|
||||
| What you need to check | Start with |
|
||||
| --- | --- |
|
||||
| Page errors, element styles, or network requests | Open Developer Tools |
|
||||
| Three.js or VRM rendering diagnostics | Lag Visualizer |
|
||||
| Broken transition animations | the animation switches |
|
||||
| Keyboard, mouse, display, or global-shortcut behavior | useMagicKeys, mouse/display tools, or Global Shortcut |
|
||||
| Chat context, WebSockets, or real-time transcription | Context Flow, WebSocket Inspector, or Aliyun Real-time Transcriber |
|
||||
| Plugin discovery, loading, or unloading | Plugin Host Debug |
|
||||
| Failed updates or an unexpected update source | Updater |
|
||||
| Screen sharing, vision input, or capture permissions | Screen Capture or Vision Capture |
|
||||
|
||||
## Quick actions and rendering diagnostics
|
||||
|
||||
### Open Developer Tools
|
||||
|
||||
Select **Open** to launch Electron's built-in browser developer tools. Use them to inspect console errors, network requests, the DOM, and performance recordings. This is usually the best starting point for an interface problem.
|
||||
|
||||
For a reproducible issue, clear the console, repeat the action once, and save only the relevant errors. Remove sensitive information before attaching diagnostics to an issue or pull request.
|
||||
|
||||
### Markdown Stress
|
||||
|
||||
This tool renders high-volume Markdown in a separate window to test long passages, code blocks, tables, scrolling, and theme styles. It does not modify your documents or conversations.
|
||||
|
||||
### IO Tracer
|
||||
|
||||
IO Tracer shows the timing spans for interaction turns across ASR, LLM, Streaming Control, TTS, and Playback. Use it to locate delays or missing stages in the voice-and-chat pipeline. Trace data can contain contextual information, so open it only when needed and avoid sharing complete traces.
|
||||
|
||||
### Lag Visualizer
|
||||
|
||||
Lag Visualizer traces the Stage Three runtime. It reports the window lifecycle, Three.js render counts and resources, VRM frame-update timing, fade-on-hover hit tests, VRM load and disposal timing, and renderer/resource snapshots. Use it for Three.js or VRM rendering problems; it is not a general page-transition, long-task, or FPS profiler.
|
||||
|
||||
### Stage and page transition animations
|
||||
|
||||
**Disable Stage Transitions** removes the overall animation used when switching stages. Turn it on to remove stage transitions as a variable during testing. **Use Page Specific Transitions** controls each page's own transition and is unavailable while **Disable Stage Transitions** is on.
|
||||
|
||||
When investigating flickering, pages that do not unload, or slow transitions, test each state separately. Restore your normal settings after testing.
|
||||
|
||||
## Keyboard, mouse, and displays
|
||||
|
||||
### useMagicKeys
|
||||
|
||||
This page shows keyboard shortcut and modifier-key state so you can confirm that the app receives key events correctly. It has no regular user settings. To change AIRI's Spotlight shortcut, use **Settings → System → Window Shortcuts** instead.
|
||||
|
||||
### useElectronWindowMouse, Displays, and Relative Mouse
|
||||
|
||||
These tools show pointer positions in different coordinate systems:
|
||||
|
||||
- **useElectronWindowMouse** shows the pointer in the desktop coordinate space formed by all displays.
|
||||
- **Displays** shows connected displays and the pointer's current location. Use it for multi-display, scaling, or external-monitor problems.
|
||||
- **Relative Mouse** shows the pointer relative to the AIRI window. Use it to test hit areas and dragging inside the window.
|
||||
|
||||
When reporting window-following, click-offset, or multi-display positioning problems, include the display arrangement, scale factors, primary display, and reproduction steps.
|
||||
|
||||
### Widgets Calling
|
||||
|
||||
Widgets Calling creates overlay widgets and validates the component props passed to them. It is intended for desktop-overlay and component-call development; regular AIRI use does not require it.
|
||||
|
||||
### Beat Sync Visualizer
|
||||
|
||||
Beat Sync Visualizer plots beat-synchronized V-motion targets, paths, and Y/Z scalar changes. Use **Hit beat** or **Hit V sequence** to inject test beats and inspect the resulting motion. This page has no audio input or automatic beat-detection path.
|
||||
|
||||
## Chat, real-time services, and networking
|
||||
|
||||
### Context Flow
|
||||
|
||||
Context Flow shows context updates entering the chat pipeline and chat-stream events sent to services. It is useful for confirming that context from plugins, VS Code, and other external sources reaches AIRI.
|
||||
|
||||
Open the tool first, perform the smallest reproduction, and then compare the input context and output events in chronological order. Context can contain filenames, conversations, or other private information; redact logs before sharing them.
|
||||
|
||||
### WebSocket Inspector
|
||||
|
||||
WebSocket Inspector displays raw WebSocket traffic. Use it for failed connections, missing events, or messages with an unexpected format. Share only the few frames relevant to the problem, and remove tokens, user content, and address information.
|
||||
|
||||
### Aliyun Real-time Transcriber
|
||||
|
||||
This page sends audio from the system's default microphone to Alibaba Cloud NLS and displays the transcription as it arrives. It validates the real-time speech-recognition path: default microphone input, credentials, network connectivity, and transcription output. The page does not provide an input-device selector, so choose the desired default microphone in the operating system before opening it. Record only where you have permission.
|
||||
|
||||
## Plugins, updates, and system features
|
||||
|
||||
### Plugin Host Debug
|
||||
|
||||
Plugin Host Debug shows whether plugins are discovered, enabled, and loaded, and lets developers control their load and unload lifecycle. For a plugin that does not work, check discovery, enabled state, load errors, and whether events or interface state remain after unloading.
|
||||
|
||||
Record the current state and errors before changing anything. Repeatedly loading and unloading a plugin without a minimal reproduction can make the original problem harder to diagnose.
|
||||
|
||||
### Updater
|
||||
|
||||
Updater shows the current version, platform, architecture, update channel, update source, log location, and update state. It can also check for, download, and install updates manually. Use it to investigate failed updates, unexpected update sources, or platform-specific installation problems.
|
||||
|
||||
For routine updates, prefer the **About** window. Do not override the update source unless you understand and trust it.
|
||||
|
||||
## Screen and vision capture
|
||||
|
||||
### Screen Capture
|
||||
|
||||
Screen Capture can capture an application window or an entire display and create a video or audio stream. It is primarily a test page for screen-sharing and capture behavior.
|
||||
|
||||
The operating system may request screen-recording permission on first use. On macOS, if AIRI is not listed, enable or add it under **System Settings → Privacy & Security → Screen & System Audio Recording**, restart AIRI, and try again. Permission prompts on Windows and Linux depend on the operating system, desktop environment, and Electron version.
|
||||
|
||||
In the tool, **Applications** lists application windows and **Displays** lists entire screens. The current implementation does not supply external sources to the **Devices** tab, so that tab remains empty. Use **Refetch** after connecting or disconnecting a display, opening a window, or changing permissions. After stopping, confirm that the preview has closed so the stream no longer uses system resources or permissions.
|
||||
|
||||
### Vision Capture
|
||||
|
||||
Vision Capture captures screen frames and shows the payload sent through the vision pipeline. Use it to verify that vision input is captured correctly and reaches downstream features. It is a diagnostic workflow, not a global switch that must remain open after configuring a vision provider.
|
||||
|
||||
To test screen vision:
|
||||
|
||||
1. Configure a vision provider's credentials under **Settings → Providers → Vision**.
|
||||
2. Open **Settings → Modules → Vision**, then select the configured provider and an image-capable model.
|
||||
3. Open **Settings → System → Developer → Vision Capture** and grant the operating system's screen-recording permission.
|
||||
4. Choose a window or display, then select **Start ticker** to begin capturing and analyzing frames.
|
||||
5. Enable **Publish to character** only when you want recognition results added to AIRI's conversation context.
|
||||
6. Select **Stop ticker** when finished. Leaving the page also stops the capture loop.
|
||||
|
||||
If the page remains on a permission prompt, grant permission in the operating system, fully quit AIRI, restart it, and reopen the tool. Never publish captures that show a personal desktop, notifications, or content from other applications.
|
||||
|
||||
## Global shortcuts
|
||||
|
||||
### Global Shortcut
|
||||
|
||||
Global Shortcut registers, unregisters, and observes system-wide shortcut events. It differs from the Spotlight shortcut configured for everyday use under **Settings → System → Window Shortcuts**: this page exists for development and validation.
|
||||
|
||||
Choose a key combination that does not conflict with the operating system or another application. If registration fails, check whether that combination is already in use. Unregister the shortcut after testing so it does not continue intercepting keys.
|
||||
@@ -1,20 +1,27 @@
|
||||
---
|
||||
title: Documentation Site
|
||||
description: Contribute to Project AIRI
|
||||
title: Documentation Site Development
|
||||
description: Write, preview, and validate the VitePress documentation locally
|
||||
---
|
||||
|
||||
### Documentation site
|
||||
The documentation site is in `docs`, with content organized by locale under `docs/content/<locale>`. From the repository root, run:
|
||||
|
||||
```shell
|
||||
pnpm dev:docs
|
||||
```
|
||||
|
||||
::: tip
|
||||
To validate only the documentation site, run:
|
||||
|
||||
For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can
|
||||
```shell
|
||||
pnpm -F @proj-airi/docs typecheck
|
||||
pnpm -F @proj-airi/docs build
|
||||
```
|
||||
|
||||
When adding an English page, also add it to the `en` sidebar in `docs/.vitepress/config.ts`. Otherwise, the page will be available by URL but will not appear in the navigation.
|
||||
|
||||
::: tip
|
||||
If you use [@antfu/ni](https://github.com/antfu-collective/ni), run:
|
||||
|
||||
```shell
|
||||
nr dev:docs
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
@@ -1,50 +1,37 @@
|
||||
---
|
||||
title: Contributing
|
||||
description: Contributing to Project AIRI
|
||||
title: Development Setup and Your First Contribution
|
||||
description: Run Project AIRI locally and submit your first pull request
|
||||
---
|
||||
|
||||
Hello! Thank you for your interest in contributing to this project. This guide will help you get started.
|
||||
Hello! Thank you for your interest in contributing to Project AIRI. This guide explains how to set up a local development environment, create a branch, and submit your first pull request.
|
||||
|
||||
::: info Scope
|
||||
This section is for contributors who want to change source code, documentation, or design resources. If you only want to use AIRI, start with the user manual. For the debugging tools built into the app, see [Developer Tools](./desktop-developer-tools).
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Git](https://git-scm.com/downloads)
|
||||
- [Node.js 23+](https://nodejs.org/en/download/)
|
||||
- [corepack](https://github.com/nodejs/corepack)
|
||||
- [pnpm](https://pnpm.io/installation)
|
||||
- [mise](https://mise.jdx.dev/installing-mise.html), or another version manager that reads `.tool-versions`
|
||||
- [Corepack](https://github.com/nodejs/corepack), which is included with recent Node.js releases
|
||||
|
||||
The repository pins Node.js in [`.tool-versions`](https://github.com/moeru-ai/airi/blob/main/.tool-versions) (currently 24.13.0). Install that pinned version after cloning instead of relying on the version supplied by a system package manager.
|
||||
|
||||
<details>
|
||||
<summary>Windows setup</summary>
|
||||
|
||||
0. Download [Visual Studio](https://visualstudio.microsoft.com/downloads/), and follow the instructions here: https://rust-lang.github.io/rustup/installation/windows-msvc.html#walkthrough-installing-visual-studio-2022
|
||||
|
||||
> Make sure to install Windows SDK and C++ build tools when installing Visual Studio.
|
||||
|
||||
1. Open PowerShell
|
||||
2. Install [`scoop`](https://scoop.sh/)
|
||||
1. Open PowerShell.
|
||||
2. Install [`scoop`](https://scoop.sh/).
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
|
||||
```
|
||||
|
||||
3. Install `git`, Node.js, `rustup`, `msvc` through `scoop`
|
||||
3. Install Git and mise with Scoop.
|
||||
|
||||
```powershell
|
||||
scoop install git nodejs rustup
|
||||
|
||||
# For Rust dependencies
|
||||
# Not required if you are not going to develop on either crates or apps/tamagotchi
|
||||
scoop install main/rust-msvc
|
||||
# Rust & Windows specific
|
||||
rustup toolchain install stable-x86_64-pc-windows-msvc
|
||||
rustup default stable-x86_64-pc-windows-msvc
|
||||
```
|
||||
|
||||
4. Install `pnpm` through `corepack`
|
||||
|
||||
```powershell
|
||||
corepack enable
|
||||
corepack prepare pnpm@latest --activate
|
||||
scoop install git mise
|
||||
```
|
||||
|
||||
</details>
|
||||
@@ -52,18 +39,11 @@ Hello! Thank you for your interest in contributing to this project. This guide w
|
||||
<details>
|
||||
<summary>macOS setup</summary>
|
||||
|
||||
0. Open Terminal, (or iTerm2, Ghostty, Kitty, etc.)
|
||||
1. Install `git`, `node` through `brew`
|
||||
1. Open Terminal, iTerm2, Ghostty, Kitty, or another terminal.
|
||||
2. Install Git and mise with Homebrew.
|
||||
|
||||
```shell
|
||||
brew install git node
|
||||
```
|
||||
|
||||
2. Install `pnpm` through `corepack`
|
||||
|
||||
```shell
|
||||
corepack enable
|
||||
corepack prepare pnpm@latest --activate
|
||||
brew install git mise
|
||||
```
|
||||
|
||||
</details>
|
||||
@@ -71,152 +51,130 @@ Hello! Thank you for your interest in contributing to this project. This guide w
|
||||
<details>
|
||||
<summary>Linux setup</summary>
|
||||
|
||||
0. Open Terminal
|
||||
1. Follow [nodesource/distributions: NodeSource Node.js Binary Distributions](https://github.com/nodesource/distributions?tab=readme-ov-file#table-of-contents) to install `node`
|
||||
2. Follow [Git](https://git-scm.com/downloads/linux) to install `git`
|
||||
3. Install `pnpm` through `corepack`
|
||||
|
||||
```shell
|
||||
corepack enable
|
||||
corepack prepare pnpm@latest --activate
|
||||
```
|
||||
4. If you would love to help to develop the desktop version, you will need those dependencies:
|
||||
```shell
|
||||
sudo apt install \
|
||||
libssl-dev \
|
||||
libglib2.0-dev \
|
||||
libgtk-3-dev \
|
||||
libjavascriptcoregtk-4.1-dev \
|
||||
libwebkit2gtk-4.1-dev
|
||||
```
|
||||
1. Open a terminal.
|
||||
2. Follow the [Git installation instructions for Linux](https://git-scm.com/downloads/linux).
|
||||
3. Install mise using the [package or installation method for your distribution](https://mise.jdx.dev/installing-mise.html).
|
||||
|
||||
</details>
|
||||
|
||||
## If you have already contributed to this project before
|
||||
|
||||
::: warning
|
||||
|
||||
If you haven't clone this repository, skip this section.
|
||||
## If you have contributed before
|
||||
|
||||
::: tip
|
||||
Skip this section if you have not cloned the repository yet.
|
||||
:::
|
||||
|
||||
Make sure your local repository is up to date with the upstream repository:
|
||||
Fetch upstream changes and rebase your local `main` branch:
|
||||
|
||||
```shell
|
||||
git fetch --all
|
||||
git checkout main
|
||||
git switch main
|
||||
git pull upstream main --rebase
|
||||
```
|
||||
|
||||
If you have a working branch, to make your branch up to date with the upstream repository:
|
||||
If you already have a working branch, update it from `main`:
|
||||
|
||||
```shell
|
||||
git checkout <your-branch-name>
|
||||
git switch <your-branch-name>
|
||||
git rebase main
|
||||
```
|
||||
|
||||
## Fork this project
|
||||
## Fork the project
|
||||
|
||||
Click on the **Fork** button on the top right corner of the [moeru-ai/airi](https://github.com/moeru-ai/airi) page.
|
||||
Click **Fork** in the upper-right corner of the [moeru-ai/airi](https://github.com/moeru-ai/airi) repository page to create a copy under your account.
|
||||
|
||||
## Clone
|
||||
## Clone your fork
|
||||
|
||||
```shell
|
||||
git clone https://github.com/<your-github-username>/airi.git
|
||||
cd airi
|
||||
```
|
||||
|
||||
## Create your working branch
|
||||
## Create a working branch
|
||||
|
||||
```shell
|
||||
git checkout -b <your-branch-name>
|
||||
git switch -c <your-branch-name>
|
||||
```
|
||||
|
||||
## Install dependencies
|
||||
|
||||
```shell
|
||||
corepack enable
|
||||
pnpm install
|
||||
From the repository root, install the Node.js version recorded in `.tool-versions`, verify it, enable Corepack, and install dependencies:
|
||||
|
||||
# For Rust dependencies
|
||||
# Not required if you are not going to develop on either crates or apps/tamagotchi
|
||||
cargo fetch
|
||||
```shell
|
||||
mise install
|
||||
mise exec -- node --version
|
||||
mise exec -- corepack enable
|
||||
mise exec -- pnpm install
|
||||
```
|
||||
|
||||
The reported Node.js version must match `.tool-versions`. The remaining examples assume that [mise is activated for your shell](https://mise.jdx.dev/dev-tools/shims.html); otherwise, run package-manager commands through `mise exec --`, for example `mise exec -- pnpm typecheck`.
|
||||
|
||||
::: tip
|
||||
You can optionally install [@antfu/ni](https://github.com/antfu-collective/ni) to simplify package-manager commands:
|
||||
|
||||
```shell
|
||||
mise exec -- npm install --global @antfu/ni
|
||||
```
|
||||
|
||||
After installation:
|
||||
|
||||
- Use `ni` instead of `pnpm install`, `npm install`, or `yarn install`.
|
||||
- Use `nr` instead of `pnpm run`, `npm run`, or `yarn run`.
|
||||
|
||||
`ni` detects the package manager used by the repository.
|
||||
:::
|
||||
|
||||
## Commit your changes
|
||||
|
||||
### Validate before committing
|
||||
|
||||
Make sure the code passes linting and type checking:
|
||||
|
||||
```shell
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
We would recommend to install [@antfu/ni](https://github.com/antfu-collective/ni) to make your script simpler.
|
||||
|
||||
```shell
|
||||
corepack enable
|
||||
npm i -g @antfu/ni
|
||||
```
|
||||
|
||||
Once installed, you can
|
||||
|
||||
- use `ni` for `pnpm install`, `npm install` and `yarn install`.
|
||||
- use `nr` for `pnpm run`, `npm run` and `yarn run`.
|
||||
|
||||
You don't need to care about the package manager, `ni` will help you choose the right one.
|
||||
:::
|
||||
|
||||
## Choose the application you want to develop on
|
||||
|
||||
## Commit
|
||||
|
||||
### Before commit
|
||||
|
||||
::: warning
|
||||
|
||||
Please make sure lint (static checkers) and TypeScript compilers are satisfied:
|
||||
|
||||
```shell
|
||||
pnpm lint && pnpm typecheck
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
::: tip
|
||||
|
||||
If you have [@antfu/ni](https://github.com/antfu-collective/ni) installed, you can use `nr` to run the commands:
|
||||
If you installed [@antfu/ni](https://github.com/antfu-collective/ni), run:
|
||||
|
||||
```shell
|
||||
nr lint && nr typecheck
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Commit
|
||||
### Create the commit
|
||||
|
||||
```shell
|
||||
git add .
|
||||
git add <changed-files>
|
||||
git commit -m "<your-commit-message>"
|
||||
```
|
||||
|
||||
### Push to your fork repository
|
||||
### Push your branch
|
||||
|
||||
```shell
|
||||
git push origin <your-branch-name> -u
|
||||
git push -u origin <your-branch-name>
|
||||
```
|
||||
|
||||
You should be able to browse the branch on your fork repository.
|
||||
Your branch should now be available on GitHub.
|
||||
|
||||
::: tip
|
||||
|
||||
If this is your first time contributing with this project, you need to add the upstream repository too:
|
||||
If this is your first contribution, add the Project AIRI repository as the `upstream` remote:
|
||||
|
||||
```shell
|
||||
git remote add upstream https://github.com/moeru-ai/airi.git
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Creating Pull Request
|
||||
## Create a pull request
|
||||
|
||||
Navigate to [moeru-ai/airi](https://github.com/moeru-ai/airi) page, click on the **Pull requests** tab, and click on the **New pull request** button, click on the **Compare across forks** link, and select your fork repository.
|
||||
Open the [moeru-ai/airi](https://github.com/moeru-ai/airi) repository page:
|
||||
|
||||
Review the changes, and click on the **Create pull request** button.
|
||||
1. Click **Pull requests**.
|
||||
2. Click **New pull request**.
|
||||
3. Click **Compare across forks**.
|
||||
4. Select your fork and working branch.
|
||||
5. Review the changes, then click **Create pull request**.
|
||||
|
||||
## Whooo-ya! You made it!
|
||||
## You made it!
|
||||
|
||||
Congratulations! You made your first contribution to this project. You can now wait for the maintainers to review your pull request.
|
||||
Congratulations on submitting your first contribution. The project maintainers can now review your pull request.
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Discord Bot
|
||||
description: Contribute to Project AIRI
|
||||
---
|
||||
|
||||
### Discord bot integration
|
||||
|
||||
```shell
|
||||
cd integrations/discord-bot
|
||||
```
|
||||
|
||||
Configure `.env`
|
||||
|
||||
```shell
|
||||
cp .env .env.local
|
||||
```
|
||||
|
||||
Edit the credentials in `.env.local`.
|
||||
|
||||
Run the bot
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/discord-bot start
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can
|
||||
|
||||
```shell
|
||||
nr -F @proj-airi/discord-bot dev
|
||||
```
|
||||
|
||||
:::
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
title: Minecraft
|
||||
description: Contribute to Project AIRI
|
||||
---
|
||||
|
||||
### Minecraft agent
|
||||
|
||||
```shell
|
||||
cd integrations/minecraft
|
||||
```
|
||||
|
||||
Start a Minecraft client, export your world with desired port, and fill-in the port number in `.env.local`.
|
||||
|
||||
Configure `.env`
|
||||
|
||||
```shell
|
||||
cp .env .env.local
|
||||
```
|
||||
|
||||
Edit the credentials in `.env.local`.
|
||||
|
||||
Run the bot
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/minecraft-bot start
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can
|
||||
|
||||
```shell
|
||||
nr -F @proj-airi/minecraft-bot dev
|
||||
```
|
||||
|
||||
:::
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Satori Bot
|
||||
description: Contribute to Project AIRI
|
||||
---
|
||||
|
||||
### Satori Bot
|
||||
|
||||
```shell
|
||||
cd integrations/satori-bot
|
||||
```
|
||||
|
||||
Configure the `.env` file:
|
||||
|
||||
```shell
|
||||
cp .env .env.local
|
||||
```
|
||||
|
||||
Edit various keys and configuration information in `.env.local`.
|
||||
|
||||
Start the bot:
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/satori-bot dev
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
If you use [@antfu/ni](https://github.com/antfu-collective/ni), you can:
|
||||
|
||||
```shell
|
||||
nr -F @proj-airi/satori-bot dev
|
||||
```
|
||||
|
||||
:::
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: Telegram Bot
|
||||
description: Contribute to Project AIRI
|
||||
---
|
||||
|
||||
### Telegram bot integration
|
||||
|
||||
A Postgres database is required.
|
||||
|
||||
```shell
|
||||
cd integrations/telegram-bot
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Configure `.env`
|
||||
|
||||
```shell
|
||||
cp .env .env.local
|
||||
```
|
||||
|
||||
Edit the credentials in `.env.local`.
|
||||
|
||||
Migrate the database
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/telegram-bot db:generate
|
||||
pnpm -F @proj-airi/telegram-bot db:push
|
||||
```
|
||||
|
||||
Run the bot
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/telegram-bot start
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can
|
||||
|
||||
```shell
|
||||
nr -F @proj-airi/telegram-bot dev
|
||||
```
|
||||
|
||||
:::
|
||||
@@ -1,20 +1,29 @@
|
||||
---
|
||||
title: Desktop
|
||||
description: Contribute to Project AIRI
|
||||
title: Desktop Development
|
||||
description: Run, check, and build the Electron desktop app
|
||||
---
|
||||
|
||||
### Stage Tamagotchi (Desktop version)
|
||||
The desktop app is in `apps/stage-tamagotchi`. From the repository root, run:
|
||||
|
||||
```shell
|
||||
pnpm dev:tamagotchi
|
||||
```
|
||||
|
||||
::: tip
|
||||
This starts the Electron development environment. Before changing desktop pages, check whether the relevant shared component or state already exists in `packages/stage-ui`. Logic used by both the web and desktop apps should normally live in a shared package.
|
||||
|
||||
For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can
|
||||
## Validation
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/stage-tamagotchi typecheck
|
||||
pnpm -F @proj-airi/stage-tamagotchi build
|
||||
```
|
||||
|
||||
For the **System → Developer** menu and the purpose of each debugging tool, see [Developer Tools](./desktop-developer-tools).
|
||||
|
||||
::: tip
|
||||
If you use [@antfu/ni](https://github.com/antfu-collective/ni), run:
|
||||
|
||||
```shell
|
||||
nr dev:tamagotchi
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
@@ -1,20 +1,31 @@
|
||||
---
|
||||
title: Web UI
|
||||
description: Contribute to Project AIRI
|
||||
title: Web App Development
|
||||
description: Run, check, and build the AIRI web app
|
||||
---
|
||||
|
||||
### Stage Web (Browser version for [airi.moeru.ai](https://airi.moeru.ai))
|
||||
The web app is in `apps/stage-web` and powers [airi.moeru.ai](https://airi.moeru.ai). From the repository root, run:
|
||||
|
||||
```shell
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
::: tip
|
||||
You can also use the more explicit command:
|
||||
|
||||
For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can
|
||||
```shell
|
||||
pnpm dev:web
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
```shell
|
||||
pnpm -F @proj-airi/stage-web typecheck
|
||||
pnpm -F @proj-airi/stage-web build
|
||||
```
|
||||
|
||||
::: tip
|
||||
If you use [@antfu/ni](https://github.com/antfu-collective/ni), run:
|
||||
|
||||
```shell
|
||||
nr dev
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Discord Bot
|
||||
description: Run AIRI as a voice and messaging bot using a Discord application
|
||||
---
|
||||
|
||||
The Discord bot connects to text and voice channels in a Discord server. Text replies come from the chat provider and model selected in AIRI.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Install dependencies from the repository root with **pnpm i**.
|
||||
- Create an application and bot in the [Discord Developer Portal](https://discord.com/developers/home).
|
||||
- Enable **Message Content Intent** in the bot settings.
|
||||
- Configure a working chat provider and model in AIRI.
|
||||
|
||||
::: warning Credential security
|
||||
Keep the Bot Token and AIRI Auth Token only in AIRI's local settings or the bot service's local **.env.local** file. Do not commit, screenshot, or share these credentials.
|
||||
:::
|
||||
|
||||
## Configure the bot service
|
||||
|
||||
```bash
|
||||
cp integrations/discord-bot/.env integrations/discord-bot/.env.local
|
||||
```
|
||||
|
||||
In the Desktop ver., open **Settings → Connection**. Show and copy the **Auth Token**. Then add these values to **integrations/discord-bot/.env.local**:
|
||||
|
||||
```env
|
||||
AIRI_URL=ws://localhost:6121/ws
|
||||
AIRI_TOKEN=<Auth Token from Settings → Connection>
|
||||
```
|
||||
|
||||
`DISCORD_TOKEN` is an optional startup fallback. You can leave it empty and send the Bot Token from AIRI after the service connects. The service does not use `DISCORD_BOT_CLIENT_ID`, `OPENAI_MODEL`, `OPENAI_API_*`, or `ELEVENLABS_*`; Discord text replies use AIRI's active chat configuration.
|
||||
|
||||
For Discord voice input, configure an OpenAI-compatible transcription endpoint with `OPENAI_STT_API_BASE_URL`, `OPENAI_STT_API_KEY`, and `OPENAI_STT_MODEL`. These values are not required for text channels, but voice transcription cannot complete without them.
|
||||
|
||||
## Start the service
|
||||
|
||||
```bash
|
||||
pnpm -F @proj-airi/discord-bot start
|
||||
```
|
||||
|
||||
## Configure Discord in AIRI
|
||||
|
||||
1. Open **Settings → Modules → Discord**.
|
||||
2. Paste the bot token into **Bot Token**.
|
||||
3. Turn on **Enable Discord Integration**.
|
||||
4. Click **Save**.
|
||||
|
||||
The authenticated bot service receives the enabled state and token through AIRI's configuration channel. If the service is not running or its AIRI Auth Token is missing or incorrect, saving these fields alone does not start the Discord bot.
|
||||
|
||||
## Install and use the bot in Discord
|
||||
|
||||
1. In the Discord Developer Portal, configure a **Guild Install** with the `bot` scope and install the bot in your server. The `bot` scope includes `applications.commands` by default. Grant only the permissions required by the features you use:
|
||||
- Text replies: **View Channels** and **Send Messages**.
|
||||
- Voice input: **View Channels** and **Connect**.
|
||||
- Voice playback: **Speak**.
|
||||
2. For text chat, send the bot a direct message or mention it in a server channel. The bot does not respond to every server message.
|
||||
3. For voice input, join a voice channel and run `/summon`. The service registers `/ping` and `/summon` after the bot logs in.
|
||||
|
||||
If the bot works in some channels but not others, check the channel-level permission overrides.
|
||||
|
||||
## Security notes
|
||||
|
||||
Limit the bot's access to the channels and capabilities it needs. If the Bot Token is lost or exposed, reset it immediately in the Discord Developer Portal.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Factorio
|
||||
description: Connect AIRI to a trusted Factorio server
|
||||
---
|
||||
|
||||
The Factorio integration connects AIRI to an external game service. The Desktop ver. provides settings for the server address, port, and player name. You must supply a reachable Factorio server and a compatible server-side integration.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A reachable Factorio server.
|
||||
- Permission from the server administrator for your account and server-side integration to connect.
|
||||
- The server address, port, and your in-game username.
|
||||
|
||||
::: warning Connect only to trusted servers
|
||||
This integration exchanges context and action requests with the game server. Do not use it with an untrusted public server, and do not expose server addresses, tokens, or account information in public chats, screenshots, or issues.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Modules → Factorio**.
|
||||
2. Enable **Factorio Integration**.
|
||||
3. Enter the server address, port, and your in-game username. The default port is `34197`.
|
||||
4. Click **Save**. A **configured** status only means that all three fields have values; an actual connection still depends on the server and its server-side integration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Check that the device running AIRI can reach the server address and port.
|
||||
- Confirm that no firewall, VPN, or server allowlist blocks the connection.
|
||||
- Confirm that the username matches the player name on the server.
|
||||
- If the settings are saved but AIRI still cannot interact, inspect the server-side integration logs. The Desktop ver. does not include a ready-to-deploy Factorio bot service.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Minecraft Agent
|
||||
description: Run AIRI's local game agent on a trusted Minecraft server
|
||||
---
|
||||
|
||||
The Minecraft integration uses Mineflayer to connect AIRI to a Minecraft server so the agent can receive context, perform in-game actions, and report state. It is intended for local development and maintenance. The current implementation is planned to migrate to a Fabric runtime, so avoid building new long-term features around it.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Install dependencies from the repository root with **pnpm i**.
|
||||
- Provide a reachable local or trusted Minecraft server. The connection address and port come from the environment configuration.
|
||||
- Configure a working chat provider and model in AIRI, and prepare the OpenAI-compatible model settings used by the Minecraft agent.
|
||||
|
||||
::: warning Credential security
|
||||
Keep API keys, service addresses, and Minecraft server credentials only in the local **.env.local** file. Do not commit, screenshot, or share these values.
|
||||
:::
|
||||
|
||||
## Configure
|
||||
|
||||
```bash
|
||||
cp integrations/minecraft/.env integrations/minecraft/.env.local
|
||||
```
|
||||
|
||||
Edit **integrations/minecraft/.env.local** and provide the required Minecraft server, AIRI, and model-service settings.
|
||||
|
||||
In the Desktop ver., open **Settings → Connection**. Show and copy the **Auth Token**. Then add these AIRI channel settings:
|
||||
|
||||
```env
|
||||
AIRI_WS_BASEURL=ws://localhost:6121/ws
|
||||
AIRI_CLIENT_NAME=minecraft-bot
|
||||
AIRI_WS_TOKEN=<Auth Token from Settings → Connection>
|
||||
```
|
||||
|
||||
Also configure `BOT_HOSTNAME`, `BOT_PORT`, and the `OPENAI_API_BASEURL`, `OPENAI_API_KEY`, `OPENAI_MODEL`, and `OPENAI_REASONING_MODEL` values required by your server and model service. Keep the defaults only when they match your local setup.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
pnpm -F @proj-airi/minecraft-bot dev
|
||||
```
|
||||
|
||||
After startup, use the terminal output to verify that authentication to AIRI succeeds and that the agent connects to the Minecraft server. A missing or incorrect `AIRI_WS_TOKEN` prevents the module from registering with AIRI.
|
||||
|
||||
## Security and limitations
|
||||
|
||||
Do not connect the agent to an untrusted public server. It controls a local Minecraft session and network connection. Even when action planning runs in an isolated environment, a malicious server may still cause unexpected behavior.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Satori Bot
|
||||
description: Bridge AIRI to multiple messaging platforms through Koishi and the Satori protocol
|
||||
---
|
||||
|
||||
The Satori bot connects to messaging platforms such as QQ, Telegram, Discord, and Lark through Koishi's Satori service. The current standalone core is transitional and is suitable for experiments and maintenance; it should not be treated as a stable AIRI Core integration.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Install dependencies from the repository root with **pnpm i**.
|
||||
- Run a Koishi instance with the **server-satori** plugin enabled.
|
||||
- Provide a model service with an OpenAI-compatible API.
|
||||
|
||||
::: warning Credential security
|
||||
Keep the Satori token, messaging-platform credentials, and model API keys only in the local **.env.local** file. Do not commit, screenshot, or share these values.
|
||||
:::
|
||||
|
||||
## Configure
|
||||
|
||||
```bash
|
||||
cp integrations/satori-bot/.env integrations/satori-bot/.env.local
|
||||
```
|
||||
|
||||
Edit **integrations/satori-bot/.env.local** and provide **SATORI_WS_URL**, **SATORI_API_BASE_URL**, the optional **SATORI_TOKEN**, and the LLM address, key, and model.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
pnpm -F @proj-airi/satori-bot dev
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
Messaging-platform addresses, tokens, and model credentials are sensitive. Do not commit **.env.local** or send its contents to anyone.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Telegram Bot
|
||||
description: Run AIRI as a Telegram bot using PostgreSQL and model services
|
||||
---
|
||||
|
||||
The Telegram bot requires a Telegram Bot Token, a PostgreSQL vector database, and model services. The repository Compose service runs PostgreSQL with pgvecto.rs 0.4.0 in pgvector compatibility mode. The bot is intended to be run from source.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Install dependencies from the repository root with **pnpm i**.
|
||||
- Create a Telegram bot with [@BotFather](https://t.me/BotFather) and obtain its token.
|
||||
- Make Docker available to start the repository's PostgreSQL vector service.
|
||||
- Prepare chat-model and embedding-model services.
|
||||
|
||||
::: warning Credential security
|
||||
Keep the Telegram Bot Token, database connection, and model API keys only in the local **.env.local** file. Do not commit, screenshot, or share these values.
|
||||
:::
|
||||
|
||||
## Configure
|
||||
|
||||
```bash
|
||||
cp integrations/telegram-bot/.env integrations/telegram-bot/.env.local
|
||||
```
|
||||
|
||||
Edit **integrations/telegram-bot/.env.local** and provide **TELEGRAM_BOT_TOKEN**, the database connection, and the chat-model and embedding-model settings. The embedding service's output size must match `EMBEDDING_DIMENSION`; supported values are `768`, `1024`, and `1536`.
|
||||
|
||||
## Initialize the database
|
||||
|
||||
```bash
|
||||
cd integrations/telegram-bot
|
||||
docker compose up -d --wait pgvector
|
||||
cd ../..
|
||||
pnpm -F @proj-airi/telegram-bot db:push
|
||||
```
|
||||
|
||||
The repository Compose file exposes PostgreSQL on host port `5433`. When using that service, set:
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgres://postgres:123456@localhost:5433/postgres
|
||||
```
|
||||
|
||||
Starting only `pgvector` avoids launching the optional Grafana, Tempo, Prometheus, and OpenTelemetry services.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
pnpm -F @proj-airi/telegram-bot start
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
The database, Telegram token, and model credentials are sensitive. Do not commit **.env.local**. Before the first deployment, also confirm the database backup and access-control arrangements.
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: X / Twitter (unavailable)
|
||||
description: Current implementation status of AIRI's X / Twitter integration
|
||||
---
|
||||
|
||||
The X / Twitter integration is not functional in AIRI 0.11.3. Although **Settings → Modules → X / Twitter** displays credential fields and can show **configured**, the app cannot currently deliver that configuration to the separate X service.
|
||||
|
||||
::: warning Do not enter X credentials
|
||||
|
||||
Do not enter an API Key, API Secret, Access Token, or Access Token Secret in the current version. The **configured** state means only that all four fields contain values; it does not confirm a working service connection.
|
||||
:::
|
||||
|
||||
## Current limitation
|
||||
|
||||
Before investigating the protocol mismatch, contributors must start the external process with `ENABLE_AIRI=true`, `AIRI_URL=ws://localhost:6121/ws`, and an `AIRI_TOKEN` that matches **Settings → Connection → Auth Token**. The checked-in defaults disable the AIRI adapter, point it to `http://localhost:3000`, and provide no token. Correcting these settings only allows the service to connect; it does not repair the incompatible configuration flow described below.
|
||||
|
||||
The AIRI module publishes configuration under the module name `twitter`, while the external service expects `x`. The channel protocols also disagree: the server forwards configuration as `module:configure` with a `{ config }` payload, but the service listens for `ui:configure` and expects a `moduleName` field. The external service also runs as a separate process and is not started by AIRI. Fixing only the module name or starting the service manually is therefore not enough to make the form work.
|
||||
|
||||
There is no supported end-user workaround. Contributors investigating the implementation can compare:
|
||||
|
||||
- `packages/stage-ui/src/stores/modules/twitter.ts`
|
||||
- `integrations/twitter-services/src/adapters/airi-adapter.ts`
|
||||
|
||||
## Credential security
|
||||
|
||||
If you previously entered credentials, remove them from AIRI and rotate them in the [X Developer Portal](https://developer.x.com/en/portal/dashboard) if they may have been exposed. Never commit, screenshot, or share X credentials.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Configure voice input and output
|
||||
description: Configuring AIRI for speech synthesis (TTS) and speech recognition (ASR/STT)
|
||||
---
|
||||
|
||||
Speech synthesis (TTS) reads AIRI's text responses aloud; speech recognition (ASR/STT) converts microphone audio into text. You can configure either capability independently.
|
||||
|
||||
## Configure speech synthesis (TTS)
|
||||
|
||||
1. Open **Settings → Providers → Speech**, select a provider, and enter its credentials.
|
||||
2. Use the provider playground, when available, to synthesize a short test sentence.
|
||||
3. Open **Settings → Modules → Speech** and select the configured provider, model, and voice.
|
||||
|
||||
See **Service Providers → Speech** in the sidebar for provider-specific instructions. If your provider implements the OpenAI speech interface, see [OpenAI Compatible API (TTS)](./providers/speech/openai.md).
|
||||
|
||||
## Configure speech recognition (ASR/STT)
|
||||
|
||||
1. Open **Settings → Providers → Transcription**, select a provider, and enter its credentials.
|
||||
2. Open **Settings → Modules → Hearing** and select the configured provider and model.
|
||||
3. Select the correct microphone, click **Start Monitoring**, and say a brief sentence.
|
||||
4. Confirm that the text appears correctly in the recognition result area.
|
||||
|
||||
See **Service Providers → Transcription** in the sidebar for provider-specific instructions. If your provider supports the OpenAI-compatible transcription interface, see [OpenAI Compatible API (ASR/STT)](./providers/transcription/openai.md).
|
||||
|
||||
## FAQ
|
||||
|
||||
### TTS no sound
|
||||
|
||||
Confirm that the Speech provider, model, and voice are selected, and check the system output device and volume. If the playground reports an error, check the API key, account credit, and model capabilities.
|
||||
|
||||
### ASR produces no text
|
||||
|
||||
Confirm that AIRI has permission to the microphone and that the correct input device is selected on the Hearing page. For real-time recognition services, network outages or browser/system microphone permissions being revoked can also result in empty results.
|
||||
|
||||
### Incorrect language or voice
|
||||
|
||||
Select a model and voice that the provider supports for the target language. Transcription language, region, and model settings must match the capabilities enabled for the provider account.
|
||||
|
||||
## Next step
|
||||
|
||||
For field and validation details, read [Common Configuration Instructions](./common.md). Provider-specific guides are under **Providers → Speech** and **Providers → Transcription**.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: General configuration instructions
|
||||
description: Understand AIRI's provider configuration flow, fields, and verification methods
|
||||
---
|
||||
|
||||
This page explains how AIRI's provider configuration works. For a provider's API endpoint, account setup, and model selection, see its provider-specific guide.
|
||||
|
||||
## Configuration process
|
||||
|
||||
1. Open **Settings → Providers** and select **Chat**, **Vision**, **Speech**, **Transcription**, or **Artistry**.
|
||||
2. Select a provider and enter the credentials required by its settings page.
|
||||
3. If necessary, expand the advanced settings and enter the Base URL or other parameters from the provider's documentation.
|
||||
4. Wait for automatic validation. Where available, use **Ping API** or the provider playground for a live test.
|
||||
5. Select the provider and model or voice on the corresponding page under **Settings → Modules**.
|
||||
|
||||
::: warning Credential security
|
||||
Credentials and provider settings are saved in the current device's local settings. Never disclose credentials such as API keys or AccessKey Secrets in screenshots, logs, issues, or chat messages.
|
||||
:::
|
||||
|
||||
## Common fields
|
||||
|
||||
| Field | Meaning | Guidance |
|
||||
| --- | --- | --- |
|
||||
| API Key | Access token issued by the provider | Paste the complete key without adding quotes or spaces. |
|
||||
| Base URL | Root URL of the provider API | Change it only when the provider's documentation requires another URL. Include the complete `https://` or `http://` address. |
|
||||
| Model | Model ID used for chat, speech, or recognition | Prefer a model from AIRI's list. If the list cannot be loaded and the field accepts custom input, enter the exact ID from the provider's documentation. |
|
||||
| Voice | Voice ID used for speech synthesis | Select the model first, then select a voice supported by that model. |
|
||||
| Region | Deployment region used by some cloud services | Match the project or resource region shown in the provider console. |
|
||||
|
||||
## Verification results
|
||||
|
||||
Chat-provider forms validate required fields automatically; providers that expose **Ping API** can also send a live request, which may consume a small amount of credit. Speech-provider playgrounds test synthesis and playback when available. Test transcription from **Settings → Modules → Hearing** with the selected microphone.
|
||||
|
||||
When verification fails, troubleshoot in this order:
|
||||
|
||||
1. Confirm that the account has access to the service and available credit or quota.
|
||||
2. Copy the API Key again and make sure you did not include leading or trailing spaces or line breaks.
|
||||
3. Restore the default Base URL, or compare it exactly with the provider's official documentation.
|
||||
4. Confirm that the network, proxy, and firewall allow access to the provider.
|
||||
5. Choose a model that is explicitly supported by the provider; do not use the display name as a model ID.
|
||||
|
||||
## Next
|
||||
|
||||
- To configure text replies, read [Configure a chat model](./llm.md).
|
||||
- To configure speech output or microphone input, read [Configure voice input and output](./audio.md).
|
||||
@@ -1,48 +1,56 @@
|
||||
---
|
||||
title: Configuration Guide
|
||||
description: How to use Project AIRI
|
||||
title: Provider configuration guide
|
||||
description: Configure Chat, Vision, Speech, Transcription, and Artistry providers for Project AIRI
|
||||
---
|
||||
|
||||
## Settings
|
||||
To chat with AIRI, configure at least one Chat provider and chat model. Speech synthesis (TTS) adds voice output, while automatic speech recognition (ASR/STT) adds microphone input. Voice input and output are optional and can be configured independently.
|
||||
|
||||
You can open settings in the system tray for further customization, for example,
|
||||
changing the theme color of AIRI, or switching to another model, either
|
||||
Live2D (2D) or VRM (3D, like Grok Companion).
|
||||
## Configure the minimum required setup
|
||||
|
||||
<video autoplay loop muted>
|
||||
1. Open AIRI’s **Settings → Providers**.
|
||||
2. Select a provider in the **Chat** category, enter its credentials, and complete the available verification.
|
||||
3. Open **Settings → Modules → Consciousness** and select the provider and model you configured.
|
||||
4. Send a message to confirm that AIRI can reply.
|
||||
|
||||
After Chat is working, add voice input or output as needed:
|
||||
|
||||
* **[General Instructions](./common.md)**: Understand the configuration process, field meanings, verification results and FAQs.
|
||||
* **[Configure Chat Model](./llm.md)**: Configure LLM and select the model in Consciousness.
|
||||
* **[Configure Speech Input and Output](./audio.md)**: Configure TTS and ASR/STT and enable them in **Modules → Speech** and **Modules → Hearing**.
|
||||
* **[Configure Visual Understanding](./vision.md)**: Configure a separate Vision provider and select an image-capable model.
|
||||
* **[Configure Web Search](./web-search.md)**: Use Tavily to let AIRI search the Internet for the latest information when needed.
|
||||
* **Providers**: Expand **Providers** in the sidebar and select **Chat**, **Vision**, **Speech**, **Transcription**, or **Artistry**. Provider pages save credentials; module pages select which provider and model AIRI actively uses.
|
||||
|
||||
> [!TIP]
|
||||
> Configure Chat first if you want to verify the basic setup. Add TTS and ASR afterward to isolate any voice-configuration problems.
|
||||
|
||||
## Additional setup
|
||||
|
||||
After configuring a provider, you can also change AIRI's theme or switch its display model. The current model selector supports Live2D, Spine, VRM, MMD, and Tachie.
|
||||
|
||||
<video autoplay loop muted playsinline preload="metadata" poster="/assets/tutorial-basic-open-settings-poster.avif">
|
||||
<source src="/assets/tutorial-basic-open-settings.mp4" type="video/mp4">
|
||||
</video>
|
||||
|
||||
There are so many options in the settings, try experiment and discover what
|
||||
you would like to try.
|
||||
When configuring a service provider, use the default address and model name from its documentation whenever possible. Don't guess at the Base URL, model ID, or region parameters; they vary by provider.
|
||||
|
||||
### Changing Model
|
||||
### Change model
|
||||
|
||||
It's possible to swap the default model out for other Live2D (2D) and VRM (3D, again,
|
||||
similar 3D model like Grok Companion as long as you have it),
|
||||
You can replace the default model with another supported 2D or 3D display model.
|
||||
|
||||
Models setting located under [Settings] -> [Models].
|
||||
Model settings are located in **Settings → Models**.
|
||||
|
||||
::: tip Importing models from VTuber Studio?
|
||||
The library we used to render the Live2D model is having difficulties to read the ZIP
|
||||
file bundled from a VTuber Studio model because of the unknown files used by VTuber Studio
|
||||
but not Live2D engine known files.
|
||||
|
||||
So when importing, before compressing the VTuber Studio model into a ZIP file, make sure
|
||||
to exclude the following files:
|
||||
|
||||
- `items_pinned_to_model.json`
|
||||
::: tip Importing a model from VTube Studio?
|
||||
Compress the complete Live2D model folder as a ZIP file. AIRI ignores VTube Studio's `items_pinned_to_model.json` metadata during import, so you do not need to remove it manually.
|
||||
:::
|
||||
|
||||
<br />
|
||||
|
||||
::: warning Bugs inside
|
||||
Currently the functionality of the reloading the scene of models is not working as intended.
|
||||
You will have to restart AIRI after loaded the model.
|
||||
::: tip Model changes
|
||||
The stage observes model-setting changes and reloads the selected renderer automatically. If an imported model itself fails to load, check its package structure and assets before restarting AIRI.
|
||||
:::
|
||||
|
||||
<br />
|
||||
|
||||
<video autoplay loop muted>
|
||||
<video autoplay loop muted playsinline preload="metadata" poster="/assets/tutorial-settings-change-model-poster.avif">
|
||||
<source src="/assets/tutorial-settings-change-model.mp4" type="video/mp4">
|
||||
</video>
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Configure chat model
|
||||
description: Configuring chat providers and models for AIRI
|
||||
---
|
||||
|
||||
The chat model is AIRI's “brain.” To generate text replies, AIRI needs either a provider account with chat-model access or a running local model service.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- AIRI is installed and running.
|
||||
- For a cloud provider, you have created an API key and confirmed that the account can use the selected chat model.
|
||||
- For a local provider, its model service is running and reachable from the device running AIRI.
|
||||
|
||||
## Configure a provider and model
|
||||
|
||||
1. Open **Settings → Providers → Chat** and select the provider you want to use.
|
||||
|
||||
When you are not sure which one to choose, start with [OpenRouter](./providers/consciousness/openrouter.md), [DeepSeek](./providers/consciousness/deepseek.md), [OpenAI Compatible](./providers/consciousness/openai.md), or local [Ollama](./providers/consciousness/ollama.md). Other chat providers are listed under **Providers → Chat**.
|
||||
|
||||
2. Enter the API Key. Change the Base URL in advanced settings only when the provider's documentation requires another address.
|
||||
|
||||
3. Review the automatic validation result shown on the provider page. Provider fields are saved as you edit them; validation differs by provider and may check only fields, fetch the model list, or offer **Ping API** for a small live request.
|
||||
|
||||
4. Open **Settings → Modules → Consciousness** and select the provider and model you configured.
|
||||
|
||||
AIRI loads the model list when the provider supports it. If the list cannot be loaded and the field accepts custom input, enter the exact model ID from the provider's official documentation.
|
||||
|
||||
5. Return to the chat interface and send a short message, such as “Hello.” A reply confirms that the provider and model are working.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Validation passes, but no model is available
|
||||
|
||||
First confirm that the provider supports listing models. Some providers do not return a model list, or the API key lacks the required permission. In that case, manually enter the model ID under **Settings → Modules → Consciousness**. The model ID must exactly match the provider documentation.
|
||||
|
||||
### Verification failed or request timed out
|
||||
|
||||
Check the API Key, Base URL, account quota, and network connection. For a local service, verify that it is running and that AIRI can reach the configured address.
|
||||
|
||||
### AIRI does not reply
|
||||
|
||||
Confirm that both the provider and model are selected under **Settings → Modules → Consciousness**. Saving provider credentials does not enable the provider automatically.
|
||||
|
||||
## Next step
|
||||
|
||||
After chat works, continue to [Configure voice input and output](./audio.md) to let AIRI speak or use microphone input.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: ComfyUI (Artistry)
|
||||
description: Connect local ComfyUI workflows to AIRI
|
||||
---
|
||||
|
||||
ComfyUI lets AIRI use image-generation workflows from your local machine or a trusted LAN. Configure and activate the workflow on the provider page, then select **ComfyUI (Local)** under **Settings → Modules → Artistry**.
|
||||
|
||||
::: info Why choose ComfyUI?
|
||||
Choose ComfyUI to use your own installed models, nodes, and workflows while keeping image generation in your local environment.
|
||||
:::
|
||||
|
||||
## Prepare ComfyUI services and workflows
|
||||
|
||||
1. Start ComfyUI. AIRI connects to `http://localhost:8188` by default.
|
||||
2. Prepare an image workflow that can be executed directly in ComfyUI, and export its API workflow JSON from ComfyUI.
|
||||
3. If AIRI and ComfyUI are not on the same device, confirm that the address can be accessed from the device where AIRI is located.
|
||||
|
||||
::: warning Local Services and Workflow Security
|
||||
Do not expose ComfyUI's service ports to untrusted public networks. Check the nodes, model paths and parameters in the workflow before importing it, and do not import workflow JSON from unknown sources.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Artistry → ComfyUI**.
|
||||
2. Fill in the ComfyUI **Server URL**. The default is `http://localhost:8188`.
|
||||
3. Click **Test** to confirm that AIRI can read the ComfyUI service status.
|
||||
4. Upload the API workflow JSON in the Workflow area, enter a name, and select the input fields that AIRI may control.
|
||||
5. Save the workflow and make it the active workflow.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. In **Settings → Modules → Consciousness**, select a chat model that supports tool calling. AIRI needs the model to invoke the Artistry tool before ComfyUI receives a generation task.
|
||||
2. Open **Settings → Modules → Artistry** and select **ComfyUI (Local)**.
|
||||
3. Return to chat and ask AIRI to generate a non-sensitive image.
|
||||
4. Confirm that the task appears in ComfyUI's Queue or History. A returned image confirms that the connection, active workflow, exposed fields, and chat-model tool call work.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Test fails:** Confirm that ComfyUI is running and that the **Server URL**, port, and network route are correct.
|
||||
- **The browser reports a cross-origin error:** Restart ComfyUI with the CORS options shown on AIRI's ComfyUI provider page.
|
||||
- **The workflow fails in ComfyUI:** Import the API-format workflow JSON, then confirm that every referenced custom node and model is installed.
|
||||
- **No task appears in Queue or History:** For the interactive Artistry flow, confirm that the selected chat model supports tool calling and that **Settings → Modules → Artistry** is set to **ComfyUI (Local)**. Text-only models that cannot call tools cannot start an interactive Artistry task.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Nano Banana (Artistry)
|
||||
description: Configuring Nano Banana image generation in AIRI
|
||||
---
|
||||
|
||||
Nano Banana uses a Google AI Studio API key to generate images. Configure it under **Settings → Providers → Artistry**, then enable it under **Settings → Modules → Artistry**.
|
||||
|
||||
::: info Why choose Nano Banana?
|
||||
If you already have a Google AI Studio API Key and want to use AIRI's built-in Gemini image model and resolution options directly, you can select it.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [Google AI Studio API Keys](https://aistudio.google.com/app/apikey), then create an API key.
|
||||
2. Confirm that the selected image model is available for your account and region.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke and create a new key in Google AI Studio.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Artistry → Nano Banana** and paste the API Key.
|
||||
2. Select the default model: `gemini-3.1-flash-image-preview`, `gemini-3-pro-image-preview` or `gemini-2.5-flash-image`.
|
||||
3. Select a default resolution: 1K, 2K, or 4K.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Open **Settings → Modules → Artistry** and select **Nano Banana (Preview)**.
|
||||
2. Under **Settings → Modules → Consciousness**, select a chat model that supports tool/function calling.
|
||||
3. Return to chat and ask AIRI to generate a non-sensitive image.
|
||||
4. A returned image confirms that the API key, model, resolution, and tool call work.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When authentication fails, check whether the API key is valid. If image generation fails, check your Google AI Studio account, regional availability, and current model status, then try 1K resolution or another available model.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Replicate (Artistry)
|
||||
description: Configuring Replicate image generation in AIRI
|
||||
---
|
||||
|
||||
Replicate lets AIRI generate images with cloud-hosted models. Configure it under **Settings → Providers → Artistry**, then enable it under **Settings → Modules → Artistry**.
|
||||
|
||||
::: info Why choose Replicate?
|
||||
You can choose the cloud inference service if you don't want to deploy the image model yourself and want to choose from the models available in Replicate.
|
||||
:::
|
||||
|
||||
## Obtain API Token
|
||||
|
||||
1. Log in to [Replicate API Tokens](https://replicate.com/account/api-tokens), then create an API token.
|
||||
2. Confirm that the account has an available billing method or sufficient credit.
|
||||
3. Copy the token and store it securely.
|
||||
|
||||
::: warning API Token Security
|
||||
Do not commit, screenshot, or share API tokens. If a token is exposed, revoke it immediately and create a replacement in the Replicate console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Artistry → Replicate**.
|
||||
2. Paste the API Token.
|
||||
3. Enter a model ID. AIRI defaults to `black-forest-labs/flux-schnell`; use the exact ID shown on the Replicate model page if you select another model.
|
||||
4. Set the default aspect ratio (default `16:9`) and number of inference steps (default 4) as needed.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Open **Settings → Modules → Artistry** and select **Replicate.ai (Cloud)**.
|
||||
2. Under **Settings → Modules → Consciousness**, select a chat model that supports tool/function calling.
|
||||
3. Return to chat and ask AIRI to generate a non-sensitive image.
|
||||
4. A returned image confirms that the token, model ID, account quota, and tool call work.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If authentication fails, confirm that the complete token was pasted. If a request is denied, check account quota, model access, and the model ID. If the result is unexpected, confirm the aspect ratios and parameter ranges supported by that model, then adjust the inference steps or choose another model.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: 302.AI
|
||||
description: Configure 302.AI in AIRI as a chat provider
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
302.AI is an API aggregation provider. After completing the configuration, select a 302.AI chat model under **Settings → Modules → Consciousness**.
|
||||
|
||||
::: info Why choose 302.AI?
|
||||
If you mainly use AIRI in mainland China, you can try 302.AI first. It provides an aggregated API, making it easy to try multiple models with one API Key; actual availability still depends on your network environment, payment method, and service provider policies.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [302.AI Console](https://302.ai/), then sign in or create an account.
|
||||
2. Create an API Key in the console.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the 302.AI console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → 302.AI**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.302.ai/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API Key, account balance, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by 302.AI manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: AIHubMix
|
||||
description: Configuring the AIHubMix chat model in AIRI
|
||||
---
|
||||
|
||||
AIHubMix provides chat models in AIRI and lists available models for an account.
|
||||
|
||||
::: info Why choose AIHubMix?
|
||||
You can select this if you wish to use the models provided in your AIHubMix account via an API Key.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
Log in to [AIHubMix](https://aihubmix.com/), then create an API key in the console.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
Open **Settings → Providers → Chat → AIHubMix** and fill in the **API Key**. The default Base URL is `https://aihubmix.com/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API Key, account balance, and network connection. If AIRI cannot load the model list, confirm that the Base URL is unchanged or enter the exact model ID provided by AIHubMix manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Amazon Bedrock
|
||||
description: Configuring the Amazon Bedrock Chat Model in AIRI
|
||||
---
|
||||
|
||||
Amazon Bedrock uses a Bedrock API key and AWS region to access authorized base models.
|
||||
|
||||
::: info Why choose Amazon Bedrock?
|
||||
If you already manage model access, regions, and billing in AWS, Bedrock can use this same account management approach.
|
||||
:::
|
||||
|
||||
## Prepare a Bedrock API key
|
||||
|
||||
1. Open the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), enable access to the required model, and create a Bedrock API key for the same account and region.
|
||||
|
||||
::: warning AWS Credential Security
|
||||
Do not expose the Bedrock API key. Store it only in AIRI's provider settings and revoke it when no longer needed.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Amazon Bedrock**, enter the **Amazon Bedrock API Key**, and enter the **AWS Region**; the default region is `us-east-1`.
|
||||
2. Confirm that the AWS account has access to the target model in that region. The AIRI form has no custom endpoint field.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Wait for AIRI's automatic validation after entering the API key and region.
|
||||
2. Go to **Settings → Modules → Consciousness**, select Amazon Bedrock and an authorized model, then send a message to verify the configuration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If verification fails, check that the Bedrock API key, selected AWS region, and model access belong to the same account. If a model cannot be selected, confirm in the Bedrock console that the account has access to that model in the selected region.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Anthropic
|
||||
description: Configuring the Anthropic Claude chat model in AIRI
|
||||
---
|
||||
|
||||
Anthropic provider lets AIRI use the Claude chat model. AIRI uses Anthropic's API address and your API Key; the model list is built into AIRI, so there's no need to manually fill in a Base URL or model ID to get started.
|
||||
|
||||
::: info Why choose Anthropic?
|
||||
If you are already using the Claude API, or want to use Claude models in AIRI, you can choose Anthropic directly.
|
||||
:::
|
||||
|
||||
## Create API Key
|
||||
|
||||
1. Log in to the [Anthropic Console](https://platform.claude.com/settings/keys), create an API key, and confirm that the account has API access enabled.
|
||||
2. Set an appropriate name, validity period, and quota limit for the key.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Anthropic console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Anthropic**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.anthropic.com/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Provider validation checks connectivity by sending a short chat request. If it fails, confirm that the API key is valid, the account has available credit and sufficient usage limits, no rate limit is active, and the network can reach the Anthropic API.
|
||||
|
||||
If the model selector does not show the expected model, first update AIRI or manually enter the exact model ID provided by Anthropic on the **Consciousness** page.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Atlas Cloud
|
||||
description: Configure Atlas Cloud as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Atlas Cloud provides a chat API compatible with the OpenAI format. After completing the configuration, select an Atlas Cloud model under **Settings → Modules → Consciousness**.
|
||||
|
||||
::: info Why choose Atlas Cloud?
|
||||
If you already have an Atlas Cloud API Key, or want to use the models it provides, you can choose this service provider directly.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Go to [Atlas Cloud](https://www.atlascloud.ai/) to register an account and create an API Key.
|
||||
2. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Atlas Cloud console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Atlas Cloud**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.atlascloud.ai/v1`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Atlas Cloud manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Azure AI Foundry
|
||||
description: Configure Azure AI Foundry chat model in AIRI
|
||||
---
|
||||
|
||||
Azure AI Foundry requires the resource name, model deployment information, and API Key.
|
||||
|
||||
::: info Why choose Azure AI Foundry?
|
||||
If your model deployment and access control have been completed in Azure AI Foundry, you can use this service provider to connect directly to the deployment.
|
||||
:::
|
||||
|
||||
## Prepare Azure AI Foundry resources
|
||||
|
||||
1. Log in to [Azure AI Foundry](https://ai.azure.com/), then create or open the target project and obtain the API key, resource name, and model deployment information.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the Azure API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Azure AI Foundry** and fill in the **API Key**, resource name and model ID.
|
||||
2. If the console requires a specific API version, please fill it in the interface; do not mistake the common model name for the deployment name.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. After you fill in the required fields, AIRI automatically checks that the API Key, resource name, and model ID are present. This check does not test the network connection or credentials.
|
||||
2. Go to **Settings → Modules → Consciousness**, select the Azure AI Foundry provider and deployment, then send a test message to confirm that the deployment can respond.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When validation fails, check that the API Key, resource name, deployment name, and API version are all from the same Azure AI Foundry project. Please use the deployment name, not the model name which is for presentation only.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Azure OpenAI
|
||||
description: Configure Azure OpenAI chat model in AIRI
|
||||
---
|
||||
|
||||
Azure OpenAI lets AIRI access models through your Azure resource endpoint and deployments.
|
||||
|
||||
::: info Why choose Azure OpenAI?
|
||||
If your team already deploys models and manages permissions in Azure OpenAI, this is a straightforward way to onboard.
|
||||
:::
|
||||
|
||||
## Prepare Azure OpenAI resources
|
||||
|
||||
1. Log in to the [Azure Portal](https://portal.azure.com/), then create or open an Azure OpenAI resource and obtain the endpoint and API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the Azure API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Azure OpenAI** and enter the **API Key**.
|
||||
2. Enter the complete Chat Completions URL provided by Azure. AIRI extracts the deployment name and `api-version` from the URL.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Wait for AIRI's automatic validation after entering the API key, endpoint, and deployment details.
|
||||
2. Go to **Settings → Modules → Consciousness**, select Azure OpenAI and the corresponding deployment, then send a message to verify the configuration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If validation fails, confirm that the API Key, endpoint, deployment name, and `api-version` all belong to the same Azure OpenAI resource. Use the deployment name rather than the model's display name.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: BytePlus Coding Plan
|
||||
description: Configuring the BytePlus Coding Plan chat model in AIRI
|
||||
---
|
||||
|
||||
BytePlus Coding Plan is available in AIRI as an independent provider card.
|
||||
|
||||
::: info Why choose BytePlus Coding Plan?
|
||||
If your BytePlus account has a Coding Plan, you should use this card instead of the normal BytePlus configuration to match the corresponding service plan.
|
||||
:::
|
||||
|
||||
## Prepare BytePlus Coding Plan credentials
|
||||
|
||||
1. Log in to the [BytePlus ModelArk console](https://console.byteplus.com/ark/region%3Aark%2Bap-southeast-1/application-center) and obtain the Coding Plan API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit API keys or endpoint credentials, include them in screenshots, or share them with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → BytePlus Coding Plan** and enter the API key.
|
||||
2. Keep the default **Base URL** unless the Coding Plan documentation provides another compatible API root. Models come from AIRI's static provider list; this form has no Endpoint ID or model field.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select an available model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When validation fails, check that the API key belongs to an active BytePlus Coding Plan and that the Base URL is correct. If a listed model is denied, confirm that the plan grants access to it.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: BytePlus
|
||||
description: Configuring the BytePlus chat model in AIRI
|
||||
---
|
||||
|
||||
BytePlus uses Ark-compatible chat service configuration in AIRI.
|
||||
|
||||
::: info Why choose BytePlus?
|
||||
Use this provider when your BytePlus account has Ark API access.
|
||||
:::
|
||||
|
||||
## Prepare BytePlus credentials
|
||||
|
||||
1. Log in to the [BytePlus ModelArk console](https://console.byteplus.com/ark/region%3Aark%2Bap-southeast-1/apikey) and create an API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit API keys or endpoint credentials, include them in screenshots, or share them with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → BytePlus** and enter the API key.
|
||||
2. Keep the default Base URL unless BytePlus documents another compatible API root. Models are selected from AIRI's provider list; this form has no Endpoint ID or model input.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When validation fails, check the API key, Base URL, account access, and network connection. If a model is unavailable, select one from the list exposed by the provider.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Cerebras
|
||||
description: Configuring the Cerebras chat model in AIRI
|
||||
---
|
||||
|
||||
Cerebras provides a chat model in AIRI through its compatible API.
|
||||
|
||||
::: info Why Cerebras?
|
||||
Choose Cerebras if you already use its API and want to access the models available to your account from AIRI.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
Log in to [Cerebras Cloud](https://cloud.cerebras.ai/), then create an API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
Open **Settings → Providers → Chat → Cerebras** and fill in the **API Key**. The default Base URL is `https://api.cerebras.ai/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API Key, account status, and network connection. If AIRI cannot load the model list, confirm that the Base URL is unchanged or enter the exact model ID provided by Cerebras manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Cloudflare Workers AI
|
||||
description: Configure the Cloudflare Workers AI chat model in AIRI
|
||||
---
|
||||
|
||||
Cloudflare Workers AI uses account-level credentials. In addition to the API Token, AIRI requires a Cloudflare Account ID to locate your Workers AI resources.
|
||||
|
||||
::: info Why choose Cloudflare Workers AI?
|
||||
Use this provider to run supported Workers AI models through your Cloudflare account.
|
||||
:::
|
||||
|
||||
## Prepare credentials
|
||||
|
||||
1. Open [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) and create an API token with Workers AI access.
|
||||
2. Copy the Token.
|
||||
3. In the [Cloudflare Console](https://dash.cloudflare.com/), find and copy the Account ID.
|
||||
|
||||
::: warning Safety reminder
|
||||
API Tokens are bound to account permissions. Follow the principle of least privilege and grant only the Workers AI permissions required by AIRI. Do not include the Token or Account ID in public logs.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Cloudflare Workers AI**.
|
||||
2. Fill in the **API Token** and **Account ID**.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Wait for AIRI's automatic required-field check to pass. This check only confirms that both fields contain a value; it does not contact Cloudflare or verify the credentials.
|
||||
2. Click **Select Model →** to open **Settings → Modules → Consciousness**, then select Cloudflare Workers AI and an available model.
|
||||
3. Return to the chat and send a test message. A successful response confirms that the Account ID, API Token permissions, and selected model work together.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the required-field check fails, confirm that both **API Token** and **Account ID** contain a value. If the test message fails, check that the Token has Workers AI permissions and belongs to the same Cloudflare account as the Account ID. This provider does not use an editable Base URL, so do not enter a Worker URL or API path.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: CometAPI
|
||||
description: Configuring the CometAPI chat model in AIRI
|
||||
---
|
||||
|
||||
CometAPI provides a chat model in AIRI and also has independent TTS and STT service provider pages.
|
||||
|
||||
::: info Why choose CometAPI?
|
||||
You can select this if you wish to configure chat, speech synthesis and speech recognition under the same CometAPI account.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [CometAPI Console](https://www.cometapi.com/console/token), then create an API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Comet API** and fill in the **API Key**. The default Base URL is `https://api.cometapi.com/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When provider validation fails, check the API key, available credit or quota, rate limits, and network connection. When the model list fails to load, confirm that the Base URL remains at the default value, or enter the exact model ID provided by CometAPI on the Consciousness page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: DeepSeek
|
||||
description: Configure DeepSeek as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
DeepSeek provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by DeepSeek in Consciousness.
|
||||
|
||||
::: info Why choose DeepSeek?
|
||||
If you want to use the DeepSeek model in AIRI, or already have a DeepSeek API Key, you can choose this service provider directly.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [DeepSeek Management Console](https://platform.deepseek.com/).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the DeepSeek console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → DeepSeek**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.deepseek.com/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by DeepSeek manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Featherless AI
|
||||
description: Configuring the Featherless.ai chat model in AIRI
|
||||
---
|
||||
|
||||
Featherless.ai provides a chat model in AIRI via a compatible API.
|
||||
|
||||
::: info Why choose Featherless.ai?
|
||||
If you have opened model access on Featherless.ai, you can directly use its API Key to configure AIRI.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [Featherless.ai](https://featherless.ai/), then create an API key in the account console.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Featherless AI** and fill in the **API Key**. The default Base URL is `https://api.featherless.ai/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API Key, account status, and network connection. If AIRI cannot load the model list, confirm that the Base URL is unchanged or enter the exact model ID provided by Featherless.ai manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Fireworks AI
|
||||
description: Configure Fireworks AI as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Fireworks AI provides a chat API that is compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by Fireworks AI in Consciousness.
|
||||
|
||||
::: info Why choose Fireworks AI?
|
||||
If you already manage models or inference services in Fireworks AI, you can directly reuse the same set of API credentials.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Follow the [Fireworks AI onboarding guide](https://docs.fireworks.ai/getting-started/onboarding) to create an API key.
|
||||
2. Create a new API Key.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Fireworks AI console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Fireworks.ai**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.fireworks.ai/inference/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Fireworks AI manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Google Gemini
|
||||
description: Configuring the Google Gemini chat model in AIRI
|
||||
---
|
||||
|
||||
The Google Gemini provider uses the OpenAI-compatible endpoint of the Google Generative Language API. After completing the configuration, select the Gemini model under **Settings → Modules → Consciousness**.
|
||||
|
||||
::: info Why choose Google Gemini?
|
||||
If you already have a Gemini API Key or want to use Gemini models in AIRI, you can choose this service provider.
|
||||
:::
|
||||
|
||||
## Create API Key
|
||||
|
||||
1. Log in to [Google AI Studio API Keys](https://aistudio.google.com/app/apikey), then create a Gemini API key.
|
||||
2. Confirm that the project to which the key belongs has enabled the Gemini API and can use the target model.
|
||||
3. Copy the API Key.
|
||||
|
||||
::: warning API Key Security
|
||||
After the key is leaked, please immediately revoke and recreate it in the Google AI developer console; do not put the key in code, screenshots, or public configuration files.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Google Gemini**.
|
||||
2. Fill in the API Key.
|
||||
3. Keep the default Base URL: `https://generativelanguage.googleapis.com/v1beta/openai/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Provider validation checks connectivity, model listing, and chat requests. If AIRI reports a permission error or an unavailable model, confirm that the Gemini API is enabled for the API key's project and that the model is available in the project's region. Use the model names returned in AIRI instead of rewriting names shown in Google AI Studio.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Groq
|
||||
description: Configure Groq as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Groq provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by Groq in Consciousness.
|
||||
|
||||
::: info Why choose Groq?
|
||||
If you value conversational responsiveness and the target model is available in Groq, try this provider.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [Groq Console](https://console.groq.com/).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Groq console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Groq**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.groq.com/openai/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Groq manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: LM Studio (local model)
|
||||
description: Configuring chat models for AIRI using local LM Studio services
|
||||
---
|
||||
|
||||
LM Studio can run models natively and provides a native API. It's suitable for users who want to run models on their own devices; no API Key is required by default.
|
||||
|
||||
::: info Why choose LM Studio?
|
||||
If you want to run the model locally and manage the model files yourself, LM Studio is an option that does not rely on the cloud API Key.
|
||||
:::
|
||||
|
||||
## Start local service
|
||||
|
||||
1. From the [LM Studio Download Page](https://lmstudio.ai/download) install and open LM Studio, then download and load a chat model.
|
||||
2. Open **Local Server** and start the local server.
|
||||
3. If AIRI cannot access local services, enable CORS in LM Studio's server settings.
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → LM Studio**.
|
||||
2. Keep the default Base URL: `http://localhost:1234/v1/`.
|
||||
3. If your LM Studio service requires authentication, fill in the API Key; otherwise, leave it blank.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the loaded model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When unable to connect, first confirm that the Local Server is running and the port is consistent with the Base URL. If AIRI and LM Studio are not on the same device, use a LAN address accessible from the AIRI device and only open the service on a trusted network.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Xiaomi MiMo
|
||||
description: Configure Xiaomi MiMo chat model in AIRI
|
||||
---
|
||||
|
||||
Xiaomi MiMo provides a chat model in AIRI and has independent TTS and STT service provider pages.
|
||||
|
||||
::: info Why choose Xiaomi MiMo?
|
||||
You can select this if you want to use chat and audio capabilities under the same MiMo account.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [Xiaomi MiMo Platform](https://platform.xiaomimimo.com/), then create an API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Xiaomi MiMo** and fill in the **API Key**. The default Base URL is `https://api.xiaomimimo.com/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API Key, account status, and network connection. If AIRI cannot load the model list, confirm that the Base URL is unchanged or enter the exact model ID provided by Xiaomi MiMo manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: MiniMax Global
|
||||
description: Configure the overseas version of MiniMax in AIRI as a chat provider
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
This page applies to API Keys created on the MiniMax overseas platform. Once configured, AIRI can use the chat model provided by MiniMax Global in Consciousness.
|
||||
|
||||
::: info Why choose MiniMax Global?
|
||||
If you create an API Key on the MiniMax overseas platform or use an overseas Token Plan, you should choose MiniMax Global. Please use [MiniMax (Mainland China)](./minimax.md) for the Key created by the Chinese mainland platform; the API Key, billing and Base URL of the two platforms cannot be mixed.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [MiniMax Global Platform](https://platform.minimax.io/).
|
||||
2. Create a pay-as-you-go API Key in **API Keys**; if using Token Plan, please obtain its dedicated Key on the corresponding subscription page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key on the MiniMax Global platform.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → MiniMax Global**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.minimax.io/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
3. Select MiniMax Global and the model in **Settings → Modules → Consciousness** and send a short message to confirm that AIRI can reply.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, confirm that the API key comes from the global platform, the Base URL is `https://api.minimax.io/v1/`, the account has available credit or quota, no rate limit is active, and the network can reach the service. A `401` response commonly means that a mainland-China key was paired with the global endpoint, or vice versa. If AIRI cannot load the model list, enter the exact model ID from MiniMax Global manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: MiniMax (Mainland China)
|
||||
description: Configure the Chinese mainland version of MiniMax in AIRI as a chat provider
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
This page applies to API Keys created on the MiniMax open platform in mainland China. MiniMax provides a chat API compatible with the OpenAI format; once configured, AIRI can use its models in Consciousness.
|
||||
|
||||
::: info Why choose MiniMax?
|
||||
If you create an API Key on the MiniMax open platform in mainland China, you should choose this service provider. Please use [MiniMax Global](./minimax-global.md) for keys created by overseas platforms.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [MiniMax Console](https://platform.minimaxi.com/).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the MiniMax console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → MiniMax**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.minimaxi.com/v1/`. The API Key, billing and Base URL of mainland China and overseas platforms cannot be mixed.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by MiniMax manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Mistral
|
||||
description: Configure Mistral as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Mistral provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by Mistral in Consciousness.
|
||||
|
||||
::: info Why choose Mistral?
|
||||
If you already use Mistral models, or want to try their multilingual models in AIRI, you can choose this provider.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [Mistral Console](https://console.mistral.ai/).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Mistral console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Mistral**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.mistral.ai/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Mistral manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: ModelScope
|
||||
description: Configuring the ModelScope chat model in AIRI
|
||||
---
|
||||
|
||||
ModelScope provides chat models in AIRI through its inference API.
|
||||
|
||||
::: info Why choose ModelScope?
|
||||
If you have managed model access in ModelScope, use this card to directly fill in the corresponding API Key.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [ModelScope](https://modelscope.cn/), then create an API key in the account console.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → ModelScope** and fill in the **API Key**. The default Base URL is `https://api-inference.modelscope.cn/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API Key, account status, and network connection. If AIRI cannot load the model list, confirm that the Base URL is unchanged or enter the exact model ID provided by ModelScope manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Moonshot AI
|
||||
description: Configure Moonshot AI as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Moonshot AI provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use Moonshot AI models in Consciousness.
|
||||
|
||||
::: info Why choose Moonshot?
|
||||
If you want to use the Moonshot model in AIRI, or already have a Moonshot API Key, you can choose this service provider directly.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open the [Moonshot Global Console](https://platform.moonshot.ai/).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Moonshot console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Moonshot AI**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the global Base URL `https://api.moonshot.ai/v1/`. A key from `platform.moonshot.cn` must instead use the China endpoint documented by that console; credentials and endpoints cannot be mixed between regions.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Moonshot manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: n1n
|
||||
description: Configuring the n1n chat model in AIRI
|
||||
---
|
||||
|
||||
n1n provides API-compatible chat model access in AIRI.
|
||||
|
||||
::: info Why choose n1n?
|
||||
If you use n1n's model service, you can fill in its service address and account credentials in AIRI.
|
||||
:::
|
||||
|
||||
## Prepare service access method
|
||||
|
||||
1. Log in to [n1n](https://n1n.ai/), then confirm your service URL and whether an API key is required.
|
||||
|
||||
::: warning Credential security
|
||||
Even though the API Key is optional, don't expose your private service address, access token, or gateway configuration.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → n1n**. The default Base URL is `https://api.n1n.ai/v1/`.
|
||||
2. Fill in the API Key according to n1n’s current service requirements; if your deployment allows anonymous access, leave it blank according to the deployer’s instructions.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When verification fails, check the service address, API Key, and deployer's access policy. If the service allows anonymous access, follow the deployer's instructions to leave the API Key blank and confirm that the address is accessible from the device running AIRI.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Novita
|
||||
description: Configure Novita as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Novita AI provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by Novita AI in Consciousness.
|
||||
|
||||
::: info Why choose Novita AI?
|
||||
If you have managed model services in Novita AI, you can directly reuse the service provider's API Key.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [Novita AI Console](https://novita.ai/dashboard).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Novita AI console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Novita**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.novita.ai/openai/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Novita AI manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: NVIDIA NIM
|
||||
description: Configure NVIDIA NIM as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
NVIDIA NIM provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by NVIDIA NIM in Consciousness.
|
||||
|
||||
::: warning Desktop only
|
||||
This provider is currently available only in the Electron desktop app. It is not exposed in AIRI Web.
|
||||
:::
|
||||
|
||||
::: info Why choose NVIDIA NIM?
|
||||
If you are already using model services on the NVIDIA NIM platform, you can connect the same set of credentials to AIRI.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [NVIDIA NIM Console](https://build.nvidia.com/).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the NVIDIA console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → NVIDIA NIM**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://integrate.api.nvidia.com/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by NVIDIA NIM manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: AIRI official provider
|
||||
description: Use AIRI's official chat provider
|
||||
---
|
||||
|
||||
If you want to get started with AIRI quickly and want to simplify configuration, you can use the official provider to enable chat.
|
||||
|
||||
::: info Why choose AIRI official provider?
|
||||
If you want to quickly experience AIRI without configuring a third-party API Key yourself, you can choose the official provider.
|
||||
:::
|
||||
|
||||
## Log in to your account
|
||||
|
||||
1. Click the login button and a browser page will open.
|
||||
2. Select a login method. We currently support email, Google and GitHub logins.
|
||||
|
||||
::: info Special reminder for Chinese users
|
||||
Users in China may not be able to log in with Google and GitHub. Please use your email to log in. Registering and logging in with a mobile phone number is not currently supported.
|
||||
:::
|
||||
|
||||
3. Follow the prompts to complete login/registration.
|
||||
|
||||
::: info
|
||||
If the email does not arrive, check the spam folder.
|
||||
:::
|
||||
|
||||
## Check available Flux
|
||||
|
||||
Flux is the balance used by AIRI official services. Any initial grant is configured by the current deployment, so check the balance shown in **Settings → Flux** rather than assuming a fixed amount.
|
||||
|
||||
## Enable the provider
|
||||
|
||||
1. Open **Settings → Modules → Consciousness**.
|
||||
2. Select **Official Provider** and the **Auto** model.
|
||||
3. Send a short message and confirm that AIRI replies.
|
||||
|
||||
AIRI selects the official provider automatically only when no chat provider is already active. If you previously selected another provider, signing in does not replace that selection.
|
||||
|
||||
## Charge Flux
|
||||
|
||||
Open **Settings → Flux** and choose an available package. On desktop, AIRI opens checkout in the system browser and refreshes the balance when the app regains focus. Builds or deployments with purchasing disabled do not offer checkout.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you do not receive the sign-in email, check your spam folder. If Flux packages are unavailable or checkout cannot be created, purchasing may be disabled for that deployment or temporarily unavailable.
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Ollama (local model)
|
||||
description: Configuring the chat model for AIRI using a local Ollama service
|
||||
---
|
||||
|
||||
Ollama is an open-source runtime for running language models locally. It provides a local API and does not require an API key by default.
|
||||
|
||||
::: info Why choose Ollama?
|
||||
If you want to run models natively, reduce dependence on cloud APIs, or place more emphasis on local processing of conversation data, Ollama is the right choice.
|
||||
:::
|
||||
|
||||
## Install Ollama
|
||||
|
||||
1. Download and install Ollama for your operating system from the [official website](https://ollama.com/).
|
||||
2. Run this command in Terminal or PowerShell to verify the installation:
|
||||
|
||||
```bash
|
||||
ollama --version
|
||||
```
|
||||
|
||||
## Download and run the model
|
||||
|
||||
1. Run this command to download and start a model:
|
||||
|
||||
```bash
|
||||
ollama run qwen2
|
||||
```
|
||||
|
||||
2. To use another model, replace `qwen2` with its model ID. The initial download time depends on the model size and network speed.
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Ollama**.
|
||||
2. Keep the default Base URL, `http://localhost:11434/v1/`. If Ollama runs on another device, enter a URL that the device running AIRI can reach.
|
||||
3. Select Ollama and the model you downloaded under **Settings → Modules → Consciousness**.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the downloaded model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If AIRI cannot connect, confirm that Ollama is running and that the Base URL uses the correct port. If AIRI and Ollama run on different devices, use a LAN address reachable from the AIRI device and expose the service only on a trusted network.
|
||||
|
||||
::: warning AIRI cannot connect to local Ollama
|
||||
If Ollama is running but AIRI reports a CORS error, add AIRI's exact origin to `OLLAMA_ORIGINS` and restart Ollama. Do not use a wildcard or expose Ollama to the public internet as a troubleshooting shortcut.
|
||||
:::
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: OpenAI and compatible APIs
|
||||
description: Configuring OpenAI or an OpenAI-compatible chat service in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Select **OpenAI** for the official OpenAI endpoint, or **OpenAI Compatible** for a third-party compatible endpoint. After completing the configuration, select the provider and chat model under **Settings → Modules → Consciousness**.
|
||||
|
||||
::: info Why choose OpenAI or Compatible API?
|
||||
If you already have an OpenAI API Key, or the service provider explicitly provides an OpenAI-compatible chat interface, you can use this configuration method. Merely having an API address ending with `/v1` or a key starting with `sk-` does not guarantee service compatibility.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. When using OpenAI official services, open [OpenAI API Keys](https://platform.openai.com/api-keys) to create an API Key; when using compatible services, open the management console of the corresponding service provider.
|
||||
2. Create an API Key on the API Key or Developer Settings page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the provider console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → OpenAI** or **OpenAI Compatible**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. When using OpenAI official services, keep the default Base URL: `https://api.openai.com/v1`; when using compatible services, fill in the API root address provided by the service provider's documentation, and do not append the `/chat/completions` path.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. For a compatible service, confirm that it supports the OpenAI Chat Completions API and that the Base URL is the API root documented by the provider.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: OpenPaths
|
||||
description: Configure OpenPaths as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
OpenPaths is a chat API provider compatible with the OpenAI format. After completing the configuration on this page, AIRI can use OpenPaths models in **Consciousness**.
|
||||
|
||||
::: info Why OpenPaths?
|
||||
If you already have an OpenPaths API Key, or want to use the model it provides, you can choose this service provider directly.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Go to [OpenPaths](https://openpaths.io/) to register an account and create an API Key.
|
||||
2. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the OpenPaths console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → OpenPaths**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://openpaths.io/v1`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by OpenPaths manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: OpenRouter
|
||||
description: Configure OpenRouter as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
OpenRouter is an aggregation API service provider. After completing the configuration on this page, AIRI can use the chat model provided by OpenRouter in Consciousness.
|
||||
|
||||
::: info Why choose OpenRouter?
|
||||
OpenRouter is convenient when you want to access multiple model vendors with one API key and billing account. You can switch among the models exposed by OpenRouter without configuring each upstream provider separately. Availability still depends on your region, network, payment method, and provider policy.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [OpenRouter API Keys](https://openrouter.ai/keys), then create a new API key.
|
||||
2. Set an appropriate name, validity period, and quota limit for the key.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the OpenRouter console.
|
||||
:::
|
||||
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → OpenRouter**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://openrouter.ai/api/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select an available OpenRouter model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by OpenRouter manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Perplexity
|
||||
description: Configure Perplexity as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Perplexity provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by Perplexity in Consciousness.
|
||||
|
||||
::: info Why choose Perplexity?
|
||||
You can choose this provider if you already have a Perplexity API account and want to use its available models in AIRI.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [Perplexity API Settings](https://www.perplexity.ai/settings/api).
|
||||
2. Create a new API Key on the API Keys page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Perplexity console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Perplexity**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.perplexity.ai/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Perplexity manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Together.ai
|
||||
description: Configure Together.ai as a chat provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Together AI provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use the models provided by Together AI in Consciousness.
|
||||
|
||||
::: info Why choose Together AI?
|
||||
If you have deployed or used the model in Together AI, you can directly reuse the corresponding API Key.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open [Together AI API Keys](https://api.together.ai/settings/api-keys).
|
||||
2. Create a new API Key.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Together AI console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Together.ai**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.together.xyz/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Together AI manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Volcengine Coding Plan
|
||||
description: Configuring the Volcengine Coding Plan chat model in AIRI
|
||||
---
|
||||
|
||||
The Volcengine Coding Plan is available as an independent provider card in AIRI.
|
||||
|
||||
::: info Why choose Volcengine Coding Plan?
|
||||
If your account uses the Volcengine Coding Plan, select this card for the corresponding service plan.
|
||||
:::
|
||||
|
||||
## Prepare Coding Plan credentials
|
||||
|
||||
1. Log in to the [Volcengine Ark Coding Plan console](https://console.volcengine.com/ark/region%3Acn-beijing/subscription/coding-plan) and obtain the Coding Plan API key.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit API keys or endpoint credentials, include them in screenshots, or share them with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Volcengine Coding Plan** and enter the API key.
|
||||
2. Keep the default **Base URL** unless the Coding Plan documentation provides another compatible API root. Models come from AIRI's static provider list; this form has no Endpoint ID or model field.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select an available model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When validation fails, check that the API key belongs to an active Volcengine Coding Plan and that the Base URL is correct. If a listed model is denied, confirm that the plan grants access to it.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: xAI
|
||||
description: Configuring the xAI Grok chat model in AIRI
|
||||
---
|
||||
|
||||
The xAI provider lets AIRI use the Grok chat model. Its configuration method is the same as that of common API Key service providers.
|
||||
|
||||
::: info Why choose xAI?
|
||||
If you already have an xAI API account and want to use the Grok model in AIRI, you can choose this service provider.
|
||||
:::
|
||||
|
||||
## Create API Key
|
||||
|
||||
1. Log in to [xAI Developer Console](https://console.x.ai/), then create an API key.
|
||||
2. Confirm that the account has been activated for API usage and has available quota.
|
||||
3. Copy the key.
|
||||
|
||||
::: warning API Key Security
|
||||
Only save the API Key in your password manager or AIRI's local settings. Do not write the key into code, commit it to a repository, or send it to others.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → xAI**.
|
||||
2. Fill in the API Key.
|
||||
3. Keep the default Base URL: `https://api.x.ai/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If provider validation fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID from the xAI documentation manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Z.ai
|
||||
description: Configure Z.ai as a chat service provider in AIRI
|
||||
is_openai_compatible: true
|
||||
---
|
||||
|
||||
Z.ai provides a chat API compatible with the OpenAI format. After completing the configuration on this page, AIRI can use Z.ai models in **Consciousness**.
|
||||
|
||||
::: info Why choose Z.ai?
|
||||
If you want to use Z.ai models in AIRI, or already have a Z.ai API key, you can choose this service provider directly.
|
||||
:::
|
||||
|
||||
## Get the API key
|
||||
|
||||
1. Open the [Z.ai API Keys page](https://z.ai/manage-apikey/apikey-list).
|
||||
2. Create a new API Key.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the Z.ai console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Chat → Z.ai**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://api.z.ai/api/paas/v4`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Validate configuration**: AIRI validates the configuration automatically as you edit it. If **Ping API** appears, use it for a live request test.
|
||||
2. **Select Model →**: After validation succeeds, use this button to open **Settings → Modules → Consciousness**, then select the provider and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the API check fails, verify the API key, available credit or quota, rate limits, and network connection. If AIRI cannot load the model list, enter the exact model ID provided by Z.ai manually on the **Consciousness** page.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Alibaba Cloud Bailian (TTS)
|
||||
description: Configuring Alibaba Cloud Bailian speech synthesis in AIRI
|
||||
---
|
||||
|
||||
Alibaba Cloud Bailian provides the CosyVoice speech synthesis model in AIRI.
|
||||
|
||||
::: info Why choose Alibaba Cloud Bailian?
|
||||
If you already use Alibaba Cloud Model Studio and want to choose among CosyVoice voices and models, this is the direct access method.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [Alibaba Cloud Bailian Console](https://bailian.console.aliyun.com/), then confirm that the model service is enabled.
|
||||
2. Create a key on the API Key management page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the Bailian API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Alibaba Cloud Model Studio**.
|
||||
2. Enter the Model Studio API key. The default Base URL is the AIRI/UnSpeech gateway at `https://unspeech.hyp3r.link/v1/`, not Alibaba Cloud's direct API. Your key, text to synthesize, model/voice selection, and returned audio pass through this gateway. Use it only if you accept that trust boundary; otherwise enter a compatible self-hosted gateway URL or choose a direct provider.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available voice in the provider playground. This page uses AIRI's default CosyVoice model.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Alibaba Cloud Model Studio**, then select an available model and voice. The provider playground tests credentials; this module selection is what enables speech for normal AIRI replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the playground cannot complete a request, check the API key, Model Studio billing and quota status, rate limits, and network connection. If a model or voice is unavailable, confirm that the corresponding model service is enabled for the Bailian account.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Microsoft Azure Speech (TTS)
|
||||
description: Configure Microsoft Azure Speech synthesis in AIRI
|
||||
---
|
||||
|
||||
Microsoft Azure Speech provides Azure speech synthesis capabilities in AIRI.
|
||||
|
||||
::: info Why choose Microsoft Azure Speech?
|
||||
If your team already manages voice resources and region configurations in Azure, it's more convenient to use the same credentials.
|
||||
:::
|
||||
|
||||
## Prepare Azure Speech resources
|
||||
|
||||
1. Log in to the [Azure Portal](https://portal.azure.com/), then create or open a Speech resource.
|
||||
2. Record the **API Key** and region of the resource; both must come from the same Speech resource.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Azure keys provide access to your Speech resource. Do not commit a key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Microsoft / Azure Speech**.
|
||||
2. Enter the API key and region. The default Base URL is the AIRI/UnSpeech gateway at `https://unspeech.hyp3r.link/v1/`, not Azure's direct API. Your key, region, text to synthesize, voice selection, and returned audio pass through this gateway. Use it only if you accept that trust boundary; otherwise enter a compatible self-hosted gateway URL or choose a direct provider.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available voice in the provider playground. This page uses AIRI's default Azure Speech model.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Microsoft / Azure Speech**, then select an available model and voice. The provider playground tests credentials; this module selection enables speech for normal AIRI replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If verification fails, first confirm that the region matches the Speech resource. If there is no sound, confirm that a voice is selected under **Settings → Modules → Speech** and that the resource has available quota.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Browser local speech synthesis (TTS, unavailable)
|
||||
description: Browser local speech synthesis is not configurable yet
|
||||
---
|
||||
|
||||
Browser (Local) speech synthesis is not available yet. Its AIRI settings page currently shows a Work in Progress placeholder, so models and voices cannot be prepared or selected.
|
||||
|
||||
::: warning Unavailable
|
||||
Do not use this provider for a working setup yet. It is documented here only so that the current availability is clear.
|
||||
:::
|
||||
|
||||
## Use an available alternative
|
||||
|
||||
Use [Kokoro](./kokoro.md) for AIRI's implemented local speech synthesis, or choose a supported cloud TTS provider.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: CometAPI (TTS)
|
||||
description: Configuring CometAPI speech synthesis in AIRI
|
||||
---
|
||||
|
||||
CometAPI provides speech synthesis through its compatible interface.
|
||||
|
||||
::: info Why choose CometAPI?
|
||||
If you already use CometAPI to manage models and credentials, you can reuse the API Key directly in AIRI.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [CometAPI Console](https://www.cometapi.com/console/token), then create an API key.
|
||||
2. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Comet API** and fill in the API Key.
|
||||
2. Keep the default Base URL: `https://api.cometapi.com/v1/`; modify it only when using a proxy or compatible gateway.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select a model and any available voice in the provider settings.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Comet API**, then select an available model and voice. The playground test alone does not enable the provider for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When verification fails, check the API Key, account balance, and network connection. When the model list is empty, confirm that the account can currently access the voice model.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Deepgram (TTS)
|
||||
description: Configuring Deepgram speech synthesis in AIRI
|
||||
---
|
||||
|
||||
Deepgram offers the Aura family of speech synthesis models in AIRI.
|
||||
|
||||
::: info Why choose Deepgram?
|
||||
If you already use Deepgram, or want to choose from the Aura range of voices, you can use this integration.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to the [Deepgram Console](https://console.deepgram.com/), then create a key on the project’s API Key page.
|
||||
2. Confirm that the project has permission to use speech synthesis.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Deepgram** and paste the API key.
|
||||
2. The default Base URL is the AIRI/UnSpeech gateway at `https://unspeech.hyp3r.link/v1/`, not Deepgram's direct API. Your API key, text to synthesize, model/voice selection, and returned audio pass through this gateway. Use it only if you accept that trust boundary; otherwise enter a compatible self-hosted gateway URL or choose a provider that connects directly.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available Aura voice in the provider playground.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Deepgram**, then select an available model and voice. The playground test alone does not enable the provider for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the playground cannot complete a request, check the project API Key, account permissions, and network connection. When the voice list is empty, retest your credentials before selecting a model.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Desktop local speech synthesis (TTS, unavailable)
|
||||
description: Desktop local speech synthesis is not configurable yet
|
||||
---
|
||||
|
||||
App (Local) speech synthesis is not available yet. Its AIRI settings page currently shows a Work in Progress placeholder, so models and voices cannot be prepared or selected.
|
||||
|
||||
::: warning Unavailable
|
||||
Do not use this provider for a working setup yet. It is documented here only so that the current availability is clear.
|
||||
:::
|
||||
|
||||
## Use an available alternative
|
||||
|
||||
Use [Kokoro](./kokoro.md) for AIRI's implemented local speech synthesis, or choose a supported cloud TTS provider.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: ElevenLabs (TTS)
|
||||
description: Configuring ElevenLabs speech synthesis in AIRI
|
||||
---
|
||||
|
||||
ElevenLabs synthesizes AIRI responses into speech.
|
||||
|
||||
::: info Why choose ElevenLabs?
|
||||
Choose this provider to use voices from your ElevenLabs account and select them directly in AIRI.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [ElevenLabs API Key Settings](https://elevenlabs.io/app/settings/api-keys), then create an API key.
|
||||
2. Give the key an easily identifiable name and appropriate usage restrictions.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. If you suspect a leak, please immediately revoke and recreate it in the ElevenLabs console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → ElevenLabs**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. The default Base URL is the AIRI/UnSpeech gateway at `https://unspeech.hyp3r.link/v1/`, not ElevenLabs' direct API. Your API key, text to synthesize, model/voice selection, and returned audio pass through this gateway. Use it only if you accept that trust boundary; otherwise enter a compatible self-hosted gateway URL or choose a provider that connects directly.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available voice in the provider playground. This page uses AIRI's default ElevenLabs model.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **ElevenLabs**, then select an available model and voice. The playground test alone does not enable the provider for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the playground cannot complete a request, check the API key, subscription character quota, rate limits, and network connection. If models load but no audio plays, confirm that a valid model and voice are selected under **Settings → Modules → Speech**.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Google Gemini (TTS)
|
||||
description: Configuring Google Gemini Audio Speech Synthesis in AIRI
|
||||
---
|
||||
|
||||
Google Gemini Audio speech synthesis uses Gemini credentials and a model that supports audio output.
|
||||
|
||||
::: info Why choose Google Gemini?
|
||||
If you have configured Google Gemini in AIRI and want to use the audio output capability under the same service provider, you can select this option.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Sign in to [Google AI Studio](https://aistudio.google.com/app/apikey), then create an API key.
|
||||
2. Confirm that the account can use the Gemini model that supports audio output.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the Gemini API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Fill in the Gemini API Key in **Settings → Providers → Speech → Google Gemini**.
|
||||
2. Keep the interface default Base URL unless you are using an enterprise gateway or compatible proxy.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select a model and any available voice in the provider settings.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Google Gemini**, then select an available audio model and voice. The playground test alone does not enable the provider for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When verification fails, check the API Key, account region availability, and network connectivity. When the request is successful but there is no sound, confirm that the selected model does support audio output.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Index-TTS (local TTS)
|
||||
description: Connecting to the local Index-TTS service in AIRI
|
||||
---
|
||||
|
||||
Index-TTS connects to AIRI through a local HTTP service.
|
||||
|
||||
::: info Why choose Index-TTS?
|
||||
You can select this if you are already running Index-TTS locally and want the sound data to remain on the local network.
|
||||
:::
|
||||
|
||||
## Start local service
|
||||
|
||||
1. Follow the deployment instructions for Index-TTS to start the service.
|
||||
2. AIRI connects to `http://localhost:11996/tts/` by default; if you use other hosts or ports, please record the complete address.
|
||||
3. Confirm that the service can return model and voice information.
|
||||
|
||||
::: warning Local service security
|
||||
Do not expose local service ports to untrusted public networks. If you change the listening address, secure access to the service yourself.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Bilibili / IndexTTS**.
|
||||
2. Enter the local service's Base URL.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available voice in the provider playground. This page uses the configured Index-TTS service and AIRI's default model ID.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Bilibili / IndexTTS**, choose model ID `IndexTTS-1.5`, and select a voice. The provider test alone does not enable speech for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When unable to connect, verify that the service is running, that the Base URL contains the correct port, and check the local firewall or reverse proxy. When the voice list is empty, check whether the `audio/voices` interface of the service is available.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Kokoro TTS (Local)
|
||||
description: Configuring native Kokoro speech synthesis in AIRI
|
||||
---
|
||||
|
||||
Kokoro runs speech synthesis as a native model in AIRI.
|
||||
|
||||
::: info Why choose Kokoro?
|
||||
Choose Kokoro if you want to synthesize speech locally and your device has enough resources to run the model.
|
||||
:::
|
||||
|
||||
## Prepare local operating environment
|
||||
|
||||
1. Open AIRI and wait for the model download to complete on first use.
|
||||
2. WebGPU accelerates synthesis when available. AIRI can fall back to WASM without WebGPU, but synthesis will generally be slower and use more CPU.
|
||||
3. This option does not require a cloud API key, but uses local storage, memory, and compute resources.
|
||||
|
||||
::: warning Local resource usage
|
||||
The model uses local storage, memory, and CPU or GPU resources. If the download cannot complete, memory pressure is high, or synthesis makes the device unresponsive, use a hosted speech provider instead.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Kokoro TTS (Local)**.
|
||||
2. Select an available Kokoro model provided by AIRI.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. **Select model and voice**: After the model is prepared, select the voice, and then go to **Settings → Modules → Speech** to enable it.
|
||||
2. Enter a short test sentence and confirm that AIRI plays the generated audio.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the model cannot load, check available storage and memory, then reopen the page and let the download finish. If WebGPU is unavailable, allow the WASM fallback more time to initialize and synthesize.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Xiaomi MiMo (TTS)
|
||||
description: Configuring Xiaomi MiMo speech synthesis in AIRI
|
||||
---
|
||||
|
||||
MiMo supports three speech synthesis modes: preset voice, sound design and sound cloning.
|
||||
|
||||
::: info Why choose Xiaomi MiMo?
|
||||
Choose MiMo if you need its preset Chinese voices or want to design voices from text descriptions.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [Xiaomi MiMo Platform](https://platform.xiaomimimo.com/), then confirm that the account has API access enabled.
|
||||
2. Create an API Key, copy it and keep it in a safe place.
|
||||
|
||||
::: warning Sound sample and API key security
|
||||
Voice cloning requires audio samples in Base64 data URI format. Upload only samples you have permission to use, and never publish API keys or another person's voice samples.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Fill in the API Key in **Settings → Providers → Speech → Xiaomi MiMo**.
|
||||
2. Keep the default Base URL: `https://api.xiaomimimo.com/v1/`, unless the service provider provides another address.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select a model and any available voice in the provider settings.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Xiaomi MiMo**, then choose the TTS model that matches your use case:
|
||||
|
||||
- `mimo-v2.5-tts` for a preset voice
|
||||
- `mimo-v2.5-tts-voicedesign` for a voice created from a text description
|
||||
- `mimo-v2.5-tts-voiceclone` for an authorized voice sample
|
||||
|
||||
Select a voice when the chosen mode provides one. The provider test alone does not enable speech for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If a request fails, check the API key, TTS model, required voice or prompt, and network connection. If voice cloning fails, verify that the sample is a valid Base64 data URI and that you have permission to use the recording.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: MiniMax Speech (TTS, unavailable)
|
||||
description: Current availability of MiniMax speech synthesis in AIRI
|
||||
---
|
||||
|
||||
MiniMax Speech appears in AIRI's provider registry, but the current app does not include a MiniMax Speech settings page. Selecting it under **Settings → Providers → Speech** therefore cannot complete a usable configuration.
|
||||
|
||||
::: warning Unavailable in AIRI 0.11.3
|
||||
Do not enter credentials or try to follow a MiniMax setup flow in this version. The provider route is not implemented, and AIRI cannot save or test the required settings from the UI.
|
||||
:::
|
||||
|
||||
## What to use instead
|
||||
|
||||
Choose another provider with a working settings page under **Settings → Providers → Speech**. If your service exposes an OpenAI-compatible speech endpoint, use [OpenAI Compatible API (TTS)](./openai.md) and follow the service's documented Base URL and model ID.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Official Speech Provider (TTS)
|
||||
description: Use officially provided speech synthesis in AIRI
|
||||
---
|
||||
|
||||
Official speech synthesis uses your active AIRI session; no third-party API Key is required.
|
||||
|
||||
::: info Why choose AIRI official speech synthesis?
|
||||
If you already use an official AIRI provider and want to reduce third-party credential configuration, try this option first.
|
||||
:::
|
||||
|
||||
## Log in to your account
|
||||
|
||||
1. Sign in with an AIRI account.
|
||||
2. Confirm that the official speech provider is available for the current session.
|
||||
|
||||
::: warning Account and service availability
|
||||
Available models, quotas, and regions are determined by the official service. Do not share account sessions or browser session data.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Official Speech Provider**.
|
||||
2. If prompted, sign in. Confirm that the page shows your Flux balance and a valid connection status.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Open **Settings → Modules → Speech**, select **Official Speech Provider**, and choose an available model and voice.
|
||||
2. Enter a short test sentence, click **Test Voice**, and confirm that AIRI plays the generated audio.
|
||||
|
||||
## Optional streaming provider
|
||||
|
||||
When the official service reports streaming TTS as available, AIRI shows a separate **Official Streaming Speech Provider** card under **Settings → Providers → Speech**.
|
||||
|
||||
In **Settings → Modules → Speech**, keep **Official Speech Provider** selected. AIRI includes the streaming models in that provider's model list. Select a streaming model and voice; AIRI then switches the internal speech provider automatically to match the selected model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the provider is unavailable, confirm that you are signed in and that AIRI can reach the official service. Also confirm that your account has enough Flux. Open **Settings → Flux** to view the available packages. The Desktop ver. opens checkout in the system browser. A purchase option does not appear if the build or deployment does not support purchases.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: OpenAI Compatible API (TTS)
|
||||
description: Configuring OpenAI or an OpenAI-compatible API as a speech synthesis provider in AIRI
|
||||
---
|
||||
|
||||
This page configures a provider that implements the OpenAI speech API. After saving the provider, select its model and voice in **Settings → Modules → Speech**.
|
||||
|
||||
::: info Why use an OpenAI-compatible API for TTS?
|
||||
Use this provider when your speech service explicitly supports the OpenAI speech API. An API address ending with `/v1` or a key starting with `sk-` does not by itself guarantee compatibility.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to the management console of the selected service provider.
|
||||
2. Create an API Key on the API Key or Developer Settings page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the provider console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → OpenAI Compatible**.
|
||||
2. Fill in the API Key and the TTS model ID to be used.
|
||||
3. For official OpenAI, select the separate **OpenAI** provider. The **OpenAI Compatible** provider has no default Base URL; enter the complete API root documented by the compatible service.
|
||||
4. Adjust the speaking speed as needed.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select the configured provider, model, and voice in **Settings → Modules → Speech**.
|
||||
2. Enter test text and click **Test Voice**.
|
||||
3. If the test audio plays, the provider is configured correctly. If AIRI displays an error, use its message to check the credentials, model ID, and Base URL.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If no audio plays, confirm that the selected model and voice are supported by the provider. For a compatible service, verify that it implements the OpenAI speech API.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: OpenRouter (TTS)
|
||||
description: Configuring OpenRouter as a speech synthesis service provider in AIRI
|
||||
---
|
||||
|
||||
OpenRouter is an aggregation API service provider. After completing the configuration, select the model and voice provided by OpenRouter under **Settings → Modules → Speech**.
|
||||
|
||||
::: info Why choose OpenRouter Voice?
|
||||
Choose this provider if you want to manage supported speech models and voices through an OpenRouter account. Availability still depends on your network environment, payment method, and OpenRouter policies.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Open [OpenRouter API Keys](https://openrouter.ai/keys), then create a new API key.
|
||||
2. Set an appropriate name, validity period, and quota limit for the key.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the OpenRouter console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → OpenRouter**.
|
||||
2. Paste the API Key into the basic settings.
|
||||
3. Keep the default Base URL: `https://openrouter.ai/api/v1/`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select the configured provider, model, and voice under **Settings → Modules → Speech**.
|
||||
2. Enter test text and click **Test Voice**.
|
||||
3. If the test audio plays, the provider is configured correctly. If AIRI displays an error, use its message to check the credentials and model.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When there is no sound, confirm that the selected model provides voice output, and check the account balance and network connection.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Player2 (TTS)
|
||||
description: Connecting to local Player2 Speech service in AIRI
|
||||
---
|
||||
|
||||
Player2 Speech is a speech synthesis option connected via a local service.
|
||||
|
||||
::: info Why choose Player2?
|
||||
If you already run Player2 Speech locally or on a trusted LAN, you can connect AIRI to the service and use its available voices.
|
||||
:::
|
||||
|
||||
## Start local service
|
||||
|
||||
1. Start the Player2 Speech service and confirm that the health check is available.
|
||||
2. AIRI connects to `http://localhost:4315/v1/` by default; if the service runs at another address, please record the complete Base URL.
|
||||
|
||||
::: warning Local service security
|
||||
Do not expose local service ports to untrusted public networks.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Player2**.
|
||||
2. Enter the service's Base URL.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available voice in the provider playground. This page uses AIRI's default Player2 model.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Player2**, then choose an available model and voice. The provider test alone does not enable speech for normal replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When the connection fails, check the service's `/health` response and Base URL. When the voice list is empty, confirm that the `/tts/voices` interface of the service is accessible.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Volcano Engine (TTS)
|
||||
description: Configuring Volcano Engine speech synthesis in AIRI
|
||||
---
|
||||
|
||||
Volcengine speech synthesis requires an API Key and application information in AIRI.
|
||||
|
||||
::: info Why choose Volcengine?
|
||||
If you have created a voice application and managed voice resources in Volcengine, you can reuse those settings in AIRI.
|
||||
:::
|
||||
|
||||
## Prepare application credentials
|
||||
|
||||
1. Log in to the [Volcengine Speech console](https://console.volcengine.com/speech/app), then create or open a speech application.
|
||||
2. Copy the **App ID** of the application and create the corresponding **API Key**.
|
||||
3. Confirm that both pieces of information come from the same account and application configuration.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key or App ID, include either one in screenshots, or share them with anyone. Once either the key or ID is compromised, immediately revoke it and create a new key in the Volcengine console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Speech → Volcano Engine**.
|
||||
2. Enter the API key and App ID. The default Base URL is the AIRI/UnSpeech gateway at `https://unspeech.hyp3r.link/v1/`, not Volcengine's direct API. Your credentials, text to synthesize, model/voice selection, and returned audio pass through this gateway. Use it only if you accept that trust boundary; otherwise enter a compatible self-hosted gateway URL or choose a direct provider.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available voice in the provider playground. This page uses AIRI's default Volcengine speech model.
|
||||
2. Use the playground on the same page to enter a short text and confirm that audio plays.
|
||||
|
||||
## Enable for AIRI replies
|
||||
|
||||
Open **Settings → Modules → Speech**, select **Volcano Engine**, then select an available model and voice. The provider playground tests credentials; this module selection enables speech for normal AIRI replies.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
When verification fails, check whether the App ID and API Key are from the same application. When there is no sound, make sure the app has enabled speech synthesis and selected a voice.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Aliyun NLS
|
||||
description: Configure Alibaba Cloud Intelligent Voice Interaction Service (ASR) in AIRI
|
||||
---
|
||||
|
||||
Alibaba Cloud NLS provides AIRI with real-time speech-to-text (ASR). After completing the configuration, select **Aliyun NLS** under **Settings → Modules → Hearing** and test the microphone input.
|
||||
|
||||
::: info Why choose Alibaba Cloud NLS?
|
||||
If you already use an Alibaba Cloud account and need real-time speech recognition capabilities, you can choose Alibaba Cloud NLS.
|
||||
:::
|
||||
|
||||
## Prepare credentials
|
||||
|
||||
1. In [Alibaba Cloud Intelligent Voice Interaction Console](https://nls-portal.console.aliyun.com/overview) enable the service, create a project, and copy its **AppKey**.
|
||||
2. Create a RAM user AccessKey with the required permissions in **AccessKey Management**.
|
||||
3. Copy **AccessKey ID** and **AccessKey Secret**; the Secret will usually only be displayed in full once.
|
||||
|
||||
::: warning AccessKey Security
|
||||
Do not commit the AccessKey ID, AccessKey Secret, or AppKey, include them in screenshots, or share them with anyone. Grant the RAM user only the required permissions. If credentials are exposed, disable them and create replacements in the Alibaba Cloud console immediately.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Transcription → Aliyun NLS**.
|
||||
2. Fill in the **AccessKey ID**, **AccessKey Secret** and **AppKey**.
|
||||
3. Select the area closest to you, such as East China `cn-shanghai`, North China `cn-beijing` or South China `cn-shenzhen`.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. The confirmation page prompts that the basic credentials verification has passed.
|
||||
2. Select **Aliyun NLS** and an audio input device under **Settings → Modules → Hearing**.
|
||||
3. Click "Start Monitoring" and then speak into the microphone or play an audio clip.
|
||||
4. Confirm that the text can be output in real time in the transcription area; if the recognition result is inaccurate, you can adjust the sensitivity and test again.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If credential verification fails, confirm that all three credentials come from the same Alibaba Cloud account and project, then check the RAM user permissions. If no text appears, confirm that the operating system has granted AIRI microphone access.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Browser local speech recognition (ASR/STT, unavailable)
|
||||
description: Browser local speech recognition is not configurable yet
|
||||
---
|
||||
|
||||
Browser (Local) speech recognition is not available yet. Its AIRI settings page currently shows a Work in Progress placeholder, so models cannot be prepared or enabled.
|
||||
|
||||
::: warning Unavailable
|
||||
Do not use this provider for a working setup yet. It is documented here only so that the current availability is clear.
|
||||
:::
|
||||
|
||||
## Use an available alternative
|
||||
|
||||
Use the [Web Speech API](./web-speech-api.md) in supported browsers, or choose a supported cloud transcription provider.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: CometAPI (ASR/STT)
|
||||
description: Configuring CometAPI speech recognition in AIRI
|
||||
---
|
||||
|
||||
CometAPI provides audio transcription through its compatible interface.
|
||||
|
||||
::: info Why choose CometAPI?
|
||||
If you have used CometAPI to manage models and credentials, you can directly reuse the same API Key in AIRI for speech recognition.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [CometAPI Console](https://www.cometapi.com/console/token), then create an API key.
|
||||
2. Confirm that the account can access an audio-transcription model, then copy the key and store it securely.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Transcription → Comet API** and fill in the API Key.
|
||||
2. Keep the default Base URL: `https://api.cometapi.com/v1/`; modify it only when using a proxy or compatible gateway.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available transcription model in the provider settings.
|
||||
2. Use the playground on the same page, allow microphone access, and record a short sample to confirm that text is returned.
|
||||
|
||||
## Enable microphone transcription
|
||||
|
||||
Open **Settings → Modules → Hearing**, select **Comet API** and an available model, then choose a microphone and run the Hearing test. Testing the provider page alone does not enable microphone transcription.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the playground cannot complete a request, check the API Key, account permissions, and network connection. If no text appears, confirm that AIRI has microphone access.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Desktop local speech recognition (ASR/STT, unavailable)
|
||||
description: Desktop local speech recognition is not configurable yet
|
||||
---
|
||||
|
||||
App (Local) speech recognition is not available yet. Its AIRI settings page currently shows a Work in Progress placeholder, so models cannot be prepared or enabled.
|
||||
|
||||
::: warning Unavailable
|
||||
Do not use this provider for a working setup yet. It is documented here only so that the current availability is clear.
|
||||
:::
|
||||
|
||||
## Use an available alternative
|
||||
|
||||
Use the [Web Speech API](./web-speech-api.md) in supported browsers, or choose a supported cloud transcription provider.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Xiaomi MiMo (ASR/STT)
|
||||
description: Configuring Xiaomi MiMo Voice Recognition in AIRI
|
||||
---
|
||||
|
||||
MiMo uses its native audio understanding model to complete speech transcription.
|
||||
|
||||
::: info Why choose Xiaomi MiMo?
|
||||
If you already use MiMo, or want to use its multimodal model to process audio content, you can choose this service provider.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to [Xiaomi MiMo Platform](https://platform.xiaomimimo.com/), then confirm that the account has API access enabled.
|
||||
2. Create an API Key, copy it and keep it in a safe place.
|
||||
|
||||
::: warning API Key and audio data
|
||||
Do not expose the API Key. Cloud transcription sends audio to the provider for processing, so confirm that this meets your privacy and data-handling requirements.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Fill in the API Key in **Settings → Providers → Transcription → Xiaomi MiMo**.
|
||||
2. Keep the default Base URL: `https://api.xiaomimimo.com/v1/`, unless the service provider provides another address.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select an available transcription model in the provider settings.
|
||||
2. Use the playground on the same page, allow microphone access, and record a short sample to confirm that text is returned.
|
||||
|
||||
## Enable microphone transcription
|
||||
|
||||
Open **Settings → Modules → Hearing**, select **Xiaomi MiMo**, choose model ID `mimo-v2-omni`, then choose a microphone and run the Hearing test. Testing the provider page alone does not enable microphone transcription.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If a request fails, check the API key, model selection, and network connection. If no text is returned, confirm that AIRI has microphone permission.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Official Transcription Provider (ASR/STT)
|
||||
description: Use official real-time speech recognition in AIRI
|
||||
---
|
||||
|
||||
Official transcription uses your current AIRI session; no third-party API Key is required.
|
||||
|
||||
::: info Why choose AIRI official speech recognition?
|
||||
If you already use the official AIRI provider and want to quickly enable real-time voice input, you can try this option first.
|
||||
:::
|
||||
|
||||
## Log in to your account
|
||||
|
||||
1. Sign in with an AIRI account.
|
||||
2. Confirm that the official transcription provider is available for the current session.
|
||||
|
||||
::: warning Account and audio data
|
||||
Real-time recognition will send the audio to the official service. Don't use test audio that contains sensitive information, and don't share account session information.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Transcription → Official Transcription Provider**.
|
||||
2. Confirm that the provider page is available for the signed-in account. This page does not contain the active model selector.
|
||||
3. Open **Settings → Modules → Hearing**, select **Official Transcription Provider**, and select **Auto**. The current provider exposes only the `Auto` model.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Allow AIRI to use the microphone and perform a short voice input.
|
||||
2. If the transcription appears, the provider is configured correctly.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the model is unavailable, confirm that you are signed in, AIRI can reach the service, and the account has available credit. If no transcription appears, check the operating system's microphone permission for AIRI.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: OpenAI compatible API (ASR/STT)
|
||||
description: Configuring OpenAI or an OpenAI-compatible API as a speech recognition provider in AIRI
|
||||
---
|
||||
|
||||
This page configures an OpenAI-compatible transcription API. After saving it, select the provider and model under **Settings → Modules → Hearing** and test microphone input.
|
||||
|
||||
::: info Why use an OpenAI-compatible API for ASR/STT?
|
||||
If your transcription provider implements the OpenAI transcription API, follow this guide to connect it to AIRI. An API address ending with `/v1` or a key starting with `sk-` does not by itself guarantee compatibility.
|
||||
:::
|
||||
|
||||
## Obtain API Key
|
||||
|
||||
1. Log in to the management console of the selected service provider.
|
||||
2. Create an API Key on the API Key or Developer Settings page.
|
||||
3. Copy the key and keep it in a safe place.
|
||||
|
||||
::: warning API Key Security
|
||||
Do not commit the API key, include it in screenshots, or share it with anyone. Once a key is compromised, immediately revoke it and create a new key in the provider console.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Transcription → OpenAI Compatible**.
|
||||
2. Fill in the API Key and the ASR/STT model ID to be used.
|
||||
3. For official OpenAI, select the separate **OpenAI** provider. The **OpenAI Compatible** provider has no default Base URL; enter the complete API root documented by the compatible service.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Select the configured service provider and model in **Settings → Modules → Hearing**, then select the audio input device.
|
||||
2. Click **Start Monitoring**, then speak into the microphone or play an audio clip.
|
||||
3. Confirm that text appears in the transcription area. If recognition is inaccurate, adjust the sensitivity and test again.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If there is no text result, confirm that AIRI has microphone permission. For a compatible service, verify that it implements the OpenAI transcription API and supports the entered model ID.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Browser Web Speech API (ASR/STT)
|
||||
description: Using in-browser speech recognition with AIRI Web
|
||||
---
|
||||
|
||||
The Web Speech API uses the browser's built-in speech-recognition capability and does not require an API key.
|
||||
|
||||
::: info Why choose Web Speech API?
|
||||
If you're just trying out speech input quickly on the web, and your browser supports the Web Speech API, this is the minimal configuration option.
|
||||
:::
|
||||
|
||||
## Confirm browser support
|
||||
|
||||
1. Use AIRI Web. The Web Speech API provider is not available in the Desktop ver. (Electron).
|
||||
2. Confirm that the current browser supports the Web Speech API and is ready to allow microphone permissions.
|
||||
|
||||
::: warning Browser restrictions
|
||||
The Web Speech API is only available in browser environments and is not supported by the desktop version of AIRI (Electron). Recognition capabilities may vary across browsers, network environments and languages.
|
||||
:::
|
||||
|
||||
## Configure in AIRI
|
||||
|
||||
1. Open **Settings → Providers → Transcription → Web Speech API** in the web version.
|
||||
2. Select **Recognition Language**, then configure **Continuous Recognition** and **Show Interim Results** as needed.
|
||||
|
||||
## Verify configuration
|
||||
|
||||
1. Go to **Settings → Modules → Hearing** and select Web Speech API and Audio Input Device.
|
||||
2. Allow the browser to access the microphone and start a short voice input test.
|
||||
3. Confirm that the transcription appears in AIRI.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If no transcription appears, check the browser's microphone permission, the selected input device, and the recognition language. If your browser does not support this API, use a local or cloud transcription provider instead.
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Configure vision
|
||||
description: Select an image-understanding provider and model for AIRI's vision module
|
||||
---
|
||||
|
||||
The vision module sends captured images to a model that supports image input. Vision providers use the same kinds of fields as their chat counterparts, but AIRI stores their settings separately. Enter the credentials again on the Vision provider page.
|
||||
|
||||
::: info Why do the fields look the same?
|
||||
The same service often provides both chat and image-understanding models, so the forms use matching fields. The saved values are independent, and you must still choose a model that explicitly supports image input.
|
||||
:::
|
||||
|
||||
::: warning Before using screen vision, you need to enable Vision Capture
|
||||
When configuring only the vision service provider and model, there is no need to enable this tool.
|
||||
|
||||
To have AIRI analyze your screen or window, open **System → Developer → Vision Capture**, grant screen-recording permission if needed, select a window or display, and click **Start ticker**. To send the results to the current character, enable **Publish to character**.
|
||||
|
||||
Vision Capture is the current desktop debugging/development workflow; leaving the page will stop the capture loop. For complete instructions, see [Desktop Developer Tools](/en/docs/contributing/desktop-developer-tools#vision-capture).
|
||||
:::
|
||||
|
||||
## Choose a vision provider
|
||||
|
||||
1. Open **Settings → Providers → Vision**.
|
||||
2. Select the vision provider you want to configure.
|
||||
3. Enter the credentials on this page. The fields match the chat-provider version, such as API Key, Base URL, Azure resource information, or AWS Region, but the saved values are separate.
|
||||
|
||||
You can enter the same account credentials in both Chat and Vision when appropriate. Saving the credentials in chat providers does not autofill credentials in vision providers.
|
||||
|
||||
::: warning Image and Credential Security
|
||||
Visual analysis sends captured frames to the selected provider. Do not capture API keys, passwords, personal information, or content you are not authorized to share. Never commit, screenshot, or share cloud credentials.
|
||||
:::
|
||||
|
||||
## Select a vision model
|
||||
|
||||
1. Open **Settings → Modules → Vision**.
|
||||
2. Select the provider you just configured.
|
||||
3. Select a model that supports image input.
|
||||
4. Set **Capture interval** to control how frequently the vision ticker captures a frame.
|
||||
|
||||
On desktop, the current screen or window source is selected separately under **System → Developer → Vision Capture**, as described above.
|
||||
|
||||
## Verify the configuration
|
||||
|
||||
1. Capture a window that does not contain sensitive information.
|
||||
2. Trigger a visual analysis.
|
||||
3. Confirm that AIRI receives a description or other context from the captured frame.
|
||||
|
||||
## Local visual model
|
||||
|
||||
Ollama and LM Studio are available as local vision providers. Run a model that supports image input and confirm that AIRI can reach its service. Then enter or keep the corresponding Base URL on the Vision provider page and select the model under **Settings → Modules → Vision**.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
| --- | --- |
|
||||
| The provider does not validate | Complete the required Vision fields, such as API Key, Azure Resource Name, or AWS Region, even if the Chat provider is already configured. |
|
||||
| The model cannot analyze the image | Confirm that the model explicitly supports image input and select a compatible vision model. |
|
||||
| The local model is unreachable | Check that the local service is running and that the Base URL, port, CORS, and LAN-access settings are correct. |
|
||||
| The request is rejected or quota is exhausted | Check account permissions, API Key, regional model availability, quota, and network access. |
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Configure web search
|
||||
description: Use Tavily to let AIRI find current information during conversations
|
||||
---
|
||||
|
||||
Web Search lets AIRI query the internet for current or unfamiliar information. It uses your Tavily API Key. When the tool is enabled and the selected chat model supports tool calls, AIRI can search during a conversation and cite the returned sources.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- AIRI is installed and running.
|
||||
- You have a Tavily account and an API key from the [Tavily](https://tavily.com/) console.
|
||||
- The selected chat provider and model support tool calling.
|
||||
|
||||
::: warning API Key Security
|
||||
Tavily API Key should only be saved on the current device. Do not submit to the repository, send to others, or include in character cards, journals, and screenshots. If you suspect a key has been compromised, immediately revoke it and create a new key in the Tavily console.
|
||||
:::
|
||||
|
||||
## Configuration steps
|
||||
|
||||
1. Open **Settings → Modules → Web Search**.
|
||||
2. Turn on **Enable Web Search**.
|
||||
3. Paste the API key in **Tavily API Key**.
|
||||
4. When **Web search is ready to use!** appears, you can return to the chat. The settings are saved automatically; there is no separate save button.
|
||||
|
||||
After turning off the switch or clearing the API Key, AIRI will no longer send search requests to Tavily.
|
||||
|
||||
## When will AIRI search?
|
||||
|
||||
AIRI may search when you ask it to or when a question requires current information, such as news, prices, recent releases, live data, or updated documentation.
|
||||
|
||||
For more focused results, state the goal and scope explicitly:
|
||||
|
||||
- "Search for the release notes for the latest stable version of AIRI and attach a link."
|
||||
- "Find instructions about API Keys in Tavily's official documentation."
|
||||
- "Search only the most recent week of updates on `github.com/moeru-ai/airi`."
|
||||
|
||||
Search results include source links. If the available results are insufficient, AIRI should search further or clearly state the uncertainty.
|
||||
|
||||
## Privacy, Reliability and Security
|
||||
|
||||
Each search sends the query text to Tavily. Do not include API keys, passwords, access tokens, private addresses, or other sensitive information. Search results may be incorrect, outdated, or biased.
|
||||
|
||||
::: warning Please verify important information
|
||||
Search results are provided to AIRI as reference material only and do not change your original request. For medical, legal, or financial information, review the linked sources yourself and consult official guidance or a qualified professional.
|
||||
:::
|
||||
|
||||
## FAQ
|
||||
|
||||
### Tavily shows configured, but AIRI does not search
|
||||
|
||||
Confirm that **Enable Web Search** is on and that the selected chat model supports tool calls. Then ask AIRI to “search and include source links.” If it still does not search, check the provider's tool-calling support.
|
||||
|
||||
### Got API Key, permission or quota error
|
||||
|
||||
Return to the Tavily console to confirm that the key is correct and still valid, and check the account's available credit or access rights. Do not include leading or trailing spaces or line breaks when copying. If you changed the key, paste the new key into AIRI.
|
||||
|
||||
### Search results are inaccurate or not current enough
|
||||
|
||||
State the time frame, location, and preferred sources, such as “only check the past week” or “use only official documentation.” Open the cited links to verify important information; search results are not a substitute for professional advice or independent judgment.
|
||||
@@ -1,17 +1,48 @@
|
||||
---
|
||||
title: Character Card Template
|
||||
description: A Character Card V3 JSON template for Project AIRI.
|
||||
description: Character Card V3 card.json template for an AIRI Card package
|
||||
---
|
||||
|
||||
This template gives you a minimal Character Card V3 structure for creating a new AIRI character. Copy the JSON below, replace the example values with your own character settings, and keep the field names and nesting unchanged.
|
||||
This is a minimal Character Card V3 template for the `card.json` file inside an AIRI Card package. Replace the example content with your own character details while keeping the field names and hierarchy unchanged.
|
||||
|
||||
::: tip Editing tips
|
||||
- Start with `name`, `description`, `personality`, `scenario`, and `first_mes`.
|
||||
- Keep optional fields empty when you do not need them yet.
|
||||
- Make sure the final content is still valid JSON before importing or sharing it.
|
||||
::: warning The JSON file cannot be imported by itself
|
||||
The current AIRI Card upload control accepts a `.zip` package containing both `manifest.json` and `card.json` at its root. Saving only the JSON shown below and uploading it directly will fail.
|
||||
:::
|
||||
|
||||
## Template
|
||||
::: tip Editing tips
|
||||
- You can fill in `name`, `description`, `personality`, `scenario` and `first_mes` first.
|
||||
- Leave unused optional fields blank.
|
||||
- Before packaging or sharing, confirm that the final content is valid JSON.
|
||||
:::
|
||||
|
||||
## Package structure
|
||||
|
||||
```text
|
||||
my-airi-card.zip
|
||||
├── manifest.json
|
||||
└── card.json
|
||||
```
|
||||
|
||||
Use this minimal `manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"format": "airi-character-card",
|
||||
"version": 1,
|
||||
"card": {
|
||||
"path": "card.json",
|
||||
"spec": "chara_card_v3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
An AIRI-exported package may also contain a supported display model under `models/` and describe it in `manifest.json`. The two-file structure above is sufficient for a card without a bundled display model.
|
||||
|
||||
::: warning AIRI Card packages are not lossless CCv3 backups
|
||||
AIRI imports an explicit whitelist of character fields and AIRI module settings. It preserves the fields shown in the template below, but discards unsupported CCv3 metadata such as `group_only_greetings`, `mes_example`, `creator`, and `tags`. Third-party extensions and unsupported fields inside `extensions.airi` are also removed. Keep a separate copy of the original card if you need a lossless backup.
|
||||
:::
|
||||
|
||||
## `card.json` template
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -21,18 +52,14 @@ This template gives you a minimal Character Card V3 structure for creating a new
|
||||
"name": "Example Character",
|
||||
"nickname": "Example",
|
||||
"description": "A short description of who this character is.",
|
||||
"personality": "Curious, warm, and playful.",
|
||||
"scenario": "The character is meeting the user for the first time.",
|
||||
"first_mes": "Hello! I'm happy to meet you.",
|
||||
"personality": "Curious, warm, and a little playful.",
|
||||
"scenario": "This character is meeting the user for the first time.",
|
||||
"first_mes": "Hello! Nice to meet you.",
|
||||
"alternate_greetings": [],
|
||||
"group_only_greetings": [],
|
||||
"mes_example": "",
|
||||
"creator": "Your name",
|
||||
"creator_notes": "",
|
||||
"character_version": "1.0.0",
|
||||
"system_prompt": "",
|
||||
"post_history_instructions": "",
|
||||
"tags": ["example"],
|
||||
"extensions": {}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,22 +1,22 @@
|
||||
---
|
||||
title: Desktop Quick Start
|
||||
description: How to start using Project AIRI on desktop
|
||||
description: How to get started with the Desktop ver.
|
||||
---
|
||||
|
||||
## Start Chatting
|
||||
## Start chatting first
|
||||
|
||||
After installing and launching AIRI, the quickest way to start a conversation is to complete the onboarding flow:
|
||||
After installing and starting AIRI, complete the onboarding flow:
|
||||
|
||||
1. Select your language if AIRI asks for it.
|
||||
2. Choose **setup with your provider**, or sign in if you already use an AIRI account.
|
||||
3. Pick a chat provider, such as OpenRouter, OpenAI Compatible API, DeepSeek, Ollama, Qwen, Gemini, or Claude.
|
||||
4. Enter the required API key or local endpoint information.
|
||||
5. Choose a chat model, then save and continue.
|
||||
6. On the main character window, click the bottom-right **Expand** button in the Controls Island.
|
||||
7. Click **Open Chat**, type a message, and send it.
|
||||
1. On the welcome screen, optionally click the <span class="i-lucide:globe inline-block align-[-0.125em]" aria-hidden="true"></span> **globe button** in the upper-right corner to change the interface language.
|
||||
2. Select **Setup with your provider**, or select **Sign in** to use the official AIRI provider.
|
||||
3. Select a Chat provider such as OpenRouter, OpenAI Compatible, DeepSeek, Ollama, Google Gemini, or Anthropic.
|
||||
4. Fill in the API Key, local service address and other necessary information.
|
||||
5. Select a chat model, then select **Save and Continue**.
|
||||
6. After returning to the main character window, click **Expand** in the Controls Island in the lower-right corner.
|
||||
7. Click **Open Chat**, enter the message and send it.
|
||||
|
||||
::: tip Using Ollama locally?
|
||||
Set `OLLAMA_ORIGINS=*` as a system environment variable, then restart Ollama before selecting it in AIRI.
|
||||
By default, Ollama allows requests from the development and packaged-app origins of the Desktop ver. Thus, a local setup does not usually require `OLLAMA_ORIGINS`. If a CORS error occurs from a non-default remote web origin, add that exact origin to `OLLAMA_ORIGINS`. Then restart Ollama. Do not use a wildcard or expose Ollama to the public internet.
|
||||
:::
|
||||
|
||||
<br />
|
||||
@@ -25,41 +25,41 @@ Set `OLLAMA_ORIGINS=*` as a system environment variable, then restart Ollama bef
|
||||
<source src="/assets/tutorial-basic-setup-providers.mp4" type="video/mp4">
|
||||
</video>
|
||||
|
||||
## What Is On Screen
|
||||
## What will you see
|
||||
|
||||
The desktop version, also called Stage Tamagotchi, usually has these surfaces:
|
||||
The Desktop ver. usually consists of these interfaces:
|
||||
|
||||
- **Main character window**: the always-on-desktop Live2D / VRM stage.
|
||||
- **Controls Island**: the small button group at the bottom-right of the character window.
|
||||
- **Chat window**: the conversation window opened from Controls Island.
|
||||
- **Settings window**: provider, character, model, module, data, connection, and system settings.
|
||||
- **System tray menu**: size, alignment, settings, caption, widgets, and quit actions.
|
||||
- **Main Character Window**: A desktop-resident character stage supporting Live2D, Spine, VRM, MMD, and Tachie.
|
||||
- **Controls Island**: A small group of buttons in the lower-right corner of the main character window.
|
||||
- **Chat Window**: A conversation window opened from the Controls Island.
|
||||
- **Settings Window**: Configure providers, profiles, models, modules, data, connections, and system options.
|
||||
- **System Tray Menu**: Adjust the window size and position, open settings, manage captions and widgets, or quit AIRI.
|
||||
|
||||
If the character window is hidden, you can bring it back by clicking the AIRI tray icon or choosing **Show** from the tray menu.
|
||||
If the main character window is hidden, you can bring it back by clicking on the AIRI tray icon or selecting **Show** in the tray menu.
|
||||
|
||||
## Controls Island
|
||||
|
||||
The Controls Island is the most convenient place to operate the desktop app during everyday use.
|
||||
The Controls Island is the main entry point for everyday use of the desktop app.
|
||||
|
||||
- Click **Expand** to reveal more actions.
|
||||
- Click **Expand** to show more actions.
|
||||
- Click **Open Chat** to open the chat window.
|
||||
- Click **Open Settings** to configure providers, models, modules, characters, and system settings.
|
||||
- Click **Switch Profile** to change the active character card.
|
||||
- Click **Refresh** when the stage needs to reload.
|
||||
- Click the light/dark icon to switch theme.
|
||||
- Click the pin icon to toggle always-on-top.
|
||||
- Click **Open settings** to configure providers, models, modules, profiles, and system settings.
|
||||
- Click **Switch Profile** to change the current character card.
|
||||
- If needed, you can click **Refresh** to reload the stage.
|
||||
- Click the light/dark icon to switch themes.
|
||||
- Click the pushpin icon to toggle **Pin on top**.
|
||||
- Click the eye icon to toggle **Auto hide** / **Always show**.
|
||||
- Use the microphone button to open hearing controls.
|
||||
- Drag the move button to reposition the character window.
|
||||
- Click **Open hearing Controls** to open voice-input controls.
|
||||
- Drag **Drag to move window** to move the main character window.
|
||||
|
||||
## Auto Hide
|
||||
## Hide on hover
|
||||
|
||||
The eye button controls whether AIRI should stay fully interactive or gently reduce visual and click interference while you work.
|
||||
The eye icon controls whether AIRI remains fully interactive or fades out of the way to reduce obstruction while you work.
|
||||
|
||||
- **Always show** keeps the character visible and clickable.
|
||||
- **Auto hide** fades the character and UI when your cursor is nearby, then lets clicks pass through to the app underneath.
|
||||
- **Auto hide** fades the character and interface when the cursor is close, making it easier to click the application below.
|
||||
|
||||
The first time you enable Auto hide, AIRI shows a short notice explaining the behavior. If AIRI becomes hard to click, move the cursor near the Controls Island and click the eye button again.
|
||||
When you first enable hide on hover, AIRI displays a short explanation. If it becomes difficult to click AIRI, move the cursor near the Controls Island and click the eye icon again to switch it off.
|
||||
|
||||
<div rounded-lg overflow-hidden>
|
||||
<video autoplay loop muted class="scale-180 translate-x--30 translate-y--2 lg:scale-150 lg:translate-x--40">
|
||||
@@ -67,9 +67,9 @@ The first time you enable Auto hide, AIRI shows a short notice explaining the be
|
||||
</video>
|
||||
</div>
|
||||
|
||||
## Move And Resize
|
||||
## Move and resize
|
||||
|
||||
To move the character window, drag the move button at the bottom-right of the Controls Island.
|
||||
To move the main character window, drag the move button in the lower-right corner of the Controls Island.
|
||||
|
||||
<div rounded-lg overflow-hidden>
|
||||
<video autoplay loop muted class="scale-225 translate-x--45 translate-y--5 lg:scale-200 lg:translate-x--80 lg:translate-y--5">
|
||||
@@ -77,13 +77,13 @@ To move the character window, drag the move button at the bottom-right of the Co
|
||||
</video>
|
||||
</div>
|
||||
|
||||
On Windows, you can resize the character window by dragging the window edges or corners. The tray menu also provides a few quick presets:
|
||||
On Windows, you can drag the edges or corners of a window to resize it. Several common sizes are also provided in the tray menu:
|
||||
|
||||
1. Right-click the AIRI tray icon.
|
||||
2. Open **Adjust sizes**.
|
||||
3. Choose **Recommended**, **Full Height**, **Half Height**, or **Full Screen**.
|
||||
3. Select **Recommended (450x600)**, **Full Height**, **Half Height**, or **Full Screen**.
|
||||
|
||||
You can use **Align to** in the same tray menu to place the window at the center or a screen corner.
|
||||
**Align to** in the same tray menu can move the window to the center or four corners of the screen.
|
||||
|
||||
<div rounded-lg overflow-hidden>
|
||||
<video autoplay loop muted class="scale-160 translate-x--20 lg:scale-150 lg:translate-x--40 lg:translate-y-10">
|
||||
@@ -91,14 +91,14 @@ You can use **Align to** in the same tray menu to place the window at the center
|
||||
</video>
|
||||
</div>
|
||||
|
||||
## Settings Worth Checking
|
||||
## Recommended settings to review
|
||||
|
||||
These pages are useful to check after the first chat works:
|
||||
After your first chat, review these pages:
|
||||
|
||||
- **Service Sources**: add or edit Chat, Speech, Transcription, and Artistry providers.
|
||||
- **Body Modules**: choose which providers AIRI uses for consciousness, voice, hearing, vision, memory, Discord, Minecraft, Factorio, MCP, and other modules.
|
||||
- **Character Model**: switch between Live2D and VRM models, or import your own model.
|
||||
- **AIRI Character Card**: change the active character or create a new one.
|
||||
- **System**: set language, theme, analytics preference, and desktop-specific options.
|
||||
- **Providers**: Add or edit Chat, Vision, Speech, Transcription, and Artistry providers.
|
||||
- **Modules**: Select services for consciousness, speech, hearing, vision, memory, Discord, Minecraft, Factorio, MCP, and other modules.
|
||||
- **Models**: Switch between supported 2D/3D models, or import your own.
|
||||
- **AIRI Card**: Switch the current character, or create a new character card.
|
||||
- **System**: Set the language, theme, usage-analytics settings, and desktop-specific options.
|
||||
|
||||
Some modules are still experimental and may require local source setup or external services. For a more detailed Windows-focused walkthrough, see the [full desktop manual](./setup-and-use/).
|
||||
Some modules are experimental and require local source configuration or additional services. See the [complete desktop manual](./setup-and-use/) for detailed instructions.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 37 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 2.3 KiB After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 38 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 42 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user