Generate an answer (demo helper)

POST https://api.tokenpath.ai/v1/generate

This is a convenience, not the product. TokenPath attribution works with any model. /v1/generate exists so demos and prototypes can produce an answer with a TokenPath key alone, without setting up a second provider. If you already have a model, skip this endpoint.

Send a list of chat messages. TokenPath streams back an answer from one inexpensive, server-selected model. TokenPath adds no prompt text of its own. The system message, how you frame the document, and the conversation history are all yours. Attribution is a separate call you make afterwards. Requires the attributions:write scope.

Request body

array of object

required

The conversation, oldest first. Each message is {"role": "system" | "user" | "assistant", "content": "..."}. You can send 1 to 50 messages, and the last one must have role user. Total content across all messages is capped at 420,000 characters.

integer

default:"512"

The maximum number of tokens to generate, from 16 to 2048.

That is the whole request. Unknown fields are rejected with 422 validation_error, both at the top level and inside each message. There is no model, temperature, tools, or stream parameter. TokenPath chooses the model and sampling settings. Reasoning, tools, web search, images, and structured output are all off. The message shape looks like OpenAI’s chat format, but this is not an OpenAI-compatible endpoint. The endpoint is stateless. To continue a conversation, send the whole transcript again each turn, just as you would with any chat API.

Response

A successful request returns 200 with Content-Type: text/event-stream. Each server-sent event has a name and a single-line JSON payload:

event: delta
data: {"text": "Revenue improved because "}

event: delta
data: {"text": "enterprise demand increased."}

event: done
data: {"answer": "Revenue improved because enterprise demand increased.", "model": "google/gemini-3.1-flash-lite", "usage": {"input_tokens": 55, "output_tokens": 9, "billed_tokens": 48}, "credits_remaining": 9999952}

`delta`

string

The next piece of the answer. Joining every delta gives exactly the done answer.

`done`

string

The complete answer. Attribute this string. Stream chunks can split in the middle of a Unicode character, but this field is always whole.

string

The model that actually ran. It can change over time, so read it instead of assuming.

object

input_tokens and output_tokens are the generation provider’s own counts, shown for transparency. billed_tokens is what you were charged.

integer | null

Your available balance after this call, or null if it could not be read.

`error`

Sent instead of done when generation fails after the stream has started:

event: error
data: {"error": {"code": "generation_timeout", "message": "Answer generation timed out.", "request_id": "req_..."}}

Failures before the stream starts are ordinary HTTP errors, so handle both.

Billing

Generation uses the same prepaid credits as attribution, at the same $1 per million tokens.

You are billed for input only, estimated as ceil(total message characters / 4). Output is free.
Credits are held before the model is called. If your balance is too low, you get 402 insufficient_credits and nothing is spent.
The charge becomes final once the model accepts the request. Disconnecting afterwards does not refund it.
If the request fails before the model accepts it, the hold is released in full.
Each turn re-sends the whole conversation, so each turn pays for it again, including any document in the system message.

Generation events appear in GET /v1/me/usage with generation_-prefixed reasons.

Generate, then attribute

Keep the document separate from the prompt you wrap it in. Send the bare document to /v1/attributions together with the done answer:

import json
import os

import httpx

API = "https://api.tokenpath.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"}

document = "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals."
question = "What drove Q4 revenue growth?"

messages = [
    {"role": "system", "content": f"Answer only from the document.\n\nDOCUMENT:\n{document}"},
    {"role": "user", "content": question},
]

answer = None
with httpx.stream("POST", f"{API}/v1/generate", headers=HEADERS,
                  json={"messages": messages}, timeout=90.0) as response:
    response.raise_for_status()
    event = None
    for line in response.iter_lines():
        if line.startswith("event:"):
            event = line.removeprefix("event:").strip()
        elif line.startswith("data:"):
            payload = json.loads(line.removeprefix("data:"))
            if event == "delta":
                print(payload["text"], end="", flush=True)
            elif event == "done":
                answer = payload["answer"]
            elif event == "error":
                raise RuntimeError(payload["error"]["code"])

# Attribute against the bare document, not the system message that wraps it.
result = httpx.post(
    f"{API}/v1/attributions",
    headers=HEADERS,
    json={"document": document, "question": question, "answer": answer,
          "offset_encoding": "utf-32"},
    timeout=90.0,
).json()

Errors

In addition to the authentication errors. The generation errors can arrive either as an HTTP status before the stream starts or as an error event after it has started.

Status	Code	Meaning
`402`	`insufficient_credits`	Your balance cannot cover the input. Nothing was spent.
`422`	`validation_error`	An unknown field, an empty or oversized `messages` list, a last message that is not `user`, or content over the character cap.
`429`	`rate_limited`	Over the generation rate limit. Retry after `Retry-After`.
`429`	`generation_saturated`	Too many generations in flight. Retry after `Retry-After`.
`502`	`generation_unreachable`	The model provider could not be reached.
`502`	`generation_failed`	The model provider returned an error.
`502`	`generation_incomplete`	The stream ended before the model finished.
`502`	`generation_empty_answer`	The model produced no text.
`503`	`generation_not_configured`	Generation is not available in this environment.
`504`	`generation_timeout`	Generation took too long.

Overview

Endpoints

Generate an answer (demo helper)

Request body

Response

`delta`

`done`

`error`

Billing

Generate, then attribute

Errors

​Request body

​Response

​delta

​done

​error

​Billing

​Generate, then attribute

​Errors

Request body

Response

`delta`

`done`

`error`

Billing

Generate, then attribute

Errors