Phaseo Python SDK

Official Python SDK for Phaseo Gateway.

Installation

pip install phaseo

Requires Python 3.10+.

Quick start

from phaseo import Phaseo

client = Phaseo()  # Uses PHASEO_API_KEY from environment

response = client.responses.create(
    {
        "model": "google/gemma-3-27b:free",
        "input": "Reply with: Python SDK works",
    }
)

print(response.get("output_text"))

To attribute usage to one of your own applications, provide app metadata explicitly:

client = Phaseo(
    app={
        "id": "support-console",
        "name": "Support Console",
        "url": "https://support.example.com",
    }
)

App attribution is optional and is never inferred from the SDK itself.

Regional text routing

Select eu or us to restrict Chat Completions, Responses, and Messages to matching regional provider routes:

client = Phaseo(region="eu")

Regional endpoints currently accept text-only requests. This is regional provider routing, not an end-to-end data residency guarantee. region cannot be combined with a custom base_url.

Streaming example

from phaseo import Phaseo

client = Phaseo()

response = ""
for chunk in client.stream_chat(
    {
        "model": "google/gemma-3-27b:free",
        "messages": [{"role": "user", "content": "Stream hi"}],
    }
):
    if chunk.get("text"):
        response += chunk["text"]
        print(chunk["text"], end="", flush=True)

    if chunk.get("reasoning_tokens"):
        print("\nReasoning tokens:", chunk["reasoning_tokens"])

Common methods

• client.responses.create(...)
• client.chat.completions.create(...)
• client.messages.create(...)
• client.stream_chat(...), client.stream_responses(...), and client.stream_message(...) for parsed streaming chunks with text, usage, and reasoning_tokens
• client.models.list(...)
• client.list_organisations(...) for paginated /organisations discovery
• client.list_pricing_models(...) for /pricing/models catalogue pricing discovery
• client.calculate_pricing(...) for /pricing/calculate usage estimation
• client.list_providers(...), client.get_credits(...), client.get_activity(...), and client.get_analytics(...) for provider discovery and management-key usage surfaces
• client.list_api_keys(...) for management-key /keys discovery
• client.create_api_key(...), client.update_api_key(key_id, ...), and client.delete_api_key(key_id) for management-key API-key lifecycle changes
• client.get_api_key(key_id) for management-key /keys/{id} lookup
• client.list_workspaces(...), client.get_workspace(workspace_id), client.create_workspace(...), client.update_workspace(workspace_id, ...), and client.delete_workspace(workspace_id) for management-key workspace lifecycle management
• client.get_current_api_key()
• client.get_health()
• client.models.get_deprecation_info(model_id)
• client.models.validate(model_id)
• client.batches.list_models() for batch-capable models and supported batch parameter metadata

Model discovery supports the public /models filters, including provider, provider_status, provider_routing_status, model_routing_status, capability_status, provider_availability_status, provider_availability_reason, status, organisation, endpoints, input_types, output_types, params, availability, limit, and offset.

Use provider_availability_reason with availability="all" when you want rollout-state entries such as preview_only, provider_not_ready, gated, access_limited, region_limited, project_limited, paused, or soft_blocked. Use capability_status with availability="all" when you want non-routable endpoint mappings such as coming_soon or internal_testing.

models = client.get_models({
    "provider": ["anthropic"],
    "provider_status": ["beta", "not_ready"],
    "provider_availability_reason": ["preview_only", "provider_not_ready"],
    "capability_status": ["coming_soon", "internal_testing"],
    "availability": "all",
})

Async job websocket helpers

Batch and video operations can expose a websocket lifecycle stream at /v1/async/{kind}/{id}/ws. Create responses include the job id, polling URL, optional websocket URL, and sanitized webhook delivery state.

import os

batch = client.batches.create({
    "endpoint": "/v1/responses",
    "input_file_id": "file_123",
    "completion_window": "24h",
    "webhook": {
        "url": "https://example.com/phaseo/webhooks",
        "secret": os.environ["PHASEO_WEBHOOK_SECRET"],
        "events": ["batch.progress", "batch.completed", "batch.failed"],
    },
})

video = client.videos.create({
    "model": "google/veo-3",
    "prompt": "orbital reveal",
    "webhook": {
        "url": "https://example.com/phaseo/webhooks",
        "secret": os.environ["PHASEO_WEBHOOK_SECRET"],
        "events": ["video.progress", "video.completed", "video.failed"],
    },
})

batch_socket_url = client.batches.websocket_url("batch_123", interval_ms=1500)

video_socket_url = client.videos.websocket_url(
    "video_123",
    close_on_terminal=True,
)

generic_socket_url = client.get_async_job_websocket_url("video", "video_123")

Free and paid models

• Models with :free in the model ID can be called with zero deposited credits.
• Paid models require available wallet balance.

Model lifecycle warnings

from phaseo import Phaseo

client = Phaseo(
    enable_deprecation_warnings=True,
    warnings_as_errors=False,
    logger=lambda level, message, meta: print(level, message, meta),
)

For completed Anthropic batches, client.batches.stream_results(batch_id) yields original JSONL byte chunks without buffering the whole download. Write chunks to your output file and close the iterator if stopping early. The configured HTTP timeout applies; downloading does not add inference charges.

Environment variables

• PHASEO_API_KEY (required unless passed in code)
• PHASEO_BASE_URL (optional, defaults to https://api.phaseo.app/v1)

Devtools

from phaseo import Phaseo, create_phaseo_devtools

client = Phaseo(
    devtools=create_phaseo_devtools(
        directory=".phaseo-devtools",
        capture_headers=False,
    )
)

Regeneration and local checks

• Regenerate generated client: pnpm openapi:gen:py
• Run tests: pnpm test:sdk-py
• Smoke checks:
  • pnpm --filter @phaseo/py-sdk run smoke:chat
  • pnpm --filter @phaseo/py-sdk run smoke:responses