POST
/
call
Python
from typing import Optional

from opperai import Opper
from pydantic import BaseModel, Field

opper = Opper(http_bearer="YOUR_API_KEY")


class CountryInput(BaseModel):
    country: str = Field(description="The name of the country")


class CapitalOutput(BaseModel):
    capital: str = Field(description="The capital city of the country")
    population: Optional[int] = Field(
        None, description="The population of the capital city"
    )


input_data = CountryInput(country="Sweden")

response = opper.call(
    name="get_capital",
    instructions="What is the capital of the provided country? Also include the population if you know it.",
    input_schema=CountryInput,
    output_schema=CapitalOutput,
    input=input_data,
)

print(response)
{
  "span_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": "The sum of 1 and 3 is 4",
  "json_payload": {
    "sum": 4
  },
  "cached": true,
  "images": [
    "image_url"
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 972,
    "output_tokens_details": {
      "reasoning_tokens": 704
    },
    "total_tokens": 997
  },
  "cost": {
    "generation": 0.0001,
    "platform": 0.00001,
    "total": 0.00011
  }
}

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

Successful Response

​
span_id
string<uuid>
required

The ID of the span of the call

​
message
string | null

Result of the task if the call does not use an output schema

Examples:

"The sum of 1 and 3 is 4"

​
json_payload

Result of the task if the call uses an output schema

Examples:
{ "sum": 4 }
​
cached
boolean | null

True if the result was returned from a cached results

Examples:

true

​
images
string[] | null

The images generated by the call. Only available for image models. Depending on the configuration, the response can either be a list of image urls or a base64 encoded images.

Examples:
["image_url"]
​
usage
object | null

The usage of the call split into input and output tokens as well as the total tokens and an optional breakdown of the input and output tokens.The input tokens are the tokens sent to the model and the output tokens are the tokens received from the model. The total tokens is the sum of input and output tokens.

Examples:
{
  "input_tokens": 25,
  "output_tokens": 972,
  "output_tokens_details": { "reasoning_tokens": 704 },
  "total_tokens": 997
}
​
cost
object | null

The cost in USD of the call split into total, generation and platform costs where total is the sum of generation and platform costs

Examples:
{
  "generation": 0.0001,
  "platform": 0.00001,
  "total": 0.00011
}