curl --request POST \
--url https://api.poyo.ai/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "gpt-5.2",
"input": "Write a product tagline in one sentence.",
"max_output_tokens": 120
}
'{
"id": "resp_9876543210",
"object": "response",
"created_at": 1677652288,
"status": "completed",
"model": "gpt-5.2",
"output": [
{
"id": "msg_123",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Launch faster with a smarter AI workspace built for teams."
}
]
}
],
"usage": {
"input_tokens": 12,
"output_tokens": 14,
"total_tokens": 26
}
}{
"error": {
"message": "Model not found: no-such-model",
"type": "invalid_request_error",
"code": "model_not_found"
}
}API Formats
Responses
The Responses API is an OpenAI-compatible endpoint for plain text or structured image input. Tool calls and server-sent event streaming are available when the selected model supports them.
POST
/
v1
/
responses
curl --request POST \
--url https://api.poyo.ai/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "gpt-5.2",
"input": "Write a product tagline in one sentence.",
"max_output_tokens": 120
}
'{
"id": "resp_9876543210",
"object": "response",
"created_at": 1677652288,
"status": "completed",
"model": "gpt-5.2",
"output": [
{
"id": "msg_123",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Launch faster with a smarter AI workspace built for teams."
}
]
}
],
"usage": {
"input_tokens": 12,
"output_tokens": 14,
"total_tokens": 26
}
}{
"error": {
"message": "Model not found: no-such-model",
"type": "invalid_request_error",
"code": "model_not_found"
}
}- 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
{
"model": "gpt-5.2",
"input": "Write a product tagline in one sentence.",
"max_output_tokens": 120
}
Multimodal Input
{
"model": "gpt-5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Describe this image in one paragraph."
},
{
"type": "input_image",
"image_url": "https://example.com/image.jpg"
}
]
}
],
"max_output_tokens": 300
}
Web Search
{
"model": "gpt-5",
"input": "Use web search to find the latest product update on poyo.ai. Reply with the title and URL only.",
"tools": [
{
"type": "web_search_preview"
}
],
"tool_choice": "auto",
"max_output_tokens": 2000
}
Streaming
{
"model": "gpt-5.2",
"input": "Write a 100-word product introduction.",
"max_output_tokens": 200,
"stream": true,
"store": false
}
cURL
curl "https://api.poyo.ai/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer PoYo_API_KEY" \
-d '{
"model": "gpt-5.2",
"input": "Write a product tagline in one sentence.",
"max_output_tokens": 120
}'
Streaming
Whenstream 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.createdresponse.output_item.addedresponse.output_text.deltaresponse.output_text.doneresponse.completedresponse.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 acode / 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]:
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_...","status":"in_progress",...}}
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"type":"message",...}}
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_...","delta":"OK"}
data: {"type":"response.output_text.done","sequence_number":6,"item_id":"msg_...","text":"OK"}
data: {"type":"response.completed","sequence_number":9,"response":{"id":"resp_...","status":"completed","usage":{...}}}
data: [DONE]
- Concatenate
response.output_text.deltaevents to build the text. response.completedcarries the final response object, includingusage.- Events are sent as
data:lines only, without separateevent:lines. Read the event name fromtype.
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.
Authorizations
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:
Authorization: Bearer YOUR_API_KEY
Body
application/json
Text output configuration, such as structured output format options when supported.