# Create a model response

div
strong
🔨 In Development
 — This section is still being developed and may change.


Creates a model response for AI-powered text generation, structured outputs, and tool-augmented workflows.

Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search.

#### Request Body

### Core Parameters

**`organization_id`** string required

The unique identifier of the organization to which this request belongs. All API requests must be scoped to an organization for billing, access control, and resource management. Find your organization ID in [Freddy Hub → Settings → Organization](https://freddy-hub.aitronos.com/settings/organization).

**`assistant_id`** string optional

ID of the assistant to use for this response. When provided, automatically applies the assistant's configured rules, instructions, and settings. Enables consistent AI behavior across conversations with priority-based rule application and context management. [Learn more about assistants](/docs/documentation/core-concepts/assistants)

**`rules`** array of strings optional

IDs of rules to attach to this response. Rules provide additional behavior modifications and can override default model behavior. Each string should be a valid rule ID (e.g., `rule_abc123`). [Learn more about rules](/docs/documentation/core-concepts/rules)

**`disable_rules`** boolean optional · Defaults to `false`

Disable all rule application for this response. When `true`, no rules will be applied regardless of other rule settings. This parameter is only available when using API keys and cannot be used with bearer tokens (user authentication). [Learn more about rules](/docs/documentation/core-concepts/rules)

**`model`** string optional · Defaults to `ftg-3.0`

The AI model to use for generating the response. Aitronos supports various models with different capabilities, performance characteristics, and pricing. Choose based on your task requirements: reasoning models for complex problems, fast models for simple queries, or vision models for image understanding. [View available models →](/docs/documentation/getting-started/models)

**`inputs`** array required

Array of input message objects. Each message contains a role and content arrays (texts, images, audio, files). [View full object →](/docs/api-reference/objects/input-message)

## Properties

**`role`** string required

The role of the message input. One of `user`, `system`, or `assistant`.

**`texts`** array optional

Array of text content items.

details
summary
Show structure
Each text item:

**`text`** string required

The text content.

Example: `[{ "text": "Hello, how are you?" }]`

**`images`** array optional

Array of image inputs.

details
summary
Show structure
Each image item can have:

**`fileId`** string optional

Reference to an uploaded file.

**`url`** string optional

Direct image URL.

Example: `[{ "fileId": "file_abc123" }]` or `[{ "url": "https://example.com/image.jpg" }]`

**`audio`** array optional

Array of audio inputs.

details
summary
Show structure
Each audio item:

**`fileId`** string required

Reference to uploaded audio file.

Example: `[{ "fileId": "file_audio123" }]`

**`files`** array optional

Array of file attachments for context (PDFs, documents, etc.).

details
summary
Show structure
Each file item:

**`fileId`** string required

Reference to uploaded file.

Example: `[{ "fileId": "file_doc123" }]`

**`id`** string optional

The unique ID of the input message. Populated when items are returned via API.

### Thread and Context

**`thread`** string or object optional · Defaults to `null`

The thread that this response belongs to. Items from this thread are prepended to inputs for this response request. Input items and output items from this response are automatically added to this thread after completion. [Learn more](/docs/documentation/core-concepts/threads)

If no `thread` is provided (or set to `null`), a new thread is automatically created for this request. The response will include the new thread ID in the `thread` field, which can be used in subsequent requests to maintain conversation context and history. This enables seamless multi-turn conversations without manual thread management. For stateless multi-turn conversations, use `previous_response_id` instead (see inputs documentation).

**`instructions`** string optional

System-level instructions that define the model's behavior and capabilities. These instructions override any previous system messages when continuing from a prior response, allowing you to dynamically adjust the model's context without carrying over old system prompts.

**`rule_context`** object optional

Contextual information provided to attached rules to influence their behavior and execution. Since rules are now explicitly attached by ID, this context helps rules understand the request characteristics and adapt their application accordingly.

details
summary
Show properties
**`requestType`** string optional

Type of request being made. Examples: `chat`, `technical_documentation`, `creative_writing`, `code_generation`, `data_analysis`.

**`user_expertise`** string optional

User's expertise level. Values: `beginner`, `intermediate`, `expert`, `professional`. Provides context to attached rules about the expected user knowledge level, allowing rules to adjust their behavior accordingly.

**`output_format`** string optional

Desired output format. Examples: `markdown`, `html`, `json`, `plain_text`, `code`.

**`target_audience`** string optional

Intended audience for the response. Examples: `developers`, `business_users`, `students`, `general_public`.

### Response Delivery

**`stream`** boolean optional · Defaults to `false`

Enable streaming mode to receive response data incrementally as it's generated, using server-sent events (SSE). When enabled, the model sends partial outputs in real-time rather than waiting for the complete response. Ideal for user-facing applications requiring immediate feedback. [Learn more](/docs/documentation/running-methods/streaming-mode)

**`include`** array optional

Specify additional data to include in the response. Each value expands specific parts of the output with extra information. [Learn more](/docs/documentation/core-concepts/response-includes)

details
summary
Show possible types
- `all` - Include all available additional data types (web search sources, code outputs, logs, etc.). Use this for comprehensive debugging and full visibility into the response generation process. Note: Significantly increases response size and processing time.
- `web_search.sources` - Include source URLs and metadata from web search results
- `code_interpreter.outputs` - Include Python execution outputs and generated files
- `computer_use.screenshots` - Include screenshot URLs from computer interactions
- `file_search.results` - Include matched document chunks and relevance scores
- `function_calls.logs` - Include execution logs and timing data for function calls
- `function_calls.sources` - Include source code context for function executions
- `message.input_images` - Include full image URLs from user messages
- `message.output_images` - Include generated image URLs from assistant responses
- `message.logprobs` - Include output-level probability scores for generated content
- `reasoning.encrypted` - Include encrypted reasoning data for stateless conversations
- `request.logs` - Include detailed request processing logs
- `usage.detailed` - Include synapse and neuron usage breakdown by component
- `rules.debug` - Include detailed metadata about rule application, including which rules were considered, applied, compressed, or filtered


### Limits and Controls

**`max_output_synapses`** integer optional

Maximum number of synapses the model can generate in the response, including both visible output and internal reasoning synapses. Use this to control response length and computational cost. [Learn more](/docs/documentation/core-concepts/synapses-and-tokens)

**`metadata`** object optional

Custom key-value pairs (up to 16) for attaching structured information to the response. Useful for tracking, categorization, or filtering responses in your application. Keys must be ≤64 characters, values ≤512 characters.

**`previous_response_id`** string optional

Reference a previous response to create multi-turn conversations while maintaining context. The model will use the outputs and state from the referenced response as the starting point for this new response. Cannot be used together with `thread`. [Learn more](/docs/documentation/core-concepts/threads#stateless-conversations)

**`thread_context_mode`** string optional · Defaults to `recent`

Controls how thread history is managed when exceeding neuron capacity limits. Available modes: `recent` (keeps newest messages), `smart` (preserves start + recent), `full` (keeps all messages). [Learn more](/docs/documentation/core-concepts/thread-context-modes)

### Prompt and Reasoning

**`prompt`** object optional

Reference to a reusable prompt template with variable substitution. Prompt templates allow you to define standardized instructions once and reuse them across requests with dynamic values. [Learn more](/docs/documentation/core-concepts/prompt-templates)

details
summary
Show properties
**`id`** string required

The unique identifier of the prompt template to use.

**`variables`** object optional

Key-value pairs to substitute into template variables. Values can be strings, numbers, or other input types like images or files.

**`version`** string optional

Specific version of the prompt template. If omitted, uses the latest version.

**`reasoning`** object optional

**Unified reasoning configuration** that works across all reasoning-capable models (OpenAI GPT-5/O-series, Anthropic Claude). Controls how much computational effort the model dedicates to internal chain-of-thought processing before generating the final output. The API automatically maps your effort level to provider-specific parameters. [Learn more](/docs/documentation/reasoning/reasoning-models)

details
summary
Show properties
**`effort`** string optional · Defaults to `medium`

Controls the computational effort spent on reasoning/thinking. Higher effort produces more thorough analysis but increases response time and token usage.

**Available values:** `off`, `low`, `medium`, `high`, `maximum`

[View provider mapping details →](/docs/documentation/reasoning/reasoning-models#provider-mapping)

**`summary`** string optional

Request a summary of the model's reasoning process.

**Available values:**

- `auto` (model decides)
- `concise` (brief overview)
- `detailed` (comprehensive explanation)


**Note:** Some models do not stream reasoning content in real-time, only metadata events (`reasoning.started`, `reasoning.completed`). Other models stream full thinking content as it's generated.

### Tools

**`tools`** array optional

Array of tools the model can invoke during response generation. Enables extended capabilities beyond text generation, including web search, file analysis, code execution, custom function calls, and personal connectors. Tool usage can be controlled via the `toolChoice` parameter. [Learn more](/docs/documentation/core-concepts/function-calling)

details
summary
Show possible types
details
summary
System Tools
Built-in tools provided by Aitronos for common tasks like file search, web search, code execution, image generation, and computer control.

File Search object

Built-in tool for searching uploaded files and documents using vector similarity search. Retrieves relevant content from document collections to augment model responses with your data. [Learn more](/docs/documentation/system-tools/file-search)

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `fileSearch`.

**`vector_store_ids`** array required

Array of vector store IDs to search. Vector stores contain your uploaded and indexed documents.

**`filters`** object optional

Query filters to narrow search results (e.g., by file type, date, metadata).

**`max_num_results`** integer optional

Maximum number of results to return per search. Must be between 1 and 50. Higher values provide more context but increase neuron usage.

**`ranking_options`** object optional

Advanced ranking configuration for search results.

details
summary
Show ranking properties
**`ranker`** string optional

Ranking algorithm to use. Options: `default`, `semantic`, `hybrid`.

**`score_threshold`** number optional

Minimum relevance score (0.0 to 1.0) for results. Higher values return only highly relevant matches but may return fewer results.

Web Search object

Built-in tool for real-time internet search. Retrieves current information, news, and data beyond the model's training cutoff. [Learn more](/docs/documentation/system-tools/web-search)

details
summary
Show properties
**`type`** string required

The type of tool. One of `webSearch` or `web_search_2025_08_26` (version-specific).

**`search_context_size`** string optional · Defaults to `medium`

Controls how much neuron capacity the search results can consume. Higher values provide more comprehensive search context but increase neuron usage. Lower values are faster and more cost-effective but may miss relevant details. Available values: `low`, `medium`, `high`.

**`filters`** object optional

Search filters to control which domains are queried.

details
summary
Show filter properties
**`allowed_domains`** array optional · Defaults to `[]`

Restrict search to specific domains. If empty, all domains are allowed. Subdomains are automatically included (e.g., `example.com` includes `blog.example.com`).

Example: `["pubmed.ncbi.nlm.nih.gov", "nih.gov"]`

**`user_location`** object optional

Approximate geographic location of the user to provide location-aware search results. Useful for local queries (e.g., "restaurants nearby", "weather today").

details
summary
Show location properties
**`type`** string optional · Defaults to `approximate`

Type of location approximation. Always set to `approximate` for privacy.

**`city`** string optional

City name in free text format. Example: `San Francisco`, `Tokyo`, `London`.

**`region`** string optional

State, province, or region name. Example: `California`, `Ontario`, `Bavaria`.

**`country`** string optional

Two-letter ISO 3166-1 alpha-2 country code. Example: `US`, `JP`, `GB`, `DE`.

**`timezone`** string optional

IANA timezone identifier. Example: `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`.

Code Interpreter object

Executes Python code in a secure sandbox environment to perform computations, data analysis, file processing, and visualization tasks. Ideal for mathematical calculations, data transformations, and generating charts. [Learn more](/docs/documentation/system-tools/code-interpreter)

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `codeInterpreter`.

**`container`** string or object required

Specifies the code execution environment. Can be a container ID (string) for a pre-configured environment, or an object to auto-configure with specific files.

details
summary
Show container types
**String (Container ID):**

Reference a pre-existing container by ID. Example: `"container_abc123"`.

**Object (Auto-configuration):**

Automatically provision a container with specified files. Object properties:

**`type`** string required

Container type. Always set to `auto` for automatic provisioning.

**`file_ids`** array optional

Array of file IDs to make available in the code interpreter environment. Files must be uploaded via the Files API first. Example: `["file_abc123", "file_xyz789"]`.

Image Generation object

Generates images using AI image models. Supports multiple providers including OpenAI (DALL-E 2, DALL-E 3, GPT-Image-1) and Clipdrop. Creates images from text descriptions, modifies existing images via inpainting, or generates variations. Supports customization of style, quality, format, and dimensions. [Learn more](/docs/documentation/system-tools/image-generation)

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `image_generation`.

**`provider`** string optional · Defaults to `openai`

The image generation provider to use. Available options: `openai` (supports DALL-E 2, DALL-E 3, GPT-Image-1), `clipdrop` (Clipdrop image generation service).

**`model`** string optional · Defaults to `dall-e-3`

The image generation model to use. When `provider` is `openai`, supports: `dall-e-2`, `dall-e-3`, `gpt-image-1`. When `provider` is `clipdrop`, uses Clipdrop's default model.

**`prompt`** string required

A text description of the desired image. The maximum length is 1000 characters for DALL-E 3 and 4000 characters for DALL-E 2.

**`n`** integer optional · Defaults to `1`

The number of images to generate. Must be between 1 and 10. For DALL-E 3, only `1` is supported.

**`size`** string optional · Defaults to `1024x1024`

Dimensions of the generated image.

For DALL-E 2: `256x256`, `512x512`, `1024x1024`.

For DALL-E 3: `1024x1024`, `1792x1024`, `1024x1792`.

For GPT-Image-1: `1024x1024`, `1024x1536` (portrait), `1536x1024` (landscape), `auto` (model decides based on context).

**`quality`** string optional · Defaults to `standard`

Output image quality level.

For DALL-E 3: `standard` (faster, standard quality), `hd` (higher detail, slower, more expensive).

For GPT-Image-1: `low` (faster, smaller files), `medium`, `high` (best detail, slower), `auto` (balanced choice).

**`style`** string optional · Defaults to `vivid`

The style of the generated images. Only supported for DALL-E 3. Values: `vivid` (hyper-real and dramatic images), `natural` (more natural, less hyper-real).

**`response_format`** string optional · Defaults to `url`

The format in which the generated images are returned. Values: `url` (returns image URLs), `b64_json` (returns base64-encoded JSON strings).

**`output_format`** string optional · Defaults to `png`

File format for the generated image. Options: `png` (lossless, transparency), `webp` (modern, efficient), `jpeg` (compressed, no transparency).

**`output_compression`** integer optional · Defaults to `100`

Compression level for output images. Range: 0-100. Higher values preserve quality but increase file size. Only affects `jpeg` and `webp` formats.

**`background`** string optional · Defaults to `auto`

Background handling for generated images. Values: `transparent` (PNG with alpha channel), `opaque` (solid background), `auto` (model decides).

**`input_image`** string or object optional

Input image for editing or variation generation. Can be a URL string or an object with `fileId` or `imageUrl` properties.

details
summary
Show input image properties
**`fileId`** string optional

File ID of an uploaded image. Alternative to `imageUrl`.

**`imageUrl`** string optional

URL to an input image.

**`input_fidelity`** string optional · Defaults to `low`

Controls how closely the model matches style and features (especially facial features) from input images. Only supported for `gpt-image-1`. Values: `low` (creative interpretation), `high` (precise matching).

**`input_image_mask`** object optional

Mask configuration for inpainting (editing specific regions of an input image). Used to specify which areas should be regenerated. White areas in the mask indicate regions to regenerate; black areas are preserved.

details
summary
Show mask properties
**`imageUrl`** string optional

URL to a mask image. White areas indicate regions to regenerate; black areas are preserved.

**`fileId`** string optional

File ID of an uploaded mask image. Alternative to `imageUrl`.

**`partial_images`** integer optional · Defaults to `0`

Number of partial/intermediate images to generate during streaming. Range: 0-3. Useful for showing progressive generation stages to users. Only applicable when `stream: true`.

**`moderation`** string optional · Defaults to `auto`

Content moderation level applied to generated images. Values: `auto` (balanced safety), `strict` (conservative filtering), `permissive` (minimal filtering).

**`user`** string optional

A unique identifier representing your end-user, which can help OpenAI monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)

Computer Use Preview object

Experimental tool enabling the model to control a virtual computer environment. Allows interaction with applications, browsers, and system interfaces. [Learn more](/docs/documentation/system-tools/computer-use-preview)

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `computer_use_preview`.

**`environment`** string required

Type of virtual environment to control. Options: `desktop`, `browser`, `terminal`.

**`display_width`** integer required

Virtual display width in pixels. Recommended: 1280-1920.

**`display_height`** integer required

Virtual display height in pixels. Recommended: 720-1080.

details
summary
Personal Connectors
Access to external services and APIs through configured personal connectors. Enables the model to interact with services like Gmail, Google Calendar, Dropbox, and more. [Learn more about personal connectors →](/docs/api-reference/personal-connectors/list)

Personal Connectors object

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `personalConnector`.

**`configuration_ids`** array of strings optional

Specific personal connector configuration IDs to use. If not provided, all enabled configurations for the authenticated user or API key will be available. Each string should be a valid configuration ID (e.g., `pconf_abc123`).

details
summary
Streamline Tools
Built-in tool for executing user-uploaded scripts on the Streamline platform. Allows running custom server-side scripts as part of the AI workflow. Scripts are uploaded separately to the Streamline platform and referenced by ID.

Streamline Tool object

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `streamline`.

**`script_id`** string required

The unique identifier of the uploaded script on the Streamline platform.

**`parameters`** object optional

Key-value pairs of parameters to pass to the script during execution. These are made available to the script as environment variables or input arguments.

**`environment`** string optional · Defaults to `python`

The runtime environment for the script. Available options: `python`, `node`, `bash`, `ruby`, `php`.

**`timeout`** integer optional · Defaults to `300`

Maximum execution time in seconds before the script is terminated. Range: 1-64800 (18 hours). When `timeout` exceeds 5 minutes (300 seconds), background mode is automatically enabled to prevent request timeouts.

**`background`** boolean optional · Defaults to `false`

Run the script execution asynchronously in the background. When enabled, the API returns immediately with an execution ID while the script continues processing. Automatically enabled when `timeout` exceeds 5 minutes (300 seconds).

**`push_notification_on_completion`** boolean optional

Send a push notification when script execution completes. Useful for long-running scripts to notify users of completion status. Only applicable when `background` is `true` or when `timeout` exceeds 5 minutes.

**`require_approval`** boolean optional · Defaults to `false`

If `true`, requires user approval before executing the script. Useful for scripts with side effects.

details
summary
Custom MCP
Connect to Model Context Protocol (MCP) servers to access additional tools and capabilities. MCP enables Claude to interact with external services, databases, APIs, and custom integrations through standardized protocols. [Learn more](/docs/documentation/personal-connectors/mcp)

MCP Tool object

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `mcp`.

**`server_label`** string required

A unique label identifying this MCP server connection. Used to distinguish between multiple MCP servers in a single request and appears in tool calls and logs. Example: `"database_server"`, `"api_integration"`.

**Server Connection**

Choose one of the following methods to connect to an MCP server:

**`configuration_id`** string optional

ID of a saved MCP configuration. Use this to reference pre-configured connectors that have been set up in advance. [See MCP Configurations API](/docs/api-reference/mcp-configurations/create)

**`server_url`** string optional

Direct URL to a custom MCP server endpoint. Use this for connecting to your own MCP-compatible servers or third-party MCP services. Example: `"https://mcp.example.com/v1"`.

**`connector_id`** string optional

Identifier for built-in service connectors provided by Aitronos. These connectors handle authentication and connection setup automatically.

details
summary
Show available connectors
Currently supported connector IDs:

- `connector_dropbox` - Dropbox file storage
- `connector_gmail` - Gmail email access
- `connector_googlecalendar` - Google Calendar
- `connector_googledrive` - Google Drive
- `connector_microsoftteams` - Microsoft Teams
- `connector_outlookcalendar` - Outlook Calendar
- `connector_outlookemail` - Outlook Email
- `connector_sharepoint` - SharePoint


**Note:** One of `server_url`, `connector_id`, or `configuration_id` must be provided.

**Authentication**

**`authorization`** string optional

OAuth access token or API key for authenticating with the remote MCP server. Required when using custom MCP servers via `server_url` or when using service connectors that require additional authentication. Your application handles the OAuth flow and provides the token here.

**`headers`** object optional

Custom HTTP headers to send with requests to the MCP server. Used for authentication, API versioning, or other server-specific requirements. Example: `{"X-API-Key": "your-key", "Authorization": "Bearer token"}`.

**Server Configuration**

**`server_description`** string optional

Optional description of the MCP server's capabilities and purpose. This helps the model understand when and how to use tools from this server. Example: `"Internal analytics database with user query tools"`.

**Tool Filtering**

**`allowed_tools`** array or object optional

Restrict which tools from the MCP server the model can invoke. By default, all available tools are accessible. Use this to limit access for security or to focus the model on specific capabilities.

details
summary
Show examples
**Array format** - List specific tool names:


```json
["search_documents", "list_files", "get_file_content"]
```

**Filter object** - Use patterns to include/exclude tools:


```json
{
  "include": ["search_*", "get_*"],
  "exclude": ["delete_*", "update_*"]
}
```

**Approval Settings**

**`require_approval`** string or object optional · Defaults to `always`

Specify which MCP server tools require user approval before execution. This provides an additional security layer for tools that perform sensitive operations.

details
summary
Show approval options
**String values:**

- `always` - All tools require approval before execution (default, recommended)
- `never` - No approval required (use with caution, only for trusted servers)


**Object format** - Fine-grained control with patterns:


```json
{
  "require": ["delete_*", "update_*", "send_*"],
  "allow": ["search_*", "get_*", "list_*"]
}
```

This configuration requires approval for tools matching `delete_*`, `update_*`, or `send_*` patterns, while allowing `search_*`, `get_*`, and `list_*` tools to execute without approval.

details
summary
Custom Function Calls
Custom functions defined by you that the model can call with strongly-typed arguments. Enables the model to interact with your application code, APIs, or external services. [Learn more](/docs/documentation/core-concepts/function-calling)

Function object

details
summary
Show properties
**`type`** string required

The type of tool. Always set to `function`.

**`name`** string required

Unique identifier for the function. Used by the model to reference and invoke the function. Must be alphanumeric with underscores (e.g., `get_weather`, `calculate_total`).

**`description`** string optional

Human-readable explanation of what the function does. The model uses this to determine when and how to call the function. Be specific and clear.

**`parameters`** object required

JSON Schema object defining the function's input parameters. Specifies parameter names, types, descriptions, and whether they're required.

**`strict`** boolean optional · Defaults to `true`

Enforce strict parameter validation. When `true`, the model guarantees parameters match the schema exactly. When `false`, allows best-effort parameter generation.

**`require_approval`** boolean optional · Defaults to `false`

If `true`, requires user approval before executing the function. Useful for functions that perform sensitive operations, modify data, or have side effects. When `false`, the function executes automatically when called by the model.

**`toolChoice`** string or object optional · Defaults to `auto`

Controls which tools the model can use during response generation. Use `auto` to let the model decide, `none` to disable all tools, `required` to force tool usage, or specify a particular tool. [Learn more](/docs/documentation/core-concepts/function-calling#tool-choice)

**`max_tool_calls`** integer optional · Defaults to `20`

Maximum number of built-in tool calls the model can make during response generation. This limit applies to all built-in tools combined (web search, code interpreter, file search, etc.), not per individual tool. Once the limit is reached, any additional tool call attempts are ignored.

**`parallel_tool_calls`** boolean optional · Defaults to `false`

Allow the model to execute multiple tool calls simultaneously rather than sequentially. When enabled, improves performance for tasks requiring multiple independent operations. Disable if tool execution order matters or if you need to control concurrency.

### Output Format

**`output_mode`** string optional · Defaults to `text`

Specifies the format of the model's response output. Available modes: `text` (standard text), `json` (valid JSON object), `json_schema` (structured JSON adhering to a specific schema). [Learn more](/docs/documentation/core-concepts/structured-output)

**`json_schema`** object optional

Defines the expected structure for `json_schema` output mode. Required when `output_mode` is set to `json_schema`. The model will generate a response that conforms to this schema definition, ensuring type-safe, predictable outputs. Multiple schemas can be provided in a single request; the model selects or combines them based on the described purpose and input context. [Learn more](/docs/documentation/core-concepts/structured-output#json-schema)

details
summary
Show properties
**`id`** string required

Unique identifier for the JSON schema. Used for referencing and caching schema definitions.

**`description`** string required

A description of the schema's purpose. This helps the model determine when to use this schema for the output. For example: "Schema for weather forecast data including temperature, conditions, and location."

**`schema`** object required

The JSON Schema definition following JSON Schema Draft 2020-12 specification. Defines the structure, types, and constraints for the expected output.

**`strict`** boolean optional · Defaults to `true`

Enforce strict adherence to the schema. When `true`, the model guarantees valid output matching the schema. When `false`, the model attempts best-effort compliance.

### Response Parameters

**`temperature`** number optional · Defaults to `1.0`

Controls output randomness and creativity. Values range from `0.0` to `2.0`. Lower values (e.g., `0.2`) produce focused, deterministic outputs ideal for factual tasks. Higher values (e.g., `0.8`) generate more varied, creative responses suited for brainstorming. Adjust either `temperature` or `top_p`, not both.

**`top_p`** number optional · Defaults to `1.0`

Alternative to `temperature` for controlling randomness via nucleus sampling. Only the top cumulative probability mass up to `top_p` is considered. For example, `0.9` means only the top 90% probability mass is used. Values range from `0.0` to `1.0`. Adjust either `top_p` or `temperature`, not both.

**`logprobs`** boolean optional · Defaults to `false`

Enable log probability output for each generated element. When enabled, the response includes the log probability (confidence score) for each output element, allowing analysis of the model's certainty. Useful for debugging, confidence thresholds, and understanding alternative choices.

**`top_logprobs`** integer optional

Number of most likely alternatives to return at each position, along with their log probabilities. Must be between 0 and 20. Only applicable when `logprobs` is `true`. Provides insight into what other options the model considered and their relative probabilities.

**`presence_penalty`** number optional · Defaults to `0.0`

Penalizes content based on whether it appears in the generated text so far, encouraging the model to introduce new topics and concepts. Positive values (up to 2.0) increase novelty; negative values (down to -2.0) encourage staying on topic. Range: -2.0 to 2.0.

**`frequency_penalty`** number optional · Defaults to `0.0`

Penalizes content based on its frequency in the generated text, reducing repetitive phrasing. Higher values (up to 2.0) decrease repetition; negative values (down to -2.0) allow more repetition. Useful for preventing the model from repeating the same phrases verbatim. Range: -2.0 to 2.0.

**`truncation`** string optional · Defaults to `disabled`

Strategy for handling inputs that exceed the model's context window. Available values: `auto` (automatically truncate from beginning), `disabled` (fail with 400 error if exceeded). When set to `auto`, older messages are dropped to fit within the context window limits.

**`verbosity`** string optional · Defaults to `medium`

Controls the length and detail level of model responses. Lower verbosity produces concise, to-the-point answers ideal for quick information retrieval. Higher verbosity generates comprehensive, detailed explanations suited for learning or thorough analysis. Available values: `low`, `medium`, `high`.

**`background`** boolean optional · Defaults to `false`

Run the model response asynchronously in the background. When enabled, the API returns immediately with a response ID while processing continues. [Learn more](/docs/documentation/running-methods/background-mode)

## Returns

A [ResponseResponse](#responseresponse) object containing the API response data.

Minimal Example

```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "ftg-3.0",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Hello!"}]
      }
    ]
}'
```


```python
import os
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "ftg-3.0",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Hello!"}]
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch(
'https://api.freddy.aitronos.com/v1/model/response',
{
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123',
      model: 'ftg-3.0',
      inputs: [
        {
          role: 'user',
          texts: [{ text: 'Hello!' }]
        }
      ]
    })
}
);

const data = await response.json();
console.log(data);
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="ftg-3.0",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Hello!"}]
            }
        ]
    )
    
    print(response.output[0].content[0].text)
```

With Rules Example

```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "rules": ["rule_formal_tone", "rule_fact_check"],
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Write a product description for our new AI assistant"}]
      }
    ]
}'
```


```python
import os
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "rules": ["rule_formal_tone", "rule_fact_check"],
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Write a product description for our new AI assistant"}]
            }
        ]
    }
)

print(response.json())
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        rules=["rule_formal_tone", "rule_fact_check"],
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Write a product description for our new AI assistant"}]
            }
        ]
    )
    
    print(response.output[0].content[0].text)
```

## Disable Rules Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "disable_rules": true,
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Write a response without any rule modifications"}]
      }
    ]
}'
```


```python
import os
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "disable_rules": True,
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Write a response without any rule modifications"}]
            }
        ]
    }
)

