For the complete documentation index, see llms.txt. This page is also available as Markdown.

Pipeline API

Every published pipeline is a versioned HTTP endpoint. There are two ways to call it: the typed /invoke endpoint for JSON in and JSON out, and an OpenAI-compatible /chat/completions endpoint that works as a drop-in for any OpenAI SDK, streaming included.


Base URL

https://trezalabs.com

Both endpoints live under /api/pipelines/<id>, where <id> is the pipeline's id from the dashboard. They accept and return application/json (the streaming variant returns Server-Sent Events).


Authentication

Authenticate with a Treza API key, created on the API keys page in the dashboard and sent as a bearer token:

Authorization: Bearer treza_live_...

The key (treza_live_...) is shown once at creation. Store it in a secrets manager. A key can only invoke pipelines owned by the same account, and the pipeline must be published.

Starting a run (POST .../invoke and /chat/completions) needs the pipelines:run scope. Polling a run (GET .../invoke) accepts pipelines:read or pipelines:run. A key without the scope gets 403 with code: "MISSING_SCOPE". See API Keys.


Prerequisites

For a pipeline to accept API calls it must be published and have at least one input node and one output node. The input keys you send and the output keys you receive are derived from those nodes (the pipeline's contract). See Publishing & versioning.


Limits and credits

  • Rate limit. 60 requests a minute per account, shared by POST .../invoke and /chat/completions. Past it you get 429 with code: "RATE_LIMITED" and retryAfter (seconds), plus Retry-After and X-RateLimit-* headers.

  • Concurrent runs. Up to 10 runs of one pipeline can be in progress from /invoke at once. The next one gets 429 with code: "TOO_MANY_CONCURRENT_RUNS".

  • Credits. Runs draw from your account's prepaid credit balance. Before a run starts, the balance has to cover its estimated charge, and on /invoke also what is already committed to your runs still rendering. Check it with GET /api/account/balance and the same API key (see Funding an account without a human).

When the balance falls short, the run is refused with 402 before anything is charged:

topUpUrl is where a person adds credits. x402TopUpUrl lets an agent with a wallet top up on its own (see x402 Payments). On /chat/completions the same fields sit inside the error object, with type: "billing_error".


POST /api/pipelines/{id}/invoke

Starts a run of the published pipeline with typed inputs. Runs execute asynchronously on Treza's background workers, so this returns a runId immediately. Poll GET .../invoke for the result. Use this endpoint for video and other long runs.

Request

Field
Type
Description

inputs

object

Map of the pipeline's input keys to values. Keys come from your input nodes.

Response 202 Accepted

Field
Description

runId

Id of the run to poll. Also appears in run history.

status

Always running on accept.

version

The published version serving the run.

statusUrl

Ready-made URL to poll for status and outputs.


GET /api/pipelines/{id}/invoke

Polls a run started by POST .../invoke. Same bearer API key.

Request

Query param
Description

runId

The runId returned by POST .../invoke (URL-encode it).

Response

While the run is in progress:

Once finished:

Field
Description

status

running, success, error, partial, or cancelled (stopped before it finished).

outputs

Map keyed by the output nodes' keys of the version that ran (present once finished).

usage

Token counts and provider cost (costUsd) for the run.

durationMs

Wall-clock run time in milliseconds (once finished).

Poll statusUrl every few seconds until status is no longer running. Video and image generation poll asynchronous provider jobs, so a run can take a while. Output media URLs are returned verbatim; long text outputs are truncated in the polled result. A failed run is reported here as status: "error", not as an HTTP error.

Polling without runId returns 400; a runId this pipeline does not have returns 404.


POST /api/pipelines/{id}/chat/completions

An OpenAI-compatible chat-completions endpoint. Point any OpenAI SDK at it by changing the base URL and API key. The latest user message is fed into the pipeline's entry node, and the output node's value is returned as the assistant message.

curl

The model field is accepted but not used to pick a model (the pipeline's nodes decide that); send any string.

Python (OpenAI SDK)

TypeScript (OpenAI SDK)

Response

A standard OpenAI chat-completion object:

Two response headers help you tie a completion back to a run:

Header
Meaning

x-treza-run-id

Id of the recorded run.

x-treza-pipeline-version

The published version that served the request.

Streaming

Set "stream": true to receive the response as Server-Sent Events, emitted as chat.completion.chunk objects and terminated by data: [DONE]. The final chunk carries finish_reason: "stop" and a usage block. Any OpenAI SDK's streaming mode works unchanged. The chunks are sent once the run has finished, so streaming does not shorten the wait or the five-minute limit.


Errors

Every error response has an error field. On /invoke it is a message string, often next to a code you can branch on. On /chat/completions every error uses the OpenAI shape { "error": { "message": ..., "type": ..., "code": ... } }, so an OpenAI SDK raises its usual exception with the message intact. code is set where /invoke has one (MISSING_SCOPE, INSUFFICIENT_CREDITS, RATE_LIMITED).

Status
Meaning

400

Malformed request: no messages on /chat/completions, or no runId when polling /invoke.

401

Missing or invalid API key.

402

Not enough credits for this run (code: "INSUFFICIENT_CREDITS"). See Limits and credits.

403

The key's account does not own this pipeline, or the key lacks the scope (code: "MISSING_SCOPE").

404

Pipeline not found, or (when polling) run not found.

409

Pipeline is not published.

422

/chat/completions only: the pipeline has no entry node or no output node.

429

Rate limit or concurrent-run limit. See Limits and credits.

502

/chat/completions only: the pipeline ran but a node failed, and the error carries that node's message. On /invoke a failed run shows up as status: "error" when you poll.

500

Internal server error.


Last updated