> ## Documentation Index
> Fetch the complete documentation index at: https://docs.znapai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Responses generation

***

## Request

<CodeGroup>
  ```shellscript cURL theme={null}
  curl --location 'https://api.znapai.com/v1/responses' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $ZnapAI_API_KEY' \
  --header 'spend-logs-metadata: {"user_id": "user-123", "project_id": "proj_abc", "env": "production"}' \
  --data '{
      "model": "gpt-5-mini",
      "input": [
        {
          "role": "user",
          "content": [
            {
              "type": "input_text",
              "text": "Introduce artificial intelligence"
            }
          ]
        }
      ]
    }'
  ```

  ```python OpenAI SDK (Python) theme={null}
  import openai
  client = openai.OpenAI(
      api_key="$ZnapAI_API_KEY",
      base_url="https://api.znapai.com/"
  )

  response = client.responses.create(
      model="gpt-5-mini",
      input=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "input_text",
                      "text": "Introduce artificial intelligence"
                  }
              ]
          }
      ]
  )

  print(response)
  ```

  ```javascript OpenAI SDK (JS) theme={null}
  import OpenAI from "openai";
  const openai = new OpenAI({
    apiKey: "$ZnapAI_API_KEY",
    baseURL: "https://api.znapai.com/"
  });

  const response = await openai.responses.create({
    model: "gpt-5-mini",
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Introduce artificial intelligence",
          },
        ],
      },
    ],
  });

  console.log(response);
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "id": "resp_01J8Y...",
  "object": "response",
  "created_at": 1741451370,
  "model": "gpt-5-mini",
  "status": "completed",
  "output": [
    {
      "id": "msg_01J8Y...",
      "role": "assistant",
      "status": "completed",
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Artificial intelligence (AI) refers to the simulation of human intelligence in machines that are programmed to think and learn like humans. These machines can perform tasks such as learning, reasoning, problem-solving, perception, and language understanding."
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 45,
    "total_tokens": 57
  }
}
```

***

## Parameters

<ParamField path="spend-logs-metadata" type="header" required={false}>
  An optional header used for spend logging metadata, containing JSON properties like `user_id`, `project_id`, and `env`.
</ParamField>