print(response.json())
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        disable_rules=True,
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Write a response without any rule modifications"}]
            }
        ]
    )

    print(response.output[0].content[0].text)
```

## Streaming Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "stream": true,
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Tell me a story"}]
      }
    ]
}'
```


```python
import os
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "stream": True,
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Tell me a story"}]
            }
        ]
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))
```


```javascript
const response = await fetch(
'https://api.freddy.aitronos.com/v1/model/response',
{
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123',
      model: 'gpt-4o',
      stream: true,
      inputs: [
        {
          role: 'user',
          texts: [{ text: 'Tell me a story' }]
        }
      ]
    })
}
);

const reader = response.body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(new TextDecoder().decode(value));
}
```

## With Tools Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Search for recent AI research papers"}]
      }
    ],
    "tools": [
      {
        "type": "web_search",
        "search_context_size": "medium"
      },
      {
        "type": "function",
        "name": "save_to_database",
        "description": "Save findings to database",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "summary": {"type": "string"}
          }
        }
      }
    ]
}'
```


```python
import os
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Search for recent AI research papers"}]
            }
        ],
        "tools": [
            {
                "type": "web_search",
                "search_context_size": "medium"
            },
            {
                "type": "function",
                "name": "save_to_database",
                "description": "Save findings to database",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "summary": {"type": "string"}
                    }
                }
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch(
'https://api.freddy.aitronos.com/v1/model/response',
{
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123',
      model: 'gpt-4o',
      inputs: [
        {
          role: 'user',
          texts: [{ text: 'Search for recent AI research papers' }]
        }
      ],
      tools: [
        {
          type: 'web_search',
          search_context_size: 'medium'
        },
        {
          type: 'function',
          name: 'save_to_database',
          description: 'Save findings to database',
          parameters: {
            type: 'object',
            properties: {
              title: { type: 'string' },
              summary: { type: 'string' }
            }
          }
        }
      ]
    })
}
);

