Build a reliable Python Voice API client.

Generate a Python client

Generated clients work well for backend services that need typed request and response models. Keep generated code in source control only after contract review.

openapi-python-client generate \
  --url https://voice.stateset.app/api-docs/public.json \
  --meta none \
  --path generated/stateset_voice_public

Small service wrapper

import os
import time
import requests

class StateSetVoiceClient:
    def __init__(self, api_key: str, base_url: str = "https://voice.stateset.app"):
        self.api_key = api_key
        self.base_url = base_url.rstrip("/")

    def make_call(self, *, to: str, from_: str, agent_key: str) -> dict:
        payload = {"to": to, "from": from_, "agent_key": agent_key}
        return self._request("POST", "/api/v1/make-call", json=payload)

    def _request(self, method: str, path: str, **kwargs) -> dict:
        headers = kwargs.pop("headers", {})
        headers["Authorization"] = f"Bearer {self.api_key}"
        headers["content-type"] = "application/json"

        for attempt in range(3):
            response = requests.request(
                method,
                f"{self.base_url}{path}",
                headers=headers,
                timeout=20,
                **kwargs,
            )
            if response.status_code not in {429, 500, 502, 503}:
                response.raise_for_status()
                return response.json()
            time.sleep(0.5 * (2 ** attempt))

        response.raise_for_status()
        return response.json()

client = StateSetVoiceClient(os.environ["STATESET_VOICE_API_KEY"])
print(client.make_call(to="+15555555678", from_="+15555551234", agent_key="support_primary"))

Operational defaults

• Set explicit connect and read timeouts for every request.
• Capture x-request-id on failures so support and operators can correlate logs.
• Retry only safe failure classes and protect outbound call creation with business idempotency.
• Generate clients from a pinned OpenAPI snapshot in CI before promoting production code.

Contract test

curl -sS https://voice.stateset.app/api-docs/public.json \
  -o api-contracts/stateset-voice-public.json

openapi-python-client generate \
  --path api-contracts/stateset-voice-public.json \
  --meta none \
  --output-path generated/stateset_voice_public

git diff --exit-code api-contracts generated