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

spend-logs-metadata

header

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

model

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

input

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.

Hide input[]

role

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"

content

array

required

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

Hide content[]

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

text

string

The text content. Required if type is input_text.

image_url

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.

file_url

string

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

temperature

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

max_tokens

integer

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

stream

boolean

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

top_p

number

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

reasoning

object

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

Hide reasoning

effort

string

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

tools

array

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

Hide tools[]

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

name

string

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

description

string

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

parameters

object

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

Show parameters

type

string

The schema type. Usually "object".

properties

object

A map of parameter names to their schema definitions.

required

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