Skip to main content
POST
  • OpenAI-compatible Responses API format
  • Supports plain text input and structured multimodal input
  • Supports tools such as web search and function calling when available on the selected model
  • Supports both complete JSON responses and SSE streaming

Usage Examples

Basic Text

Multimodal Input

Streaming

cURL

Streaming

When stream is true, the endpoint returns text/event-stream. Events are sent as SSE data: lines and end with data: [DONE]. Common event types include:
  • response.created
  • response.output_item.added
  • response.output_text.delta
  • response.output_text.done
  • response.completed
  • response.failed

Notes

  • Tool availability depends on the selected model. If a model does not support a requested tool, the request may return an error.
  • For image input, public URLs must be reachable by the model service.
  • Base64 images must use the full Data URI prefix, for example data:image/png;base64,.
  • Content block order can affect model understanding. Put text instructions before images when possible.

Response

Non-streaming requests return the Responses object directly, without a code / data wrapper. The generated text is in output[].content[] items with type: "output_text".

Streaming

With "stream": true, the response is text/event-stream. Each event is a data: line whose JSON type names the event, and the stream ends with data: [DONE]:
  • Concatenate response.output_text.delta events to build the text.
  • response.completed carries the final response object, including usage.
  • Events are sent as data: lines only, without separate event: lines. Read the event name from type.

Errors

  • 401: missing or invalid API key.
  • 400: invalid parameters, or the model does not support Responses. The message lists the supported URIs.
  • 404: unknown model id.
See Error Codes for example bodies, and LLM Models for which models support this format.

Authorizations

Authorization
string
header
required

All API endpoints require Bearer Token authentication.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Body

application/json
model
string
required

Model name.

Example:

"gpt-5.2"

input
required

Plain text input or an array of structured input items.

Example:

"Write a product tagline in one sentence."

instructions
string

System or developer instructions that guide the model response.

tools
object[]

Tools available to the model. Tool support depends on the selected model.

tool_choice

Controls how the model selects tools.

Example:

"auto"

max_output_tokens
integer

Maximum number of output tokens to generate.

Required range: x >= 1
Example:

200

max_tokens
integer

Legacy compatibility field for maximum output tokens.

Required range: x >= 1
Example:

200

stream
boolean
default:false

Whether to use streaming output in SSE format.

Example:

false

store
boolean

Whether the response should be stored when supported.

Example:

false

reasoning
object

Reasoning configuration, when supported by the selected model.

Example:
text
object

Text output configuration, such as structured output format options when supported.

metadata
object

Custom metadata key-value pairs for your request.

previous_response_id
string

Previous response ID for continuing a conversation.

include
string[]

Additional response fields to include, when supported.

parallel_tool_calls
boolean

Whether the model may call multiple tools in parallel.

truncation
string

Truncation behavior for long context, when supported.

Example:

"auto"

user
string

End-user identifier for abuse monitoring and request tracing.

background
boolean

Whether to run the response in background mode, when supported.

service_tier
string

Service tier selection, when supported.

Example:

"auto"

prompt
object

Prompt object, when supported by the selected model.

temperature
number

Controls output randomness, range 0-2.

Required range: 0 <= x <= 2
Example:

1

top_p
number

Nucleus sampling parameter, range 0-1.

Required range: 0 <= x <= 1
Example:

1

Response

Response created

Response object.

id
string
Example:

"resp_9876543210"

object
string
Example:

"response"

created_at
integer
Example:

1677652288

status
string
Example:

"completed"

model
string
Example:

"gpt-5.2"

output
object[]
usage
object

Token usage statistics.