const data = await response.json();
console.log(data);
```

## Personal Connectors (All Enabled) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Create a ClickUp task for fixing the login bug"}]
      }
    ],
    "tools": [
      {
        "type": "personalConnector"
      }
    ]
}'
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")
response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Create a ClickUp task for fixing the login bug"}]
            }
        ],
        "tools": [
            {
                "type": "personalConnector"
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Create a ClickUp task for fixing the login bug' }]
      }
    ],
    personal_connectors_enabled: true
})
});

const data = await response.json();
console.log(data);
```

## Personal Connectors (Specific) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Create a GitHub issue and a ClickUp task for this bug"}]
      }
    ],
    "tools": [
      {
        "type": "personalConnector",
        "configuration_ids": ["pconf_github_abc", "pconf_clickup_xyz"]
      }
    ]
}'
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")
response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Create a GitHub issue and a ClickUp task for this bug"}]
            }
        ],
        "tools": [
            {
                "type": "personalConnector",
                "configuration_ids": ["pconf_github_abc", "pconf_clickup_xyz"]
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Create a GitHub issue and a ClickUp task for this bug' }]
      }
    ],
    tools: [
      {
        type: 'personalConnector',
        configuration_ids: ['pconf_github_abc', 'pconf_clickup_xyz']
      }
    ]
})
});

