Verification & Testing

After deploying your self-hosted engine, follow these steps to verify that it works correctly. The recommended approach is to first validate your integration against the Hiya cloud API, then deploy self-hosted, and finally re-run the same tests against your local endpoint.

1

Test against the Hiya cloud API

Before deploying self-hosted, confirm that your integration works against the Hiya cloud API using the open-source streaming verification example.

Clone the repository and install dependencies:

git clone https://github.com/loccus-ai/examples.git
cd examples/streaming-verification
npm install

Run a verification against the cloud API:

node verify.mjs \
  --target upstream \
  --audio path/to/audio.wav \
  --token <HIYA_API_TOKEN> \
  --region <REGION> \
  --owner <OWNER> \
  --space <SPACE>

You can also set the credentials as environment variables (HIYA_API_TOKEN, HIYA_REGION, HIYA_OWNER, HIYA_SPACE) instead of passing them as flags.

The script connects to wss://api.hiya.com/audiointel/{region}/v1/spaces/{owner}/{space}/verify/authenticity, streams the audio file in 16 KB chunks over WebSocket, and prints per-chunk results as they arrive followed by a final verification summary with latency metrics.

A successful run exits with code 0 and prints a result containing the model version, score, and subscores for synthesis and replay detection.

Save the output from this step — you will compare it against the self-hosted results in step 4 to confirm both environments produce consistent scores.

2

Deploy the self-hosted engine

Follow the deployment guide for your platform:

• Docker (Single Host)
• Kubernetes
• AWS EKS / AWS ECS
• GCP GKE / GCP Cloud Run
• Azure AKS

Make sure to set the required runtime environment variables (API_KEY, ORG_HANDLE, PLATFORM_REGION, and MIN_ALLOCATION) and mount the tmpfs volume as described in your chosen guide.

3

Verify that the containers are up

Confirm the engine is healthy by querying the gRPC health check endpoint on port 8080:

grpcurl -plaintext <engine-host>:8080 grpc.health.v1.Health/Check

Expected output:

{
  "status": "SERVING"
}

Then verify the WebSocket API on port 8081 is accepting connections:

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  http://<engine-host>:8081/v1/verify/authenticity

A successful response includes HTTP/1.1 101 Switching Protocols, confirming the WebSocket endpoint is reachable.

The startup probe gives the engine up to 30 seconds to load its models. If the health check returns NOT_SERVING, wait and retry.

4

Test against the self-hosted endpoint

Using the same testing script from step 1, point it at your self-hosted engine instead of the cloud API:

node verify.mjs \
  --target local \
  --audio path/to/audio.wav \
  --host <engine-host> \
  --port 8081

This connects to ws://<engine-host>:8081/v1/verify/authenticity and runs the same streaming verification flow. The default host is localhost and the default port is 3001 — override them with --host and --port to match your deployment.

Compare the output with the cloud API results from step 1. The scores should be consistent between environments.

Use wss:// with TLS termination in front of the engine for production deployments. Use ws:// only for local development and testing.

Additional script options

The verify.mjs script supports these optional flags:

Flag	Default	Description
--model <model>	phone	Authenticity verification model to use. The example script defaults to the phone model. See Authenticity Verification Models.
--synthesis-sources	disabled	Enable synthesis source scoring
--audio-format <format>	auto-detected	Audio format hint

Switching from cloud to self-hosted

The self-hosted engine exposes the same WebSocket API as the Hiya cloud service. The only change required is the endpoint URL:

Environment	Endpoint
Cloud	wss://api.hiya.com/audiointel/{region}/v1/spaces/{owner}/{space}/verify/authenticity
Self-hosted	ws://<engine-host>:8081/v1/verify/authenticity

This means any existing client code that works against the cloud API will work against the self-hosted engine by changing the WebSocket URL.

Troubleshooting

Symptom	Likely Cause	Resolution
Health check returns NOT_SERVING	Engine is still loading models	Wait up to 30 seconds for startup to complete
WebSocket connection refused on 8081	Port not exposed or firewall blocking	Verify port mapping (-p 8081:8081) and security group / firewall rules
WebSocket connects but no response	Missing or invalid API_KEY	Check the API_KEY environment variable and verify it with your Hiya account team
UNAVAILABLE error on health check	Engine container not running	Check container logs with docker logs or kubectl logs
Scores differ significantly from cloud	Different model version	Ensure the container image version matches the cloud model version