Wi-Fi API

Run voice generation, transcription, and chat on a computer on your private Wi-Fi network.

1. Install Node.js 20 or newer from nodejs.org.
2. Download and extract the local REST/JSON API server.
3. In the extracted folder, run node companion.mjs.
4. Open http://127.0.0.1:4175/ on the host computer and keep the studio open.
5. In Device & Wi-Fi, select a private network address and choose Start API. Use the displayed address and token.
6. Choose Stop API to close client connections and invalidate the token. Closing the studio stops the API after its two-minute heartbeat timeout.

The API starts off. Use a trusted private network: LAN traffic uses HTTP and is not encrypted. Anyone with the current token can submit requests. Do not forward the API port to the public internet.

Connection and authentication

Send requests from a command line or a native app using the exact IP address shown in the studio. Every endpoint, including /health, requires the current bearer token.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Browser-based cross-origin requests are rejected. This also means a hosted Swagger UI cannot call the API. The downloadable OpenAPI description works with tools that import OpenAPI, and the examples below are ready to copy into a local client.

Download OpenAPI 3.1 JSON

Check the host

curl 'http://YOUR_WIFI_IP:4177/health' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example response:

{
  "ready": true,
  "pending": 0
}

Chat

curl 'http://YOUR_WIFI_IP:4177/api/chat' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Write a friendly welcome."}]}'

Request JSON:

{
  "messages": [
    { "role": "user", "content": "Write a friendly welcome." }
  ]
}

Example response JSON:

{
  "text": "Welcome! We’re glad you’re here.",
  "inputTokens": 42,
  "outputTokens": 9
}

Send 1–100 messages. ChatCraft uses only the latest user message; earlier turns are ignored and never sent as chat history. The response reports the model token counts for its input and output. Chats are not saved.

Transcribe audio

curl 'http://YOUR_WIFI_IP:4177/api/transcribe' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-binary @transcribe-request.json

Save this request as transcribe-request.json, replacing the example string with the audio file’s Base64 data:

{
  "audioBase64": "REPLACE_WITH_BASE64_ENCODED_AUDIO",
  "model": "tiny",
  "language": "en"
}

On macOS or Linux, create that JSON from a local audio file with Python 3:

python3 -c 'import base64,json,pathlib; p=pathlib.Path("input.wav"); print(json.dumps({"audioBase64":base64.b64encode(p.read_bytes()).decode(),"model":"tiny","language":"en"}))' > transcribe-request.json

Example response JSON:

{
  "text": "សួស្តី។",
  "segments": [
    { "text": "សួស្តី។", "start": 0.1, "end": 0.9 }
  ]
}

Supported model values are tiny, base, and edge. Transcription supports English (en) and Chinese (zh); the default is English. Audio files up to 100 MB are supported. Base64 expands the request, so the API accepts a larger JSON body for this endpoint.

Generate speech

curl 'http://YOUR_WIFI_IP:4177/api/speech' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"text":"សួស្តី!","mode":"read","referenceBase64":"REPLACE_WITH_MANON_FLOAT32_BASE64","steps":10,"seed":42}'

Request JSON:

{
  "text": "សួស្តី!",
  "mode": "read",
  "referenceBase64": "REPLACE_WITH_MANON_FLOAT32_BASE64",
  "cfg": 2,
  "steps": 10,
  "seed": 42
}

Speech is generated as one take. The loaded model tokenizer counts the text and speaker features against the 512-token take budget; a long speaker reference leaves less room for text.

Example response JSON:

{
  "audioBase64": "BASE64_ENCODED_WAV_DATA",
  "subtitleBase64": "BASE64_ENCODED_SRT_DATA",
  "mimeType": "audio/wav",
  "sampleRate": 48000
}

For mode: "read", provide the saved Manon speaker in referenceBase64. For mode: "clone", provide a 3–20 second voice sample and set rightsConfirmed to true. The API supports Manon default voice and permission-confirmed speaker recordings. Only use recordings you own or have permission to use; get consent before cloning another person’s voice.

Limits and errors

One model task runs at a time; up to three requests can wait in the queue. A full queue returns 429, invalid or missing token returns 401, unavailable studio returns 503, and request processing times out after ten minutes. Responses use JSON, including errors as {"error":"…"}. The host browser performs inference; requests are not relayed to a cloud service or stored by the local API server.

Privacy and offload

The local API server binds the API only to the selected private IPv4 address and creates a new token each time it starts. Model processing stays on the host computer. When another VoxCraft device uses Offload, its chat prompts, selected audio, voice settings, and any supplied reference sample are sent to the chosen host to run its local models.

ការប្រើ API តាម Wi-Fi