const data = await response.json();
console.log(data);
```

## Personal Connectors (Disabled) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "What is the capital of France?"}]
      }
    ],
    "personal_connectors_enabled": false
}'
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")
response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "What is the capital of France?"}]
            }
        ],
        "personal_connectors_enabled": False
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'What is the capital of France?' }]
      }
    ],
    personal_connectors_enabled: false
})
});

const data = await response.json();
console.log(data);
```

## MCP (Saved Config) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Find the latest product roadmap document"}]
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "server_label": "google_drive",
        "configuration_id": "mcp_config_abc123"
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Find the latest product roadmap document"}]
            }
        ],
        "tools": [
            {
                "type": "mcp",
                "server_label": "google_drive",
                "configuration_id": "mcp_config_abc123"
            }
        ]
    }
)
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Find the latest product roadmap document' }]
      }
    ],
    tools: [
      {
        type: 'mcp',
        server_label: 'google_drive',
        configuration_id: 'mcp_config_abc123'
      }
    ]
})
});
```

## MCP (Inline Direct) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Search my Gmail for important emails from this week"}]
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "server_label": "gmail",
        "connector_id": "connector_gmail",
        "authorization": "ya29.a0AfH6SMB...",
        "server_description": "Access to Gmail inbox"
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Search my Gmail for important emails from this week"}]
            }
        ],
        "tools": [
            {
                "type": "mcp",
                "server_label": "gmail",
                "connector_id": "connector_gmail",
                "authorization": gmail_oauth_token,
                "server_description": "Access to Gmail inbox"
            }
        ]
    }
)
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Search my Gmail for important emails from this week' }]
      }
    ],
    tools: [
      {
        type: 'mcp',
        server_label: 'gmail',
        connector_id: 'connector_gmail',
        authorization: gmailOauthToken,
        server_description: 'Access to Gmail inbox'
      }
    ]
})
});
```

## MCP (Custom Server) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Query our internal database for user analytics"}]
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "server_label": "internal_db",
        "server_url": "https://mcp.example.com/v1",
        "server_description": "Internal analytics database",
        "headers": {
          "X-API-Key": "sk_custom_..."
        },
        "allowed_tools": ["query_users", "get_analytics"],
        "require_approval": "never"
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Query our internal database for user analytics"}]
            }
        ],
        "tools": [
            {
                "type": "mcp",
                "server_label": "internal_db",
                "server_url": "https://mcp.example.com/v1",
                "server_description": "Internal analytics database",
                "headers": {
                    "X-API-Key": custom_api_key
                },
                "allowed_tools": ["query_users", "get_analytics"],
                "require_approval": "never"
            }
        ]
    }
)
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Query our internal database for user analytics' }]
      }
    ],
    tools: [
      {
        type: 'mcp',
        server_label: 'internal_db',
        server_url: 'https://mcp.example.com/v1',
        server_description: 'Internal analytics database',
        headers: {
          'X-API-Key': customApiKey
        },
        allowed_tools: ['query_users', 'get_analytics'],
        require_approval: 'never'
      }
    ]
})
});
```

## File Search Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "What does our documentation say about authentication?"}]
      }
    ],
    "tools": [
      {
        "type": "fileSearch",
        "vector_store_ids": ["vs_abc123"],
        "max_num_results": 5,
        "ranking_options": {
          "ranker": "hybrid",
          "score_threshold": 0.7
        }
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "What does our documentation say about authentication?"}]
            }
        ],
        "tools": [
            {
                "type": "fileSearch",
                "vector_store_ids": ["vs_abc123"],
                "max_num_results": 5,
                "ranking_options": {
                    "ranker": "hybrid",
                    "score_threshold": 0.7
                }
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'What does our documentation say about authentication?' }]
      }
    ],
    tools: [
      {
        type: 'fileSearch',
        vector_store_ids: ['vs_abc123'],
        max_num_results: 5,
        ranking_options: {
          ranker: 'hybrid',
          score_threshold: 0.7
        }
      }
    ]
})
});

const data = await response.json();
console.log(data);
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "What does our documentation say about authentication?"}]
            }
        ],
        tools=[
            {
                "type": "fileSearch",
                "vector_store_ids": ["vs_abc123"],
                "max_num_results": 5,
                "ranking_options": {
                    "ranker": "hybrid",
                    "score_threshold": 0.7
                }
            }
        ]
    )
    
    print(response.output[0].content[0].text)
```

