OpenAI Responses generation - ZnapAI Documentation

Request

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"
          }
        ]
      }
    ]
  }'

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)

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

Response

{
  "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

header

An optional header used for spend logging metadata, containing JSON properties like user_id, project_id, and env.

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

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.

Show input[]

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"

array

required

An ordered list of content parts. Supports text, images, and files in the same message.

Show content[]

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

string

The text content. Required if type is input_text.

string

The image URL or base64 data URI. Required if type is input_image.Supports two formats:

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

Supported formats: jpeg, png, gif, webp.

string

A publicly accessible URL to a file. Required if type is input_file.Supported formats: pdf, docx, txt, csv, and more.

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

integer

The maximum number of tokens to generate. Different models have different maximum limits.

boolean

Whether to stream the response as it is generated (SSE format).Default: false

number

Controls diversity via nucleus sampling (range 0 to 1). Recommended to set either temperature or top_p, but not both.Default: 1.0

object

Controls reasoning effort for supported models (e.g. gemini-2.5-flash, o3).

Show reasoning

string

The reasoning effort level. Options: "low", "medium", "high".Higher effort produces more thorough reasoning but increases latency and token usage.

array

A list of tools available for the model to extend its capabilities.

Show tools[]

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

string

The function name. Required when type is "function".

string

A description of what the function does. Required when type is "function".

object

JSON Schema definition of the function’s parameters. Required when type is "function".

Show parameters

string

The schema type. Usually "object".

object

A map of parameter names to their schema definitions.

array

List of required parameter names.

Usage examples

PDF / File understanding

Upload or reference a document and ask questions about it.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

​Request

​Response

​Parameters

​Usage examples

​PDF / File understanding

​Advanced reasoning

​Function calling

​Web search

​Image understanding

​Params to Avoid

Request

Response

Parameters

Usage examples

PDF / File understanding

Advanced reasoning

Function calling

Web search

Image understanding

Params to Avoid