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 optional

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 → 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

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 gpt-4o

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 (text string or structured content blocks), with optional file attachments. View full object →

Thread and Context

thread_id string optional

The ID of 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_id is provided, a new thread is automatically created for this request. The response will include the new thread ID, 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.

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

space_id string optional

ID of the space to associate the thread with. When provided, new threads are automatically added to the specified space. The space's dedicated vector store and any additional attached vector stores are merged into the conversation's knowledge sources, enabling shared context across all threads in the space. This is idempotent — passing the same space_id on subsequent messages to the same thread has no effect. Learn more about spaces

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.

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.

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

vector_store_ids array optional

Vector store IDs for file search/RAG. Enables searching uploaded files to answer queries.

edit_message_id string optional

Message ID to edit. Soft-deletes this message and all subsequent messages, then creates a new branch.

previous_message_id string optional

Message ID to branch from. Soft-deletes all messages after this message (keeping it), then continues from that point.

workflow_id string optional

Workflow/Flow ID from FlowPlate. Used to associate threads with specific workflow automations.

Reasoning

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 custom tools the model can invoke during response generation. Supports custom function calls, personal connectors, and MCP server tools. Tool usage can be controlled via the tool_choice parameter. For built-in capabilities like web search, file search, and code execution, use the system_tools parameter instead. Learn more

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

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

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", "content": "Generate an image of a sunset over mountains"}],
  "model": "gpt-4o",
  "system_tools": {
    "image_operations": {"mode": "on"}
  }
}

Output Format

Response Parameters

temperature number optional

Controls output randomness and creativity. Values range from 0.0 to 1.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.

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": "gpt-4o",
    "inputs": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

Response:

{
  "success": true,
  "thread_id": "thrd_xyz789",
  "response": [
    {
      "type": "text",
      "text": "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,
  "stop_reason": "end_turn"
}