## Web Search Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "What are the latest developments in quantum computing?"}]
      }
    ],
    "tools": [
      {
        "type": "webSearch",
        "search_context_size": "high",
        "filters": {
          "allowed_domains": ["arxiv.org", "nature.com"]
        },
        "user_location": {
          "type": "approximate",
          "city": "San Francisco",
          "country": "US"
        }
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "What are the latest developments in quantum computing?"}]
            }
        ],
        "tools": [
            {
                "type": "webSearch",
                "search_context_size": "high",
                "filters": {
                    "allowed_domains": ["arxiv.org", "nature.com"]
                },
                "user_location": {
                    "type": "approximate",
                    "city": "San Francisco",
                    "country": "US"
                }
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'What are the latest developments in quantum computing?' }]
      }
    ],
    tools: [
      {
        type: 'webSearch',
        search_context_size: 'high',
        filters: {
          allowed_domains: ['arxiv.org', 'nature.com']
        },
        user_location: {
          type: 'approximate',
          city: 'San Francisco',
          country: 'US'
        }
      }
    ]
})
});

const data = await response.json();
console.log(data);
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "What are the latest developments in quantum computing?"}]
            }
        ],
        tools=[
            {
                "type": "webSearch",
                "search_context_size": "high",
                "filters": {
                    "allowed_domains": ["arxiv.org", "nature.com"]
                },
                "user_location": {
                    "type": "approximate",
                    "city": "San Francisco",
                    "country": "US"
                }
            }
        ]
    )
    
    print(response.output[0].content[0].text)
```

## Code Interpreter Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Analyze this sales data and create a visualization showing trends"}]
      }
    ],
    "tools": [
      {
        "type": "code_interpreter",
        "container": {
          "type": "auto",
          "file_ids": ["file_sales_data_csv"]
        }
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Analyze this sales data and create a visualization showing trends"}]
            }
        ],
        "tools": [
            {
                "type": "code_interpreter",
                "container": {
                    "type": "auto",
                    "file_ids": ["file_sales_data_csv"]
                }
            }
        ]
    }
)

# Access code execution results
result = response.json()
for output in result.get('outputs', []):
    if output.get('type') == 'code_interpreter_output':
        print(f"Generated files: {output.get('files', [])}")
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Analyze this sales data and create a visualization showing trends"}]
            }
        ],
        tools=[
            {
                "type": "codeInterpreter",
                "container": {
                    "type": "auto",
                    "file_ids": ["file_sales_data_csv"]
                }
            }
        ]
    )
    
    # Access code execution results
    for output in response.output:
        if output.type == 'code_interpreter_output':
            print(f"Generated files: {output.files}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Analyze this sales data and create a visualization showing trends' }]
      }
    ],
    tools: [
      {
        type: 'code_interpreter',
        container: {
          type: 'auto',
          file_ids: ['file_sales_data_csv']
        }
      }
    ]
})
});

const result = await response.json();
// Access code execution results
result.outputs?.forEach(output => {
if (output.type === 'code_interpreter_output') {
    console.log(`Generated files: ${output.files}`);
}
});
```

## Image Generation Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Create a professional logo for a tech startup called \"NexGen AI\""}]
      }
    ],
    "tools": [
      {
        "type": "image_generation",
        "model": "gpt-image-1",
        "size": "1024x1024",
        "quality": "high",
        "output_format": "png",
        "background": "transparent"
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Create a professional logo for a tech startup called 'NexGen AI'"}]
            }
        ],
        "tools": [
            {
                "type": "image_generation",
                "model": "gpt-image-1",
                "size": "1024x1024",
                "quality": "high",
                "output_format": "png",
                "background": "transparent"
            }
        ]
    }
)

# Access generated images
result = response.json()
for output in result.get('outputs', []):
    if output.get('type') == 'image':
        print(f"Image URL: {output.get('imageUrl')}")
        print(f"File ID: {output.get('fileId')}")
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Create a professional logo for a tech startup called 'NexGen AI'"}]
            }
        ],
        tools=[
            {
                "type": "image_generation",
                "model": "gpt-image-1",
                "size": "1024x1024",
                "quality": "high",
                "output_format": "png",
                "background": "transparent"
            }
        ]
    )
    
    # Access generated images
    for output in response.output:
        if output.type == 'image':
            print(f"Image URL: {output.imageUrl}")
            print(f"File ID: {output.fileId}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Create a professional logo for a tech startup called "NexGen AI"' }]
      }
    ],
    tools: [
      {
        type: 'image_generation',
        model: 'gpt-image-1',
        size: '1024x1024',
        quality: 'high',
        output_format: 'png',
        background: 'transparent'
      }
    ]
})
});

const result = await response.json();
// Access generated images
result.outputs?.forEach(output => {
if (output.type === 'image') {
    console.log(`Image URL: ${output.imageUrl}`);
    console.log(`File ID: ${output.fileId}`);
}
});
```

## Image Edit (Inpaint) Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Replace the background with a sunset beach scene"}],
        "images": [{"fileId": "file_original_photo"}]
      }
    ],
    "tools": [
      {
        "type": "image_generation",
        "model": "gpt-image-1",
        "input_fidelity": "high",
        "input_image_mask": {
          "fileId": "file_mask_image"
        },
        "quality": "high",
        "output_format": "jpeg",
        "output_compression": 90
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Replace the background with a sunset beach scene"}],
                "images": [{"fileId": "file_original_photo"}]
            }
        ],
        "tools": [
            {
                "type": "image_generation",
                "model": "gpt-image-1",
                "input_fidelity": "high",
                "input_image_mask": {
                    "fileId": "file_mask_image"
                },
                "quality": "high",
                "output_format": "jpeg",
                "output_compression": 90
            }
        ]
    }
)

result = response.json()
print(f"Edited image: {result['outputs'][0]['imageUrl']}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Replace the background with a sunset beach scene' }],
        images: [{ fileId: 'file_original_photo' }]
      }
    ],
    tools: [
      {
        type: 'image_generation',
        model: 'gpt-image-1',
        input_fidelity: 'high',
        input_image_mask: {
          fileId: 'file_mask_image'
        },
        quality: 'high',
        output_format: 'jpeg',
        output_compression: 90
      }
    ]
})
});

const result = await response.json();
console.log(`Edited image: ${result.outputs[0].imageUrl}`);
```

## Image Generation with Provider Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Generate a futuristic cityscape at sunset"}]
      }
    ],
    "tools": [
      {
        "type": "image_generation",
        "provider": "openai",
        "model": "dall-e-3",
        "prompt": "A futuristic cityscape at sunset with flying cars and neon lights",
        "size": "1792x1024",
        "quality": "hd",
        "style": "vivid",
        "n": 1,
        "response_format": "url"
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Generate a futuristic cityscape at sunset"}]
            }
        ],
        "tools": [
            {
                "type": "image_generation",
                "provider": "openai",
                "model": "dall-e-3",
                "prompt": "A futuristic cityscape at sunset with flying cars and neon lights",
                "size": "1792x1024",
                "quality": "hd",
                "style": "vivid",
                "n": 1,
                "response_format": "url"
            }
        ]
    }
)

print(response.json())
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Generate a futuristic cityscape at sunset"}]
            }
        ],
        tools=[
            {
                "type": "image_generation",
                "provider": "openai",
                "model": "dall-e-3",
                "prompt": "A futuristic cityscape at sunset with flying cars and neon lights",
                "size": "1792x1024",
                "quality": "hd",
                "style": "vivid",
                "n": 1,
                "response_format": "url"
            }
        ]
    )
    
    # Access generated images
    for output in response.output:
        if output.type == 'image':
            print(f"Generated image: {output.imageUrl}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Generate a futuristic cityscape at sunset' }]
      }
    ],
    tools: [
      {
        type: 'image_generation',
        provider: 'openai',
        model: 'dall-e-3',
        prompt: 'A futuristic cityscape at sunset with flying cars and neon lights',
        size: '1792x1024',
        quality: 'hd',
        style: 'vivid',
        n: 1,
        response_format: 'url'
      }
    ]
})
});

const data = await response.json();
console.log(data);
```

## Streaming Images Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "stream": true,
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Generate a futuristic cityscape at night"}]
      }
    ],
    "tools": [
      {
        "type": "image_generation",
        "model": "gpt-image-1",
        "size": "1536x1024",
        "quality": "high",
        "partial_images": 3
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "stream": True,
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Generate a futuristic cityscape at night"}]
            }
        ],
        "tools": [
            {
                "type": "image_generation",
                "model": "gpt-image-1",
                "size": "1536x1024",
                "quality": "high",
                "partial_images": 3
            }
        ]
    },
    stream=True
)

# Stream partial images as they're generated
for line in response.iter_lines():
    if line.startswith(b'data: '):
        data = json.loads(line[6:])
        if data.get('type') == 'image.partial':
            print(f"Partial image {data['index']}: {data['imageUrl']}")
        elif data.get('type') == 'image.completed':
            print(f"Final image: {data['imageUrl']}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    stream: true,
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Generate a futuristic cityscape at night' }]
      }
    ],
    tools: [
      {
        type: 'image_generation',
        model: 'gpt-image-1',
        size: '1536x1024',
        quality: 'high',
        partial_images: 3
      }
    ]
})
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
const { done, value } = await reader.read();
if (done) break;

const chunk = decoder.decode(value);
const lines = chunk.split('\n');

for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'image.partial') {
        console.log(`Partial image ${data.index}: ${data.imageUrl}`);
      } else if (data.type === 'image.completed') {
        console.log(`Final image: ${data.imageUrl}`);
      }
    }
}
}
```

