Create a model response

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

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

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

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

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 →

inputs array required

Array of input message objects. Each message contains a role and content arrays (texts, images, audio, files). View full object →

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

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).

store boolean optional · Defaults to true

Controls whether the created thread is visible in the user's thread list. When true (default), the thread appears in the list threads API and is visible in the user interface. When false, the thread is hidden from the list threads API but remains accessible by direct thread ID lookup. This is useful for internal operations, background tasks, or temporary threads that shouldn't clutter the user's conversation history. Learn more

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.

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

output_mode string optional · Defaults to text

Controls the format of the model's response output. Determines how the response content is structured and returned.

json_schema object optional

JSON schema definition for structured output validation. Required when output_mode is set to json_schema. Defines the exact structure the model must follow in its response.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" },
    "email": { "type": "string" }
  },
  "required": ["name", "email"]
}

include array optional

Specify additional data to include in the response. Each value expands specific parts of the output with extra information. Learn more

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

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

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

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

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

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 tool_choice parameter. Learn more

["search_documents", "list_files", "get_file_content"]

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

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

System Tools

system_tools object optional

Configuration for built-in system tools provided by Aitronos. These extend model capabilities beyond the custom tools in the tools array. System tools are enabled/disabled via mode settings rather than being defined inline.

Example:

{
  "inputs": [{"role": "user", "texts": [{"text": "Generate an image of a sunset over mountains"}]}],
  "model": "ftg-3.0",
  "system_tools": {
    "image_operations": {"mode": "on"}
  }
}

tool_choice 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

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

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

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

Returns

Non-streaming (stream: false): Returns a complete Response object after generation finishes.

Streaming (stream: true): Returns Streaming event objects as Server-Sent Events (SSE). Each event contains a specific event type and data payload showing the model's progress, tool calls, and generated content in real-time.

curl https://api.aitronos.com/v1/model/response \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_abc123",
    "model": "ftg-3.0",
    "inputs": [
      {
        "role": "user",
        "texts": [
          {
            "text": "What is the capital of France?"
          }
        ]
      }
    ]
  }'

Response:

{
  "success": true,
  "thread_id": "thread_xyz789",
  "response": "The capital of France is Paris. It is located in the north-central part of the country and is known for its art, culture, and iconic landmarks like the Eiffel Tower.",
  "response_id": "resp_abc123",
  "is_summarized": false
}