---
title: "Poll a speech bought with an x402 payment, or read the menu"
method: GET
path: "/api/x402/speech"
---

# Poll a speech bought with an x402 payment, or read the menu

`GET /api/x402/speech`

## Request

- Base URL: `https://www.trezalabs.com`
- URL: `https://www.trezalabs.com/api/x402/speech`
- Auth: HTTP bearer

Called with no query parameters, returns the menu: what is on sale, every option and price, and how to buy. With runId and token (the statusUrl the paid POST handed back), returns the run's status and, once finished, audio: the file URL. The token is the claim ticket and the only credential needed. Send Prefer: wait=N to hold the answer until it finishes, for up to N seconds (at most 720), streamed like the paid POST. A failed run answers with the provider's error, a reason, and a retryUrl.

## Query parameters

- `runId` string
- `token` string

## Headers

- `Prefer` string

## Response `200`

Run status plus audio once it has finished; or, with no query parameters, the menu.

- union
  - object
    - `runId` string, required
    - `status` 'success' | 'error' | 'partial' | 'cancelled' | 'running', required: success carries audio. error, partial, and cancelled carry the failure fields. running means it is still going; poll statusUrl.
    - `startedAt` string, date-time
    - `finishedAt` string, date-time
    - `durationMs` integer
    - `audio` string, uri: URL of the finished speech. Use it exactly as given: its query parameters, including c=, are part of it.
    - `statusUrl` string, uri: The run's status, now and later. It carries its own signed claim ticket, so it needs no other credential. Use it exactly as given: the runId contains '#', encoded as %23.
    - `pollAfterMs` integer: Only when status is running: how long to wait before polling statusUrl.
    - `paidUsd` number: What this request cost.
    - `model` string
    - `voice` string
    - `characters` integer: Characters spoken: what the price was computed from.
    - `network` string: Where the payment settled: eip155:8453 (Base) or solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (Solana).
    - `transaction` string: The settled payment: a 0x transaction hash on Base, a base58 transaction signature on Solana.
    - `payer` string: The paying wallet.
    - `error` string: Failed runs only. What went wrong, in the provider's words.
    - `reason` 'prompt_refused' | 'render_failed': Failed runs only. prompt_refused: the model declined the text, so reword it. render_failed: it did not finish; the same text may succeed.
    - `retryable` boolean: Failed runs only. True until the run's one free retry has been used.
    - `retryUrl` string, uri: Failed runs only. POST here to try again on the wallet balance, optionally with {"text": "..."} in the body. Carries the same signed ticket.
    - `message` string: Failed runs only. What happened and what to do, in one sentence.
    - `balanceUsd` number: Failed runs only. The wallet balance the retry spends.
  - object: Returned when the GET carries no query parameters: what is on sale, the prices, and how to buy.
    - `service` string, required
    - `description` string
    - `howToBuy` object, required: The request to send: method, an example body, and how payment works.
      - `method` string
      - `body` object
      - `note` string
    - `pricing` string: How the price is computed.
    - `fields` object, required: Each request field and what it takes.
    - `models` object[]
      - `id` string
      - `label` string
      - `default` boolean
      - `note` string
    - `voices` object[]
      - `id` string
      - `description` string
      - `default` boolean
    - `limits` object: maxTextChars.
    - `delivery` string: How the paid call answers and where the file ends up.
    - `alreadyPaid` string: Where a file already paid for can be collected, for a buyer that lost its statusUrl.

## Other responses

- `400`: One of runId and token was given without the other. The runId contains '#', so a hand-built URL must encode it as %23.
- `403`: Invalid, expired, or mismatched token
- `404`: Run not found

---

[API](https://skmtc.dev/trezalabs/apis/treza-pipelines-api.md) · [All operations](https://skmtc.dev/trezalabs/apis/treza-pipelines-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trezalabs/apis/treza-pipelines-api/revisions/a76574c1731b?raw)