API Reference
Runner API
One-shot and streaming generation for SDK, React, and REST.
What this does
Send content → get generated output. Stateless — no memory between calls.
content body structure (MessageContent[])
The content array uses a shared schema across run, stream, and conversation methods.
type | Required fields | Example |
|---|---|---|
text | text | { "type": "text", "text": "Summarize this" } |
image | mime_type, file_uri | { "type": "image", "mime_type": "image/jpeg", "file_uri": "https://..." } |
video | mime_type, file_uri | { "type": "video", "mime_type": "video/mp4", "file_uri": "https://..." } |
audio | mime_type, file_uri | { "type": "audio", "mime_type": "audio/mpeg", "file_uri": "https://..." } |
url | mime_type, file_uri | { "type": "url", "mime_type": "application/pdf", "file_uri": "https://..." } |
For full multimodal examples, see Multimodal.
One-shot call
client.run(options)
const data = await client.run({content: [{ type: "text", text: "Explain this in simple words." }],variables: { TONE: "friendly" },})console.log(data.content)client.run(...) awaits and returns one complete response.
| Option | Type | Required | Description |
|---|---|---|---|
content | MessageContent[] | Yes | Input items (text, image, video, audio, url) |
variables | object | No | Values injected into assistant instructions |
deploymentId | string | No | Override the default deployment for this call |
Streaming call
client.stream(options)
const unsubscribe = client.stream.subscribe((state) => {if (state.status === "streaming") { process.stdout.write(state.live ?? "")}if (state.status === "success") { console.log("\n✓ Done:", state.data?.content) unsubscribe()}})await client.stream({content: [{ type: "text", text: "Stream this response." }],variables: { TONE: "friendly" },signal: abortController.signal,})client.stream(...) pushes tokens incrementally to subscribers.
| State field | Meaning |
|---|---|
state.live | Partial text as it streams in |
state.data | Complete response once done |
state.status | idle | loading | streaming | success | error |
| Option | Type | Required | Description |
|---|---|---|---|
content | MessageContent[] | Yes | Input items (text, image, video, audio, url) |
variables | object | No | Values injected into assistant instructions |
deploymentId | string | No | Override init-level deployment for this call |
signal | AbortSignal | No | Cancel in-flight stream |
Abort a stream:
client.stream.abort()Response shape
Every response (run or stream final) returns:
{
"content": "The assistant's output...",
"model": "model-name",
"input_tokens": 42,
"output_tokens": 61,
"request_id": "req_123"
}