<ParamField path="model" type="string" required>
  Name of the model to use (for example: `gpt-5-mini`). To see the complete list of supported models, visit: [https://znapai.com/models/chat](https://znapai.com/models/chat)
</ParamField>

<ParamField path="input" type="string | array" required>
  The user input. Can be a plain string for simple text prompts, or an array of message objects for multimodal and multi-turn conversations.

  <Expandable title="input[]" defaultOpen="True">
    <ResponseField name="role" type="string" required>
      The role of the message creator.

      Options:

      * `user`: User message
      * `assistant`: AI response (for multi-turn conversations)
      * `system`: System prompt to guide AI behavior

      Default: `"user"`
    </ResponseField>

    <ResponseField name="content" type="array" required>
      An ordered list of content parts. Supports text, images, and files in the same message.

      <Expandable title="content[]" defaultOpen="True">
        <ResponseField name="type" type="string" required>
          The content type. Options:

          * `input_text`: Text input
          * `input_image`: Image input (URL or base64)
          * `input_file`: File input (PDF, DOCX, TXT, CSV, etc.)
        </ResponseField>

        <ResponseField name="text" type="string">
          The text content. Required if `type` is `input_text`.
        </ResponseField>

        <ResponseField name="image_url" type="string">
          The image URL or base64 data URI. Required if `type` is `input_image`.

          Supports two formats:

          1. **Full image URL**: Publicly accessible URL (e.g., `https://example.com/image.jpg`)
          2. **Base64 format**: Complete Data URI (e.g., `data:image/jpeg;base64,{base64_data}`)

          Supported formats: `jpeg`, `png`, `gif`, `webp`.
        </ResponseField>

        <ResponseField name="file_url" type="string">
          A publicly accessible URL to a file. Required if `type` is `input_file`.

          Supported formats: `pdf`, `docx`, `txt`, `csv`, and more.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="temperature" type="number">
  Controls output randomness between 0 and 2. Lower values (like `0.2`) make the output more deterministic, higher values (like `1.8`) make it more creative.

  Default: `1.0`
</ParamField>

<ParamField path="max_tokens" type="integer">
  The maximum number of tokens to generate. Different models have different maximum limits.
</ParamField>

<ParamField path="stream" type="boolean">
  Whether to stream the response as it is generated (SSE format).

  Default: `false`
</ParamField>

<ParamField path="top_p" type="number">
  Controls diversity via nucleus sampling (range 0 to 1). Recommended to set either `temperature` or `top_p`, but not both.

  Default: `1.0`
</ParamField>

<ParamField path="reasoning" type="object">
  Controls reasoning effort for supported models (e.g. `gemini-2.5-flash`, `o3`).

  <Expandable title="reasoning" defaultOpen="False">
    <ResponseField name="effort" type="string">
      The reasoning effort level. Options: `"low"`, `"medium"`, `"high"`.

      Higher effort produces more thorough reasoning but increases latency and token usage.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="tools" type="array">
  A list of tools available for the model to extend its capabilities.

  <Expandable title="tools[]" defaultOpen="True">
    <ResponseField name="type" type="string" required>
      The tool type to enable. Options:

      * `web_search_preview`: Real-time internet search
      * `function`: Call custom functions
      * `remote_mcp`: Connect to remote Model Context Protocol services
    </ResponseField>

    <ResponseField name="name" type="string">
      The function name. Required when `type` is `"function"`.
    </ResponseField>

    <ResponseField name="description" type="string">
      A description of what the function does. Required when `type` is `"function"`.
    </ResponseField>

    <ResponseField name="parameters" type="object">
      JSON Schema definition of the function's parameters. Required when `type` is `"function"`.

      <Expandable title="parameters">
        <ResponseField name="type" type="string">
          The schema type. Usually `"object"`.
        </ResponseField>

        <ResponseField name="properties" type="object">
          A map of parameter names to their schema definitions.
        </ResponseField>

        <ResponseField name="required" type="array">
          List of required parameter names.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

***

## Usage examples

### PDF / File understanding

Upload or reference a document and ask questions about it.

```json theme={null}
{
  "model": "gpt-4.1",
  "input": [{
    "role": "user",
    "content": [
      {
        "type": "input_file",
        "file_url": "https://example.com/report.pdf"
      },
      {
        "type": "input_text",
        "text": "Summarize this document"
      }
    ]
  }]
}
```

### Advanced reasoning

Use higher reasoning effort for complex tasks.

```json theme={null}
{
  "model": "gemini-2.5-flash",
  "reasoning": {"effort": "high"},
  "input": "Design a scalable architecture for a multi-tenant CRM SaaS."
}
```

### Function calling

Allow the model to invoke custom functions.

```json theme={null}
{
  "model": "gpt-5-mini",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  ],
  "input": "What is the weather in Delhi?"
}
```

### Web search

Enable live web search capabilities.

```json theme={null}
{
  "model": "gpt-5-mini",
  "tools": [{"type": "web_search_preview"}],
  "input": "What are the latest AI announcements this week?"
}
```

### Image understanding

Analyze images and answer questions about them.

```json theme={null}
{
  "model": "gpt-5-mini",
  "input": [{
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Describe this image"
      },
      {
        "type": "input_image",
        "image_url": "https://example.com/image.jpg"
      }
    ]
  }]
}
```

***

## Params to Avoid

| Param                 | Reason                                                                                                     |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `messages`            | The Responses API uses `input` instead of `messages`. Sending `messages` will result in an error.          |
| `response_format`     | Use structured outputs parameters defined for the Responses API instead of the standard `response_format`. |
| `n`                   | Generating multiple choices is not supported by the Responses API.                                         |
| `stream_options`      | Not supported by this endpoint.                                                                            |
| `presence_penalty`    | Not supported by this endpoint.                                                                            |
| `frequency_penalty`   | Not supported by this endpoint.                                                                            |
| `logit_bias`          | Not supported by this endpoint.                                                                            |
| `logprobs`            | Not supported by this endpoint.                                                                            |
| `top_logprobs`        | Not supported by this endpoint.                                                                            |
| `seed`                | Not supported by this endpoint.                                                                            |
| `spend-logs-metadata` | This metadata must be passed as an HTTP header, not in the JSON request body                               |