## Computer Use Preview Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Open a browser and search for the latest Python documentation"}]
      }
    ],
    "tools": [
      {
        "type": "computer_use_preview",
        "environment": "browser",
        "display_width": 1920,
        "display_height": 1080
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Open a browser and search for the latest Python documentation"}]
            }
        ],
        "tools": [
            {
                "type": "computer_use_preview",
                "environment": "browser",
                "display_width": 1920,
                "display_height": 1080
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Open a browser and search for the latest Python documentation' }]
      }
    ],
    tools: [
      {
        type: 'computer_use_preview',
        environment: 'browser',
        display_width: 1920,
        display_height: 1080
      }
    ]
})
});

const data = await response.json();
console.log(data);
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Open a browser and search for the latest Python documentation"}]
            }
        ],
        tools=[
            {
                "type": "computer_use_preview",
                "environment": "browser",
                "display_width": 1920,
                "display_height": 1080
            }
        ]
    )
    
    print(response.output[0].content[0].text)
```

## Streamline Tools Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Process this data analysis script"}]
      }
    ],
    "tools": [
      {
        "type": "streamline",
        "script_id": "script_abc123",
        "environment": "python",
        "timeout": 600,
        "background": false,
        "push_notification_on_completion": true,
        "parameters": {
          "input_file": "data.csv",
          "output_format": "json"
        }
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Process this data analysis script"}]
            }
        ],
        "tools": [
            {
                "type": "streamline",
                "script_id": "script_abc123",
                "environment": "python",
                "timeout": 600,
                "background": False,
                "push_notification_on_completion": True,
                "parameters": {
                    "input_file": "data.csv",
                    "output_format": "json"
                }
            }
        ]
    }
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Process this data analysis script' }]
      }
    ],
    tools: [
      {
        type: 'streamline',
        script_id: 'script_abc123',
        environment: 'python',
        timeout: 600,
        background: false,
        push_notification_on_completion: true,
        parameters: {
          input_file: 'data.csv',
          output_format: 'json'
        }
      }
    ]
})
});

const data = await response.json();
console.log(data);
```


```python
from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "Process this data analysis script"}]
            }
        ],
        tools=[
            {
                "type": "streamline",
                "script_id": "script_abc123",
                "environment": "python",
                "timeout": 600,
                "background": False,
                "push_notification_on_completion": True,
                "parameters": {
                    "input_file": "data.csv",
                    "output_format": "json"
                }
            }
        ]
    )
    
    print(response.output[0].content[0].text)
```

## Function Calling Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "What'\''s the weather like in San Francisco?"}]
      }
    ],
    "tools": [
      {
        "type": "function",
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
              }
            },
            "required": ["location"]
        },
        "strict": true,
        "require_approval": false
      }
    ],
    "toolChoice": "auto"
}'
```


```python
import requests
import json

# Define available functions
def get_current_weather(location, unit="fahrenheit"):
    """Get the current weather for a location"""
    # In production, call a real weather API
    return {
        "location": location,
        "temperature": 72,
        "unit": unit,
        "conditions": "sunny"
    }

# Initial API call
response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "What's the weather like in San Francisco?"}]
            }
        ],
        "tools": [
            {
                "type": "function",
                    "name": "get_current_weather",
                    "description": "Get the current weather in a given location",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The city and state, e.g. San Francisco, CA"
                            },
                            "unit": {
                                "type": "string",
                            "enum": ["celsius", "fahrenheit"],
                            "description": "Temperature unit"
                            }
                        },
                        "required": ["location"]
                },
                "strict": True,
                "require_approval": False
            }
        ],
        "toolChoice": "auto"
    }
)

result = response.json()

# Check if model wants to call a function
for output in result.get('outputs', []):
    if output.get('type') == 'function_call':
        function_name = output['function']['name']
        function_args = json.loads(output['function']['arguments'])
        
        # Execute the function
        if function_name == "get_current_weather":
            function_response = get_current_weather(**function_args)
            
            # Send function result back to model
            follow_up = requests.post(
                "https://api.freddy.aitronos.com/v1/model/response",
                headers={
                    "Authorization": f"Bearer {api_key}",
                    "Content-Type": "application/json"
                },
                json={
                    "organization_id": "org_abc123",
    "model": "gpt-4o",
                    "inputs": [
                        {
                            "role": "user",
                            "texts": [{"text": "What's the weather like in San Francisco?"}]
                        },
                        {
                            "role": "assistant",
                            "functionCall": {
                                "name": function_name,
                                "arguments": json.dumps(function_args)
                            }
                        },
                        {
                            "role": "function",
                            "name": function_name,
                            "content": json.dumps(function_response)
                        }
                    ],
                    "tools": [...]
                }
            )
            
            final_result = follow_up.json()
            print(final_result['outputs'][0]['texts'][0]['text'])
```


```python
from freddy import FreddyClient
import json

# Define available functions
def get_current_weather(location, unit="fahrenheit"):
    """Get the current weather for a location"""
    # In production, call a real weather API
    return {
        "location": location,
        "temperature": 72,
        "unit": unit,
        "conditions": "sunny"
    }

with FreddyClient(api_key="your-api-key") as client:
    # Initial API call
    response = client.responses.create(
        model="gpt-4o",
        inputs=[
            {
                "role": "user",
                "texts": [{"text": "What's the weather like in San Francisco?"}]
            }
        ],
        tools=[
            {
                "type": "function",
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"],
                            "description": "Temperature unit"
                        }
                    },
                    "required": ["location"]
                },
                "strict": True,
                "require_approval": False
            }
        ],
        toolChoice="auto"
    )
    
    # Check if model wants to call a function
    for output in response.output:
        if output.type == 'function_call':
            function_name = output.function.name
            function_args = json.loads(output.function.arguments)
            
            # Execute the function
            if function_name == "get_current_weather":
                function_response = get_current_weather(**function_args)
                
                # Send function result back to model
                follow_up = client.responses.create(
                    model="gpt-4o",
                    inputs=[
                        {
                            "role": "user",
                            "texts": [{"text": "What's the weather like in San Francisco?"}]
                        },
                        {
                            "role": "assistant",
                            "functionCall": {
                                "name": function_name,
                                "arguments": json.dumps(function_args)
                            }
                        },
                        {
                            "role": "function",
                            "name": function_name,
                            "content": json.dumps(function_response)
                        }
                    ],
                    tools=[...]
                )
                
                print(follow_up.output[0].content[0].text)
```


```javascript
// Define available functions
function getCurrentWeather(location, unit = 'fahrenheit') {
// In production, call a real weather API
return {
    location: location,
    temperature: 72,
    unit: unit,
    conditions: 'sunny'
};
}

// Initial API call
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: "What's the weather like in San Francisco?" }]
      }
    ],
    tools: [
      {
        type: 'function',
          name: 'get_current_weather',
          description: 'Get the current weather in a given location',
          parameters: {
            type: 'object',
            properties: {
              location: {
                type: 'string',
                description: 'The city and state, e.g. San Francisco, CA'
              },
              unit: {
                type: 'string',
              enum: ['celsius', 'fahrenheit'],
              description: 'Temperature unit'
              }
            },
            required: ['location']
        },
        strict: true,
        require_approval: false
      }
    ],
    toolChoice: 'auto'
})
});

const result = await response.json();

// Check if model wants to call a function
for (const output of result.outputs || []) {
if (output.type === 'function_call') {
    const functionName = output.function.name;
    const functionArgs = JSON.parse(output.function.arguments);
    
    // Execute the function
    let functionResponse;
    if (functionName === 'get_current_weather') {
      functionResponse = getCurrentWeather(functionArgs.location, functionArgs.unit);
    }
    
    // Send function result back to model
    const followUp = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4o',
      inputs: [
        {
          role: 'user',
            texts: [{ text: "What's the weather like in San Francisco?" }]
          },
          {
            role: 'assistant',
            functionCall: {
              name: functionName,
              arguments: JSON.stringify(functionArgs)
            }
          },
          {
            role: 'function',
            name: functionName,
            content: JSON.stringify(functionResponse)
          }
        ],
        tools: [...]
      })
    });
    
    const finalResult = await followUp.json();
    console.log(finalResult.outputs[0].texts[0].text);
}
}
```

## Multiple Functions Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Send an email to john@example.com about the Q4 report"}]
      }
    ],
    "tools": [
      {
        "type": "function",
          "name": "send_email",
          "description": "Send an email to a recipient",
          "parameters": {
            "type": "object",
            "properties": {
              "to": {"type": "string", "description": "Recipient email address"},
              "subject": {"type": "string", "description": "Email subject"},
              "body": {"type": "string", "description": "Email body content"}
            },
            "required": ["to", "subject", "body"]
        },
        "strict": true,
        "require_approval": true
      },
      {
        "type": "function",
          "name": "get_document",
          "description": "Retrieve a document by name",
          "parameters": {
            "type": "object",
            "properties": {
              "document_name": {"type": "string", "description": "Name of the document"}
            },
            "required": ["document_name"]
        },
        "strict": true,
        "require_approval": false
      },
      {
        "type": "function",
          "name": "create_calendar_event",
          "description": "Create a calendar event",
          "parameters": {
            "type": "object",
            "properties": {
              "title": {"type": "string"},
              "date": {"type": "string", "description": "ISO 8601 date"},
              "duration_minutes": {"type": "integer"}
            },
            "required": ["title", "date"]
        },
        "strict": true,
        "require_approval": true
      }
    ],
    "toolChoice": "auto"
}'
```


