from opperai import Opper

opper = Opper(http_bearer="YOUR_API_KEY")

# Stream a creative writing task
stream_response = opper.stream(
    name="creative_writer",
    instructions="Write a short story about a robot learning to paint. Make it engaging and creative.",
    input={"topic": "robot artist", "length": "short"},
    model="openai/gpt-4o-mini",
)

# The stream method returns a response object with 'result' containing the EventStream
for event in stream_response.result:
    # Each event is a FunctionStreamCallStreamPostResponseBody with 'data' containing the streaming chunk
    if hasattr(event, "data") and hasattr(event.data, "delta") and event.data.delta:
        print(event.data.delta, end="", flush=True)

print("\n")  # New line at the end

{
  "data": {
    "span_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Task API

Stream LLM Call

Stream a function call execution in real-time using Server-Sent Events (SSE).

This endpoint provides continuous streaming of function execution results, supporting both unstructured text streaming and structured JSON streaming with precise field tracking.

Streaming Modes

Text Mode (no output_schema):

Streams incremental text content via the delta field
chunk_type will be “text”
Best for conversational AI, creative writing, open-ended responses

Structured Mode (with output_schema):

Streams structured JSON with precise field tracking via json_path
chunk_type will be “json”
Enables real-time UI updates by showing which schema field is being populated
Perfect for forms, dashboards, structured data display

JSON Path Feature

When using output_schema, each streaming chunk includes a json_path field showing exactly which field in your schema is being populated:

response.summary → Top-level string field
response.people[0].name → Name of first person in array
response.people[1].role → Role of second person
response.metadata.created_at → Nested object field

This enables precise UI updates where you can route streaming content to specific components based on the path, creating responsive real-time interfaces.

Response Structure

Each Server-Sent Event contains:

id: Optional event identifier
event: Optional event type (typically “message”)
data: StreamingChunk with the actual streaming content
retry: Optional retry interval for reconnection

The StreamingChunk data payload varies by mode:

Text Mode:

delta: Incremental text content
span_id: Execution span ID (first chunk)
chunk_type: “text”

Structured Mode:

delta: Actual field values being streamed
json_path: Dot-notation path to current field
span_id: Execution span ID (first chunk)
chunk_type: “json”

Examples

Text streaming events:

data: {"span_id": "123e4567-e89b-12d3-a456-426614174000"}
data: {"delta": "Hello", "chunk_type": "text"}
data: {"delta": " world", "chunk_type": "text"}

Structured streaming events:

data: {"span_id": "123e4567-e89b-12d3-a456-426614174000"}
data: {"delta": "John", "json_path": "response.name", "chunk_type": "json"}
data: {"delta": " Doe", "json_path": "response.name", "chunk_type": "json"}
data: {"delta": "Engineer", "json_path": "response.role", "chunk_type": "json"}

POST

call

stream

from opperai import Opper

opper = Opper(http_bearer="YOUR_API_KEY")

# Stream a creative writing task
stream_response = opper.stream(
    name="creative_writer",
    instructions="Write a short story about a robot learning to paint. Make it engaging and creative.",
    input={"topic": "robot artist", "length": "short"},
    model="openai/gpt-4o-mini",
)

# The stream method returns a response object with 'result' containing the EventStream
for event in stream_response.result:
    # Each event is a FunctionStreamCallStreamPostResponseBody with 'data' containing the streaming chunk
    if hasattr(event, "data") and hasattr(event.data, "delta") and event.data.delta:
        print(event.data.delta, end="", flush=True)

print("\n")  # New line at the end

{
  "data": {
    "span_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name

string

required

Provide a unique name of the task. A function with this name will be created in the project. Functions configuration is overridden by the request parameters.

instructions

string | null

default:You are a helpful assistant

Optionally provide an instruction for the model to complete the task. Recommended to be concise and to the point

Example:

"Calculate the sum of two numbers"

input_schema

Input Schema · object

Optionally provide an input schema for the task. Can preferably include field descriptions to allow the model to reason about the input variables. Schema is validated against the input data and issues an error if it does not match. With the Opper SDKs you can define these schemas through libraries like Pydantic and Zod. For schemas with definitions, prefer using '$defs' and '#/$defs/...' references.

Example:

{
  "properties": {
    "x": { "title": "X", "type": "integer" },
    "y": { "title": "Y", "type": "integer" }
  },
  "required": ["x", "y"],
  "title": "OpperInputExample",
  "type": "object"
}

output_schema

Output Schema · object

Optionally provide an output schema for the task. Response is guaranteed to match the schema or throw an error. Can preferably include field descriptions to allow the model to reason about the output variables. With the Opper SDKs you can define these schemas through libraries like Pydantic and Zod. For schemas with definitions, prefer using '$defs' and '#/$defs/...' references.

Streaming with output_schema: When used with streaming endpoints, enables precise field tracking via json_path. Each streaming chunk includes the exact schema field being populated (e.g., 'response.people[0].name'), allowing real-time UI updates by routing content to specific components.

Example:

{
  "properties": {
    "sum": { "title": "Sum", "type": "integer" }
  },
  "required": ["sum"],
  "title": "OpperOutputExample",
  "type": "object"
}

input

any | null

Optionally provide input data as context to complete the task. Could be a text, image, audio or a combination of these.

Example:

{ "x": 4, "y": 5 }

model

default:azure/gpt-4o-eu

Optionally provide a model to use for completing the task. If not provided, a default model will be used. Currently the default model is azure/gpt-4o-eu

To specify options for the model, use a dictionary of key-value pairs. The options are passed to the model on invocation. An example of passing temperature to gpt-4o-mini hosted on OpenAI is shown below.

{
    "model": "openai/gpt-4o-mini", # the model name
    "options": {
        "temperature": 0.5 # the options for the model
    }
}

To specify a fallback model, use a list of models. The models will then be tried in order. The second model will be used if the first model is not available, and so on.

[
    "openai/gpt-4o-mini", # first model to try
    "openai/gpt-4.1-nano", # second model to try
]

Example:

{
  "extra_headers": {},
  "name": "openai/gpt-4o-mini",
  "options": { "temperature": 0.5 }
}

examples

Example · object[] | null

Optionally provide examples of successful task completions. Will be added to the prompt to help the model understand the task from examples.

Show child attributes

examples.input

any

required

examples.output

any

required

examples.comment

string | null

Example:

[
  {
    "comment": "Adds two numbers",
    "input": { "x": 1, "y": 3 },
    "output": { "sum": 4 }
  }
]

parent_span_id

string<uuid> | null

Optionally provide the parent span ID to add to the call event. This will automatically tie the call to a parent span in the UI.

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Server-Sent Events stream of function execution chunks

Server-Sent Event following the SSE specification

data

StreamingChunk · object

required

Represents the data payload within a Server-Sent Event for streaming function execution.

This model contains the JSON content sent in the 'data' field of each SSE event. The fields present depend on the streaming mode:

Text Mode (no output_schema):

Uses delta field for incremental text content
chunk_type will be "text"

Structured Mode (with output_schema):

Uses delta and json_path for precise field tracking
Enables real-time UI updates by showing which schema field is being populated
chunk_type will be "json"

JSON Path Examples:

response.summary - Top-level string field
response.people[0].name - Name of first person in array
response.metadata.created_at - Nested object field

Show child attributes

data.delta

Incremental content for streaming. Used for both unstructured text streaming (when no output_schema) and structured streaming (when output_schema is provided). For structured streaming, contains actual field values being streamed to the json_path location. Supports all JSON types: strings, numbers, booleans.

Example:

"Hello"

data.json_path

string | null

Dot-notation path showing exactly which field in your output_schema is being populated. Enables precise UI updates by routing content to specific components. Format: field[index].nested_field

Example:

"summary"

data.span_id

string | null

Unique identifier for the execution span, included in the first streaming chunk for tracing

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.chunk_type

string | null

Indicates the streaming mode: 'text' for unstructured streaming, 'json' for structured streaming with output_schema, 'error' for error events. Only present when delta content is included.

Example:

"text"

data.error_type

string | null

Error type when chunk_type is 'error'

Example:

"RateLimitError"

data.error_message

string | null

Error message when chunk_type is 'error'

string

Event ID for the SSE event

Example:

"123"

event

string

Event type for the SSE event

Example:

"message"

retry

integer

Retry interval in milliseconds for the SSE connection

Example:

1000

Call LLM Introduction

⌘I

API Reference

Task API

Platform APIs

Stream LLM Call

Streaming Modes

JSON Path Feature

Response Structure

Examples

Authorizations

Body

Response