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

# Responses

> A unified multimodal response interface supporting JSON mode, tool sequences, and mixed text-plus-image input.

`POST /v1/responses` is OpenAI's next-generation unified interface. It can mix text, images, and other input types in a single request and return results in a structured format.

## Request example

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/responses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Summarize the key points of the attachment"}
        ]
      }
    ],
    "response_format": {"type": "json_schema"}
  }'
```

## Streaming and compatibility

* Streaming output: set `stream: true` to receive server-sent events (SSE) increments. When you need to stay compatible with the Chat Completions streaming format, you can convert on the SSE client side (GregAPI has built-in backward-compatibility handling).
* Tool events: tool calls appear in the stream as `response.output_item.added`; the stream closes with aggregated `usage` token statistics.

## Tips and notes

* The `input` field can be a string or a composite array; an array is recommended so you can mix text, images, file references, and more.
* Conversation history can be continued by adding multiple `role`/`content` segments to `input`.
* `response_format` supports `json_schema`, `text`, and other options. Combined with GregAPI's flow-control strategy, it enables structured automation.
* For tool calls, declare optional functions in `tools`; results appear in the `tool_calls` field of `output`.
* Billing note: when tools such as Web Search Preview, Code Interpreter, or File Search are enabled, GregAPI attaches extra billing metadata in `usage` for reconciliation.


## OpenAPI

````yaml openapi/llm-en.yaml POST /v1/responses
openapi: 3.0.3
info:
  title: GregAPI Large Language Models
  version: 1.0.0
  description: >-
    Large language model (LLM) endpoints behind the GregAPI unified gateway,
    covering general chat completion, multi-modal responses, and native
    message/generation protocols.
servers:
  - url: https://api.gregapi.com
security:
  - bearerAuth: []
paths:
  /v1/responses:
    post:
      summary: Responses
      description: >-
        A unified multi-modal response interface that mixes text, images, and
        other inputs in a single request and returns structured results, with
        JSON mode and tool sequences.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
              properties:
                model:
                  type: string
                  description: Model name
                input:
                  type: array
                  description: Input messages, a string or composite array
                response_format:
                  type: object
                  description: Output format
                stream:
                  type: boolean
                  description: Whether to stream output
                tools:
                  type: array
                  description: Optional tool declarations
            example:
              model: gpt-4.1
              input:
                - role: user
                  content:
                    - type: text
                      text: Summarize the attachment.
              response_format:
                type: json_schema
      responses:
        '200':
          description: Successful structured response
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.