```python
import requests
import json

# Define available functions
def send_email(to, subject, body):
    print(f"Sending email to {to}: {subject}")
    return {"status": "sent", "message_id": "msg_123"}

def get_document(document_name):
    print(f"Retrieving document: {document_name}")
    return {"name": document_name, "content": "Q4 Report Summary..."}

def create_calendar_event(title, date, duration_minutes=60):
    print(f"Creating event: {title} on {date}")
    return {"event_id": "evt_456", "status": "created"}

# Function registry
available_functions = {
    "send_email": send_email,
    "get_document": get_document,
    "create_calendar_event": create_calendar_event
}

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Send an email to john@example.com about the Q4 report"}]
            }
        ],
        "tools": [
            {
                "type": "function",
                    "name": "send_email",
                    "description": "Send an email to a recipient",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "to": {"type": "string"},
                            "subject": {"type": "string"},
                            "body": {"type": "string"}
                        },
                        "required": ["to", "subject", "body"]
                },
                "strict": True,
                "require_approval": True
            },
            {
                "type": "function",
                    "name": "get_document",
                    "description": "Retrieve a document by name",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "document_name": {"type": "string"}
                        },
                        "required": ["document_name"]
                },
                "strict": True,
                "require_approval": False
            }
        ]
    }
)

result = response.json()

# Handle function calls
for output in result.get('outputs', []):
    if output.get('type') == 'function_call':
        func_name = output['function']['name']
        func_args = json.loads(output['function']['arguments'])
        
        # Execute the function
        if func_name in available_functions:
            func_result = available_functions[func_name](**func_args)
            print(f"Function {func_name} returned: {func_result}")
```


```javascript
// Define available functions
const availableFunctions = {
send_email: (to, subject, body) => {
    console.log(`Sending email to ${to}: ${subject}`);
    return { status: 'sent', message_id: 'msg_123' };
},
get_document: (document_name) => {
    console.log(`Retrieving document: ${document_name}`);
    return { name: document_name, content: 'Q4 Report Summary...' };
},
create_calendar_event: (title, date, duration_minutes = 60) => {
    console.log(`Creating event: ${title} on ${date}`);
    return { event_id: 'evt_456', status: 'created' };
}
};

const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Send an email to john@example.com about the Q4 report' }]
      }
    ],
    tools: [
      {
        type: 'function',
          name: 'send_email',
          description: 'Send an email to a recipient',
          parameters: {
            type: 'object',
            properties: {
              to: { type: 'string' },
              subject: { type: 'string' },
              body: { type: 'string' }
            },
            required: ['to', 'subject', 'body']
        },
        strict: true,
        require_approval: true
      },
      {
        type: 'function',
          name: 'get_document',
          description: 'Retrieve a document by name',
          parameters: {
            type: 'object',
            properties: {
              document_name: { type: 'string' }
            },
            required: ['document_name']
        },
        strict: true,
        require_approval: false
      }
    ]
})
});

const result = await response.json();

// Handle function calls
for (const output of result.outputs || []) {
if (output.type === 'function_call') {
    const funcName = output.function.name;
    const funcArgs = JSON.parse(output.function.arguments);
    
    // Execute the function
    if (funcName in availableFunctions) {
      const funcResult = availableFunctions[funcName](...Object.values(funcArgs));
      console.log(`Function ${funcName} returned:`, funcResult);
    }
}
}
```

## Parallel Functions Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Get weather for NYC, LA, and Chicago"}]
      }
    ],
    "tools": [
      {
        "type": "function",
          "name": "get_weather",
          "description": "Get weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
        },
        "strict": true,
        "require_approval": false
      }
    ],
    "parallel_tool_calls": true
}'
```


```python
import requests
import json
from concurrent.futures import ThreadPoolExecutor

def get_weather(city):
    # Simulate API call
    return {"city": city, "temp": 72, "conditions": "sunny"}

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Get weather for NYC, LA, and Chicago"}]
            }
        ],
        "tools": [
            {
                "type": "function",
                    "name": "get_weather",
                    "description": "Get weather for a city",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {"type": "string"}
                        },
                        "required": ["city"]
                },
                "strict": True,
                "require_approval": False
            }
        ],
        "parallel_tool_calls": True
    }
)

result = response.json()

# Execute multiple function calls in parallel
function_calls = [
    output for output in result.get('outputs', [])
    if output.get('type') == 'function_call'
]

with ThreadPoolExecutor() as executor:
    futures = []
    for call in function_calls:
        func_args = json.loads(call['function']['arguments'])
        future = executor.submit(get_weather, **func_args)
        futures.append((call, future))
    
    # Collect results
    for call, future in futures:
        result = future.result()
        print(f"{call['function']['name']}({call['function']['arguments']}) = {result}")
```


```javascript
async function getWeather(city) {
// Simulate API call
return { city, temp: 72, conditions: 'sunny' };
}

const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Get weather for NYC, LA, and Chicago' }]
      }
    ],
    tools: [
      {
        type: 'function',
          name: 'get_weather',
          description: 'Get weather for a city',
          parameters: {
            type: 'object',
            properties: {
              city: { type: 'string' }
            },
            required: ['city']
        },
        strict: true,
        require_approval: false
      }
    ],
    parallel_tool_calls: true
})
});

const result = await response.json();

// Execute multiple function calls in parallel
const functionCalls = result.outputs?.filter(o => o.type === 'function_call') || [];

const results = await Promise.all(
functionCalls.map(async (call) => {
    const funcArgs = JSON.parse(call.function.arguments);
    const result = await getWeather(funcArgs.city);
    return { call, result };
})
);

results.forEach(({ call, result }) => {
console.log(`${call.function.name}(${call.function.arguments}) =`, result);
});
```

## Agentic Tool Calling Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-5",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Get weather information for major European cities and provide a comprehensive report"}]
      }
    ],
    "functions": [
      {
        "type": "function",
        "name": "get_cities",
        "description": "Get a list of 5 cities for a specific region",
        "parameters": {
          "type": "object",
          "properties": {
            "region": {
              "type": "string",
              "enum": ["asia", "europe", "americas", "global"]
            }
          },
          "required": ["region"]
        }
      },
      {
        "type": "function",
        "name": "get_temperature",
        "description": "Get current temperature for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "parallel_tool_calls": false
}'
```


```python
import requests

# Single API call - backend handles the entire agentic loop
response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "org_abc123",
        "model": "gpt-5",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "Get weather information for major European cities and provide a comprehensive report"}]
            }
        ],
        "functions": [
            {
                "type": "function",
                "name": "get_cities",
                "description": "Get a list of 5 cities for a specific region",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "region": {
                            "type": "string",
                            "enum": ["asia", "europe", "americas", "global"]
                        }
                    },
                    "required": ["region"]
                }
            },
            {
                "type": "function",
                "name": "get_temperature",
                "description": "Get current temperature for a city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string"}
                    },
                    "required": ["city"]
                }
            }
        ],
        "parallel_tool_calls": False
    }
)

result = response.json()

# Backend automatically:
# 1. Calls get_cities("europe") → ["Paris", "London", "Berlin", "Rome", "Madrid"]
# 2. Calls get_temperature for each city (5 calls)
# 3. Generates final comprehensive report
print(result['response'])
# Output: "Here's a comprehensive weather report for major European cities:
#          Paris: 18°C, London: 15°C, Berlin: 10°C, Rome: 20°C, Madrid: 22°C..."
```


```javascript
// Single API call - backend handles the entire agentic loop
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    organization_id: 'org_abc123',
    model: 'gpt-5',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'Get weather information for major European cities and provide a comprehensive report' }]
      }
    ],
    functions: [
      {
        type: 'function',
        name: 'get_cities',
        description: 'Get a list of 5 cities for a specific region',
        parameters: {
          type: 'object',
          properties: {
            region: {
              type: 'string',
              enum: ['asia', 'europe', 'americas', 'global']
            }
          },
          required: ['region']
        }
      },
      {
        type: 'function',
        name: 'get_temperature',
        description: 'Get current temperature for a city',
        parameters: {
          type: 'object',
          properties: {
            city: { type: 'string' }
          },
          required: ['city']
        }
      }
    ],
    parallel_tool_calls: false
})
});

const result = await response.json();

// Backend automatically:
// 1. Calls get_cities("europe") → ["Paris", "London", "Berlin", "Rome", "Madrid"]
// 2. Calls get_temperature for each city (5 calls)
// 3. Generates final comprehensive report
console.log(result.response);
// Output: "Here's a comprehensive weather report for major European cities:
//          Paris: 18°C, London: 15°C, Berlin: 10°C, Rome: 20°C, Madrid: 22°C..."
```

