POST
/
call
/
stream
Python
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": {
    "delta": "Hello! How can I assist you today?",
    "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.

Examples:

"add_numbers"

"parse_document"

"choose_tool"

​
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

Examples:

"Calculate the sum of two numbers"

​
input_schema
object | null

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.

Examples:
{
  "properties": {
    "x": { "title": "X", "type": "integer" },
    "y": { "title": "Y", "type": "integer" }
  },
  "required": ["x", "y"],
  "title": "OpperInputExample",
  "type": "object"
}
​
output_schema
object | null

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.

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

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

​
model

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
]
​
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.

Examples:
[
  {
    "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.

Examples:

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

​
tags
object | null

Optionally provide a list of tags to add to the call event. Useful for being able to understand aggregate analytics on some dimension.

Examples:
{
  "project": "project_456",
  "user": "company_123"
}
​
configuration
object | null

Optional configuration for the function.Configuration is a dictionary of key-value pairs that can be used to override the default configuration for the function.

Examples:
{
  "beta.evaluation.enabled": true,
  "invocation.cache.ttl": 0,
  "invocation.few_shot.count": 0,
  "invocation.structured_generation.max_attempts": 5
}

Response

Server-Sent Events stream of function execution chunks

Server-Sent Event following the SSE specification

​
data
object
required

The actual data payload containing streaming chunk information

​
id
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