Text API

Chat, Legacy Completions, and Responses; supports SSE streaming

The Text API provides Chat, Legacy text completion, and Responses. All three support non-streaming JSON and SSE streaming.

Overview

The Guid AI gateway exposes three text endpoints. Choose by scenario:

Endpoint	Use when	Endpoint type
`POST /v1/chat/completions`	General chat, tool calling, multimodal input (images, etc.), streaming SSE	`openai`
`POST /v1/completions`	Legacy text completion (prompt → continuation)	`openai`
`POST /v1/responses`	Multi-turn Responses, reasoning, structured output, tool calling	`openai-response`

Selection tips:

Most new projects should prefer Chat Completions (/v1/chat/completions).
Use Completions (/v1/completions) only for single-prompt continuation or legacy SDK compatibility.
Use Responses (/v1/responses) when you need previous_response_id multi-turn context or Responses structured output.

Prerequisite: model must appear in the Models API list and include the matching endpoint type in supported_endpoint_types.

Conventions: Auth, Base URL, Content-Type, etc. are covered in Common Conventions. Error formats are in Common Conventions.

Endpoints

Method	Path	Description
POST	`/v1/chat/completions`	Chat (supports SSE streaming)
POST	`/v1/completions`	Text completion
POST	`/v1/responses`	Responses chat

POST `/v1/chat/completions`

Chat completions with non-streaming JSON and SSE streaming.

Auth: Bearer Token

Content-Type: application/json

Request body

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, who are you?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

Request fields

Field	Type	Required	Description
`model`	string	Yes	Model ID
`messages`	array	Yes	Conversation message list
`messages[].role`	string	Yes	`system` / `user` / `assistant` / `tool`
`messages[].content`	string / array	Yes	Text or multimodal content
`stream`	boolean	No	When `true`, returns an SSE stream; default `false`
`temperature`	number	No	Sampling temperature, 0–2
`top_p`	number	No	Nucleus sampling, 0–1
`max_tokens`	integer	No	Max output tokens
`max_completion_tokens`	integer	No	Max completion tokens
`stop`	string / array	No	Stop sequences
`tools`	array	No	Tool definitions
`tool_choice`	string / object	No	Tool selection strategy
`response_format`	object	No	Structured output format
`stream_options`	object	No	Streaming options, e.g. `{ "include_usage": true }`

Multimodal message example (image input):

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's in this image?" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/image.jpg" }
        }
      ]
    }
  ]
}

Request example (curl)

Non-streaming:

curl https://www.guid.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, who are you?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

Streaming (SSE):

curl -N https://www.guid.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Response body (non-streaming)

HTTP 200, Content-Type: application/json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm an AI assistant. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 15,
    "total_tokens": 43
  }
}

Response fields

Field	Type	Description
`id`	string	Response ID, e.g. `chatcmpl-xxx`
`object`	string	Always `chat.completion`
`created`	integer	Unix timestamp (seconds)
`model`	string	Model actually used
`choices`	array	Generation results; length equals request `n` (default 1)
`choices[].index`	integer	Result index, starting at 0
`choices[].message.role`	string	Always `assistant`
`choices[].message.content`	string / null	Reply text; may be `null` for tool calls
`choices[].message.tool_calls`	array	Tool call list (when tools are enabled)
`choices[].message.tool_calls[].id`	string	Tool call ID
`choices[].message.tool_calls[].type`	string	Always `function`
`choices[].message.tool_calls[].function.name`	string	Function name
`choices[].message.tool_calls[].function.arguments`	string	Function arguments as a JSON string
`choices[].message.reasoning_content`	string	Reasoning text (reasoning models)
`choices[].finish_reason`	string	Stop reason; see table below
`usage`	object	Token usage; see Shared response objects

finish_reason values:

Value	Description
`stop`	Natural stop or hit a stop sequence
`length`	Reached `max_tokens` limit
`tool_calls`	Model initiated a tool call
`content_filter`	Content blocked by safety policy

