Quickstart

export PYAI_API_KEY="$(
  curl -sS -X POST https://api.pyai.com/v1/sandbox/keys \
    | python -c 'import json,sys; print(json.load(sys.stdin)["api_key"])'
)"

curl https://api.pyai.com/v1/me -H "Authorization: Bearer $PYAI_API_KEY"

{
  "object": "identity",
  "key_id": "key_...",
  "org_id": "org_...",
  "project_id": "proj_...",
  "env": "test",
  "status": "active",
  "org_status": "active",
  "plan": "payg",
  "scopes": [
    "hear:transcribe",
    "hear:stream",
    "hear:configure",
    "transcribe:jobs",
    "speak:synthesize",
    "speak:clone",
    "omni:session",
    "omni:read",
    "amd:detect",
    "amd:configure",
    "amd:read",
    "cast:render",
    "dub:render",
    "recap:configure",
    "recap:read",
    "trace:configure",
    "trace:read",
    "text:cleanup"
  ],
  "limits": { "rps": 20, "burst": 40, "concurrency": 2, "daily_unit_cap": 10 },
  "credit": { "gated": false, "available_cents": 0 }
}

pip install pyai-sdk
# or
npm install @pyai/sdk

import WebSocket from "ws"; // npm install ws

const ws = new WebSocket(
  "wss://api.pyai.com/v1/omni?format=pcm16&rate=24000",
  ["pyai.v1", `pyai-key.${process.env.PYAI_API_KEY}`],
);

ws.on("open", () => {
  const configure = Buffer.from(JSON.stringify({
    type: "configure",
    voice_id: "stock_dorit_en_us",
    persona: "You are a concise appointment assistant.",
  }));
  ws.send(Buffer.concat([Buffer.from([0x03]), configure]));
});

ws.on("message", (data, isBinary) => {
  if (!isBinary) return;
  const frame = Buffer.from(data);
  if (frame[0] !== 0x03) return;
  const event = JSON.parse(frame.subarray(1).toString("utf8"));
  console.log(event);
  if (event.event === "configured") ws.close();
});

{ "event": "configured", "voice_id": "stock_dorit_en_us", "tools": 0 }

{ "text": "Your appointment is confirmed for Thursday at two." }

curl https://api.pyai.com/v1/voice/clones \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -F "name=Ava, brand voice" \
  -F "file=@reference.wav"

{ "id": "voice_abc", "name": "Ava, brand voice", "status": "pending" }

curl https://api.pyai.com/v1/cast/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "We made it. Now let us show them what comes next.",
    "voice": "stock_dorit_en_us",
    "emotion": "warm",
    "intensity": "balanced"
  }' \
  --output preview.wav

curl -X POST https://api.pyai.com/v1/amd/config \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aggressiveness": 0.5, "webhook_url": "https://your-app.example.com/amd"}'

{
  "event": "amd",
  "call_id": "C_123",
  "answered_by": "machine",
  "answered_by_twilio": "machine_start",
  "confidence": 0.96,
  "decision_ms": 720,
  "reason": "machine phrase: 'please leave a message' at 1.2s"
}

curl -X PUT https://api.pyai.com/v1/trace/config \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "rule_packs": { "tcpa": { "enabled": true }, "pii": { "enabled": true } },
    "guardrails": { "mode": "warn", "block_pii": { "patterns": ["ssn", "credit_card"] } }
  }'

curl "https://api.pyai.com/v1/trace/exposure?window_days=30" \
  -H "Authorization: Bearer $PYAI_API_KEY"

curl -X POST https://api.pyai.com/v1/recap/calls/call_481 \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_direction": "outbound",
    "customer_name": "Acme",
    "utterances": [
      { "speaker_role": "agent", "text": "I will send the pricing sheet today.", "offset_s": 12.4, "duration_s": 3.1 },
      { "speaker_role": "customer", "text": "Please include the annual option.", "offset_s": 16.1, "duration_s": 2.3 }
    ]
  }'

curl https://api.pyai.com/v1/recap/calls/call_481 \
  -H "Authorization: Bearer $PYAI_API_KEY"

{
  "object": "recap.call",
  "call_id": "call_481",
  "status": "complete",
  "headline": "Acme requested annual pricing and agreed to review it this week.",
  "record": {
    "format": "recap.record.v1",
    "tldr": "Acme requested annual pricing and agreed to review it this week.",
    "summary": "The call focused on pricing structure and the next review step.",
    "action_items": [{ "owner": "agent", "task": "Send annual pricing", "due": "today" }],
    "next_steps": "Email the annual option.",
    "talk_ratio": { "agent": 0.55, "customer": 0.45 },
    "signals": [],
    "fields": {}
  }
}