**How Agentic Tool Calling Works:**

The backend automatically manages multi-step tool execution:

1. **Model decides to call tools** - Based on your request, the model determines which tools to call
2. **Backend executes tools** - Functions are executed server-side with built-in implementations
3. **Results fed back to model** - Tool results are automatically passed back to the model
4. **Model makes additional calls** - If needed, the model calls more tools based on previous results
5. **Final response generated** - After all necessary tool calls, the model generates the complete answer


**Benefits:**

- **Simplified API** - Single request instead of multi-turn conversation
- **Automatic orchestration** - No manual tool result handling required
- **Built-in tool execution** - Common tools (get_cities, get_temperature) executed server-side
- **Conversation history managed** - Full context preserved across tool calls
- **Thread support** - Use `threadId` for multi-turn agentic workflows


**Supported Models:**

- `gpt-5` - Sequential tool execution (one at a time)
- `gpt-4o` - Sequential tool execution
- `claude-sonnet-4-20250514` - Parallel tool execution (multiple simultaneous calls)
- `claude-3-5-sonnet-20241022` - Parallel tool execution


**Note:** Set `parallel_tool_calls: false` for GPT models to ensure sequential execution. Claude models can handle parallel calls efficiently.

## Reasoning (Unified) Example


```bash
# Works with both GPT-5 and Claude - automatic provider mapping
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-5",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Solve this complex problem: How can Switzerland achieve net-zero emissions by 2040?"}]
      }
    ],
    "reasoning": {
      "effort": "high",
      "summary": "detailed"
    }
}'

# Same request works with Claude
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "claude-sonnet-4",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Solve this complex problem: How can Switzerland achieve net-zero emissions by 2040?"}]
      }
    ],
    "reasoning": {
      "effort": "high"
    }
}'
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")

# Works with both GPT-5 and Claude using the same parameter
def query_with_reasoning(model, question, effort_level="medium"):
    response = requests.post(
        "https://api.freddy.aitronos.com/v1/model/response",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
        json={
            "organization_id": "org_abc123",
            "model": model,
            "inputs": [
                {
                    "role": "user",
                    "texts": [{"text": question}]
                }
            ],
            "reasoning": {
                "effort": effort_level,
                "summary": "detailed"  # OpenAI only, ignored by Claude
            }
        }
    )
    return response.json()

# Use with GPT-5 (maps to OpenAI reasoning)
gpt5_result = query_with_reasoning(
    "gpt-5", 
    "What are the economic implications of quantum computing?",
    effort_level="high"
)

# Use with Claude (maps to Anthropic thinking with 25,000 tokens)
claude_result = query_with_reasoning(
    "claude-sonnet-4",
    "What are the economic implications of quantum computing?",
    effort_level="high"
)
```


```javascript
const apiKey = process.env.FREDDY_API_KEY;

// Works with both GPT-5 and Claude using the same parameter
async function queryWithReasoning(model, question, effortLevel = 'medium') {
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123',
      model: model,
      inputs: [
        {
          role: 'user',
          texts: [{ text: question }]
        }
      ],
      reasoning: {
        effort: effortLevel,
        summary: 'detailed'  // OpenAI only, ignored by Claude
      }
    })
});
return await response.json();
}

// Use with GPT-5 (maps to OpenAI reasoning)
const gpt5Result = await queryWithReasoning(
'gpt-5',
'What are the economic implications of quantum computing?',
'high'
);

// Use with Claude (maps to Anthropic thinking with 25,000 tokens)
const claudeResult = await queryWithReasoning(
'claude-sonnet-4',
'What are the economic implications of quantum computing?',
'high'
);
```

**Effort Level Mapping:**

| Effort | OpenAI (GPT-5) | Anthropic (Claude) | Use Case |
|  --- | --- | --- | --- |
| `off` | Disabled | Disabled | Quick responses without reasoning |
| `low` | Minimal effort | 2,500 tokens | Simple problems, faster responses |
| `medium` | Medium effort | 10,000 tokens | Balanced analysis (default) |
| `high` | High effort | 25,000 tokens | Complex problems, thorough analysis |
| `maximum` | High effort | 50,000 tokens | Most complex problems, deepest analysis |


**Streaming Behavior:**

- **OpenAI:** Emits `reasoning.started` and `reasoning.completed` events. Reasoning content is encrypted and not streamed.
- **Anthropic:** Emits `thinking.started`, `thinking.delta`, and `thinking.completed` events with full thinking content streamed in real-time.


## System Prompt Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "system",
        "texts": [{"text": "You are a helpful Python expert. Always include code examples."}]
      },
      {
        "role": "user",
        "texts": [{"text": "How do I sort a list?"}]
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4o",
        "inputs": [
            {
                "role": "system",
                "texts": [{"text": "You are a helpful Python expert. Always include code examples."}]
            },
            {
                "role": "user",
                "texts": [{"text": "How do I sort a list?"}]
            }
        ]
    }
)
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: [
      {
        role: 'system',
        texts: [{ text: 'You are a helpful Python expert. Always include code examples.' }]
      },
      {
        role: 'user',
        texts: [{ text: 'How do I sort a list?' }]
      }
    ]
})
});
```

## With Image Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4.1-vision",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "What is in this image?"}],
        "images": [{"fileId": "file_abc123"}]
      }
    ]
}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "organization_id": "org_abc123",
    "model": "gpt-4.1-vision",
        "inputs": [
            {
                "role": "user",
                "texts": [{"text": "What is in this image?"}],
                "images": [{"fileId": "file_abc123"}]
            }
        ]
    }
)
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4.1-vision',
    inputs: [
      {
        role: 'user',
        texts: [{ text: 'What is in this image?' }],
        images: [{ fileId: 'file_abc123' }]
      }
    ]
})
});
```

## Conversation Example


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
-H "Authorization: Bearer $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "organization_id": "org_abc123",
    "model": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "Hello!"}]
      },
      {
        "role": "assistant",
        "texts": [{"text": "Hi! How can I help you today?"}]
      },
      {
        "role": "user",
        "texts": [{"text": "Tell me about Python"}]
      }
    ]
}'
```


```python
import requests

# Build conversation history
conversation = [
    {"role": "user", "texts": [{"text": "Hello!"}]},
    {"role": "assistant", "texts": [{"text": "Hi! How can I help you today?"}]},
    {"role": "user", "texts": [{"text": "Tell me about Python"}]}
]

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"model": "gpt-4o", "inputs": conversation}
)
```


```javascript
const conversation = [
{ role: 'user', texts: [{ text: 'Hello!' }] },
{ role: 'assistant', texts: [{ text: 'Hi! How can I help you today?' }] },
{ role: 'user', texts: [{ text: 'Tell me about Python' }] }
];

const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
method: 'POST',
headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
},
body: JSON.stringify({
    model: 'gpt-4o',
    inputs: conversation
})
});
```

## Response

200 OK Response

```json
{
  "id": "resp_67ccd2bed1ec8190",
  "object": "response",
  "createdAt": 1741476542,
  "status": "completed",
  "model": "gpt-4.1-2025-04-14",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you?",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 8,
    "total_tokens": 18
  }
}
```

Streaming Response

```text
event: response.created
data: {"id":"resp_abc123","status":"in_progress"}

event: response.output_item.added
data: {"index":0,"item":{"type":"message"}}

event: response.output_text.delta
data: {"index":0,"delta":"Hello"}

event: response.output_text.delta
data: {"index":0,"delta":"! How can I"}

event: response.output_text.done
data: {"text":"Hello! How can I help you?"}

event: response.completed
data: {"status":"completed"}
```

Error Responses

```json 401 Unauthorized
{
"error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
}
}
```


```json 400 Bad Request
{
"error": {
    "message": "No valid input messages found",
    "type": "invalid_request_error",
    "code": "invalid_input",
    "param": "inputs"
}
}
```


```json 403 Forbidden
{
"error": {
    "message": "Organization access denied",
    "type": "permission_error",
    "code": "insufficient_permissions",
    "param": "organization_id"
}
}
```


```json 404 Not Found
{
"error": {
    "message": "Model not found",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
}
}
```


```json 422 Validation Error
{
"error": {
    "message": "Invalid parameter value",
    "type": "invalid_request_error",
    "code": "invalid_value",
    "param": "temperature",
    "details": "temperature must be between 0 and 2"
}
}
```


```json 429 Rate Limit
{
"error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
}
}
```


```json 500 Server Error
{
"error": {
    "message": "Internal server error",
    "type": "server_error",
    "code": "internal_error"
}
}
```


```json 503 Service Unavailable
{
"error": {
    "message": "AI provider temporarily unavailable",
    "type": "service_unavailable_error",
    "code": "provider_unavailable"
}
}
```

## Related Resources

- [Function Calling Guide](/docs/documentation/core-concepts/function-calling)
- [Structured Output Guide](/docs/documentation/core-concepts/structured-output)
- [Text Generation Guide](/docs/documentation/core-concepts/text-generation)
- [Authentication Guide](/docs/api-reference/authentication)