Tool call response example:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\":\"Beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 20,
    "total_tokens": 70
  }
}

Response body (streaming)

HTTP 200, Content-Type: text/event-stream

With "stream": true in the request body, the server pushes SSE events. Each message looks like:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":28,"completion_tokens":15,"total_tokens":43}}

data: [DONE]

Streaming chunk fields

Field	Type	Description
`id`	string	Same ID as the final response
`object`	string	Always `chat.completion.chunk`
`created`	integer	Unix timestamp (seconds)
`model`	string	Model used
`system_fingerprint`	string	System fingerprint (some models)
`choices[].index`	integer	Result index
`choices[].delta.role`	string	First chunk may include `assistant`
`choices[].delta.content`	string	Incremental text fragment
`choices[].delta.reasoning_content`	string	Incremental reasoning text (reasoning models)
`choices[].delta.tool_calls`	array	Incremental tool call fragments
`choices[].finish_reason`	string / null	Stop reason on the last chunk; otherwise `null`
`usage`	object	Appears only on the last chunk (requires `stream_options.include_usage=true`)

Streaming end marker: final line data: [DONE].

POST `/v1/completions`

Legacy text completion endpoint.

Auth: Bearer Token

Content-Type: application/json

Request body

{
  "model": "gpt-4o",
  "prompt": "Say this is a test",
  "max_tokens": 100,
  "temperature": 0.7,
  "stream": false
}

Request fields

Field	Type	Required	Description
`model`	string	Yes	Model ID
`prompt`	string / array	Yes	Prompt text
`max_tokens`	integer	No	Max output tokens
`temperature`	number	No	Sampling temperature
`top_p`	number	No	Nucleus sampling
`n`	integer	No	Number of completions; default 1
`stream`	boolean	No	Whether to stream
`stop`	string / array	No	Stop sequences

Request example (curl)

Non-streaming:

curl https://www.guid.ai/v1/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Say this is a test",
    "max_tokens": 100,
    "temperature": 0.7,
    "stream": false
  }'

Streaming (SSE):

curl -N https://www.guid.ai/v1/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Say this is a test",
    "stream": true
  }'

Response body (non-streaming)

HTTP 200

{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "text": "This is indeed a test.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 6,
    "total_tokens": 11
  }
}

Response fields

Field	Type	Description
`id`	string	Response ID, e.g. `cmpl-xxx`
`object`	string	Always `text_completion`
`created`	integer	Unix timestamp (seconds)
`model`	string	Model used
`choices`	array	Generation results
`choices[].index`	integer	Result index
`choices[].text`	string	Completion text
`choices[].finish_reason`	string	`stop` / `length` / `content_filter`
`usage`	object	Token usage; see Shared response objects

Response body (streaming)

data: {"id":"cmpl-abc123","object":"text_completion","created":1712697600,"choices":[{"index":0,"text":"This","finish_reason":null}]}

data: {"id":"cmpl-abc123","object":"text_completion","created":1712697600,"choices":[{"index":0,"text":" is","finish_reason":null}]}

data: [DONE]

Streaming chunk fields

Field	Type	Description
`id`	string	Response ID
`object`	string	Always `text_completion`
`created`	integer	Unix timestamp (seconds)
`choices[].index`	integer	Result index
`choices[].text`	string	Incremental text fragment
`choices[].finish_reason`	string / null	Stop reason on the last chunk

POST `/v1/responses`

Responses chat endpoint supporting multi-turn conversation, tool calling, reasoning, and more.

Auth: Bearer Token

Content-Type: application/json

Request body

{
  "model": "gpt-4o",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Explain quantum computing in one sentence."
        }
      ]
    }
  ],
  "temperature": 0.7,
  "max_output_tokens": 1024,
  "stream": false
}

Request fields

