PHASEO_API_KEY when you don’t pass a key.
Installation has the install command and requirements for each language. A C++ SDK is not yet released.
What you send and get back
Request bodies use the API’s JSON field names in every SDK. Usage has one example per endpoint.
A missing key fails when you create the client. Python raises
ValueError, Go’s NewFromEnv() returns an error, C# and PHP throw Missing API key. Pass apiKey or set PHASEO_API_KEY., Ruby raises ArgumentError: Missing API key. Pass api_key or set PHASEO_API_KEY., and Rust’s Phaseo::from_env() returns a PhaseoError.
Find the method for each endpoint
A dash means the SDK has no wrapper for that operation. Use the method in the last row, or call the HTTP API directly. “JSON only” means the method can’t send a multipart file upload: pass a URL or base64 data URL instead, or send the upload with your language’s HTTP client as the endpoint page shows. Most SDKs also have acreate… alias for each generate… method (for example CreateChatCompletion in Go and C#, create_response in Ruby).
C#, PHP, Ruby and Java have an upload method, but it sends JSON and can’t upload a file; Files and STT show the multipart request in each language. Keys and workspaces also have
get, update and delete methods and a current-key lookup (getCurrentApiKey, get_current_api_key, GetCurrentApiKey) in every SDK except Rust. TypeScript and Python also cover music, OCR, parse, decisions and extractions.
Check what each package ships
The published packages predate some features in the SDK source:Configure the client
- TypeScript
- Python
- Go
- C#
- PHP
- Ruby
- Java
- Rust
Wait for music, video, or batches
The wait helpers are in TypeScript and Python. The other SDKs return the job from the create call; poll it with the get method or open its job WebSocket URL.videos.generateAndWait / videos.generate_and_wait for video and batches.createAndWait / batches.create_and_wait for batches. Each helper submits once. If the first response is already complete it returns it without polling; otherwise it polls the same job until it finishes and returns the full response. Failed, cancelled, or expired jobs raise JobFailedError, whose response holds the details. A completed batch can still contain failed individual requests.
wait(id, options) on each resource resumes an existing job and returns any terminal response, including failures. In Python, music also has create(request) and retrieve(id).
JobTimeoutError and JobCancelledError keep the job ID and last response (jobId/lastResponse in TypeScript, job_id/last_response in Python), so you can resume with .wait(error.jobId) or .wait(error.job_id). Stopping a wait doesn’t cancel the remote job. In TypeScript it cancels the in-flight poll; the synchronous Python client checks cancellation and the deadline between requests and callbacks, so it can’t interrupt an HTTP call that is already in progress. HTTP failures are raised as they are, and submissions are never retried. These helpers poll from your process; they don’t add background execution to the gateway.
Keep a handle across processes
music.start, videos.start and batches.start return a handle with result(), events() and cancel(), plus toJSON() (TypeScript) or to_dict() (Python). Store the kind and ID it returns and rebuild the handle later with resume(id). result() throws on terminal failures. Only video and batch jobs support cancel(). On AsyncPhaseo, await the methods and iterate events with async for.
Request controls and errors
Retries default to0 in TypeScript, Python and Java, and apply only to GET and HEAD requests. Paid submissions, writes and streaming requests are never retried.
- TypeScript
- Python
- Java
- Rust
withOptions(...) returns a new client with those controls applied to every resource, stream and media call; the original client is unchanged. Retries honour Retry-After. timeoutMs includes reading the response body.responseMetadata(result) returns the gateway request ID and the dashboard trace URL. HTTP errors are PhaseoHttpError, with the HTTP status, the API error code, requestId, traceUrl, the retry delay, the body and headers.Call an endpoint without a wrapper
Each SDK also ships the client generated from the Phaseo OpenAPI spec:
The generated operations are lower-level than the wrapper methods; prefer the wrapper where one exists.
Parse output and collect streams
These helpers are in TypeScript and Python.responses.parse(request, schema) validates a completed JSON response. In TypeScript, schema is a Zod-compatible parser; in Python, a Pydantic model. Set the structured-output format in the request as well; the parser only validates.
collectStream(client.streamResponses(request)) (TypeScript), or collect_stream and collect_async_stream (Python), gather the streamed text and usage.
Check a model before you call it
checkModelCapabilities / check_model_capabilities (TypeScript and Python) checks advertised capabilities and scalar constraints (inputTypes, outputTypes, endpoints, parameters, parameterValues, or the snake_case names in Python) on one active provider offer. It never changes the model or drops parameters, and it can’t guarantee a live provider will accept the request. Missing metadata is handled differently: TypeScript reports it as unknown, and Python fails the check.
For model pickers and parameter editors, use live endpoint metadata:
supported, partial, unsupported, or unknown, with matching provider routes and constraint issues you can highlight inline. These checks are explicit calls; they don’t add a lookup to generation requests. Models lists the method in each SDK.
Test without the network
- TypeScript
- Python
Import
createMockTransport and jobFixtures from @phaseo/sdk/testing and pass the mock’s fetchImpl to the client. Fixtures are strict and ordered: an unexpected call fails locally and never reaches the network. Call mock.assertDone() to check every expected request happened.Export code from a room
After you send a request in a Phaseo room, Get code exports its model and settings as TypeScript or Python, and View request opens its dashboard trace when a request ID is available. Run exported code on your server withPHASEO_API_KEY set.