Field	Type	Required	Description
`model`	string	Yes	Model ID
`input`	string / array	Yes	Input content; string or message array
`instructions`	string	No	System instructions
`temperature`	number	No	Sampling temperature
`max_output_tokens`	integer	No	Max output tokens
`stream`	boolean	No	Whether to stream
`tools`	array	No	Tool definitions
`tool_choice`	string / object	No	Tool selection strategy
`previous_response_id`	string	No	Previous response ID for multi-turn chat
`store`	boolean	No	Whether to store the conversation
`metadata`	object	No	Custom metadata

Request example (curl)

Non-streaming:

curl https://www.guid.ai/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Explain quantum computing in one sentence."}
        ]
      }
    ],
    "temperature": 0.7,
    "max_output_tokens": 1024,
    "stream": false
  }'

Streaming (SSE):

curl -N https://www.guid.ai/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Hello",
    "stream": true
  }'

Response body (non-streaming)

HTTP 200

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1712697600,
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum computing uses quantum bits that can exist in superposition to perform certain calculations exponentially faster than classical computers.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 28,
    "total_tokens": 43
  },
  "temperature": 0.7,
  "top_p": 1.0
}

Response fields

Field	Type	Description
`id`	string	Response ID, e.g. `resp_xxx`
`object`	string	Always `response`
`created_at`	integer	Unix timestamp (seconds)
`status`	string	Response status; see table below
`model`	string	Model used
`output`	array	Output item list
`output[].type`	string	Output type; see table below
`output[].id`	string	Output item ID
`output[].status`	string	Output item status
`output[].role`	string	Role (`assistant` for `message` type)
`output[].content`	array	Content block list
`output[].content[].type`	string	Content type, e.g. `output_text`
`output[].content[].text`	string	Text content
`output[].content[].annotations`	array	Annotation/citation list
`output[].call_id`	string	Tool call ID (`function_call` type)
`output[].name`	string	Function name (`function_call` type)
`output[].arguments`	string / object	Function arguments (`function_call` type)
`output[].quality`	string	Image quality (`image_generation_call` type)
`output[].size`	string	Image size (`image_generation_call` type)
`instructions`	string	System instructions (echo)
`temperature`	number	Sampling temperature (echo)
`top_p`	number	Nucleus sampling (echo)
`max_output_tokens`	integer	Max output tokens (echo)
`previous_response_id`	string	Previous response ID
`parallel_tool_calls`	boolean	Whether parallel tool calls are enabled
`store`	boolean	Whether the conversation is stored
`metadata`	object	Custom metadata
`incomplete_details.reason`	string	Incomplete reason (when `status=incomplete`)
`error`	object	Error info (when `status=failed`)
`usage`	object	Token usage; see Shared response objects

status values:

Value	Description
`completed`	Generation finished
`in_progress`	Generation in progress
`failed`	Generation failed
`incomplete`	Incomplete due to token limit or similar

output[].type values:

Value	Description
`message`	Assistant text message
`function_call`	Function/tool call
`image_generation_call`	Image generation call
`web_search_call`	Web search call

Response body (streaming)

HTTP 200, Content-Type: text/event-stream

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}

data: {"type":"response.output_text.delta","delta":"Quantum","output_index":0,"content_index":0}

data: {"type":"response.output_text.delta","delta":" computing","output_index":0,"content_index":0}

data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"input_tokens":15,"output_tokens":28,"total_tokens":43}}}

data: [DONE]

Streaming event fields

Field	Type	Description
`type`	string	Event type; see table below
`response`	object	Full or partial response object
`delta`	string	Incremental text
`output_index`	integer	Output item index
`content_index`	integer	Content block index
`item`	object	Added/completed output item
`item_id`	string	Output item ID
`part`	object	Reasoning summary fragment

Common type values:

Value	Description
`response.created`	Response created
`response.output_text.delta`	Text delta
`response.output_item.added`	Output item added
`response.output_item.done`	Output item completed
`response.function_call_arguments.delta`	Function arguments delta
`response.function_call_arguments.done`	Function arguments completed
`response.completed`	Response completed

Models API

List models visible to an API Key and the endpoint types each model supports

Images API

Text-to-image and image-to-image/edit; synchronously returns image URLs or Base64 data