General Chat API

Unified chat API interface supporting all text generation models

POST /v1/chat/completions

General Chat API

cURL

curl --request POST \
  --url https://api.poyo.ai/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "system",
      "content": "You are a structured output assistant. Reply with JSON only."
    },
    {
      "role": "user",
      "content": "Generate a paginated list response example with fields items, page, page_size, total and sample values."
    }
  ]
}
'

200

{
  "code": 200,
  "data": {
    "id": "chatcmpl-9876543210",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-5.2",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "The history of artificial intelligence (AI) dates back to the 1950s..."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 28,
      "completion_tokens": 320,
      "total_tokens": 348
    }
  }
}

• Unified chat API interface supporting all text generation models
• Select different AI models via the model parameter
• Compatible with OpenAI Chat Completions API format

Authorizations

Authorization · string · required

All API endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer PoYo_API_KEY

Body

model · string · required

Model name. Example: gpt-5.2, claude-sonnet-4-5-20250929, gemini-3-flash-preview

messages · array · required

List of conversation messages

Show Message object structure

role · enum<string> · default: "user" · required

Role type

• user - User message
• assistant - AI response (for multi-turn)
• system - System prompt

content · string · required

Message content

Your question or message

Example:

[{"role": "user", "content": "Explain vector databases in one sentence."}]

Advanced usage:

Add system prompt (to define AI behavior):

[
  {"role": "system", "content": "You are an API design advisor. Respond with a short bullet list only."},
  {"role": "user", "content": "Give 5 design suggestions for a file upload endpoint."}
]

Multi-turn conversation (with context):

[
  {"role": "user", "content": "Name a feature that turns meeting notes into a weekly report."},
  {"role": "assistant", "content": "Suggestions: Weekly Brief or AutoReport."},
  {"role": "user", "content": "Provide 3 more formal names."}
]

temperature · number

Controls output randomness, range 0-2

• Lower values (e.g., 0.2) make output more deterministic
• Higher values (e.g., 1.8) make output more random

Default: 1.0

max_tokens · integer

Maximum number of tokens to generate

Different models have different maximum limits, please refer to specific model documentation

stream · boolean

Whether to use streaming output

• true: Streaming response (SSE format)
• false: Complete response at once

Default: false

top_p · number

Nucleus sampling parameter, range 0-1

Controls diversity of generated text, recommend using either this or temperature

Default: 1.0

frequency_penalty · number

Frequency penalty, range -2.0 to 2.0

Positive values reduce the likelihood of repeating the same words

Default: 0

presence_penalty · number

Presence penalty, range -2.0 to 2.0

Positive values increase the likelihood of talking about new topics

Default: 0

stop · string or array

Stop sequences

Up to 4 sequences where generation will stop when encountered

n · integer

Number of completions to generate

Default: 1

Note: Must enter a plain number (e.g., 1), do not use quotes or it will cause an error

Response

id · string

Unique identifier for the response

object · string

Object type, fixed as chat.completion

created · integer

Creation timestamp

model · string

The actual model name used

choices · array

List of generated responses

Show Properties

index · integer

Choice index

message · object

Message content

Show Properties

role · string

Role type (assistant)

content · string

Generated text content

finish_reason · string

Reason for completion

Possible values:

• stop - Natural completion
• length - Maximum length reached
• content_filter - Content filtered
• function_call - Function call

usage · object

Token usage statistics

Show Properties

prompt_tokens · integer

Number of tokens in the input messages

completion_tokens · integer

Number of tokens in the generated content

total_tokens · integer

Total number of tokens

Usage Examples

Basic Conversation

{
  "model": "gpt-5.2",
  "messages": [
    {"role": "user", "content": "Explain vector databases in one sentence."}
  ]
}

System Prompt

{
  "model": "claude-sonnet-4-5-20250929",
  "messages": [
    {"role": "system", "content": "You are a technical editor. Improve clarity of product copy."},
    {"role": "user", "content": "Rewrite the button text 'Submission failed' to be friendly and actionable."}
  ]
}

Multi-turn Conversation

{
  "model": "gemini-3-flash-preview",
  "messages": [
    {"role": "user", "content": "Give me 3 customer support bot names."},
    {"role": "assistant", "content": "1) HelpWave 2) CarePilot 3) SwiftSupport"},
    {"role": "user", "content": "Add one style tag for each name."}
  ]
}

Streaming Output

{
  "model": "gpt-5.2",
  "messages": [
    {"role": "user", "content": "Generate 5 short titles (max 6 words) about AI video generation."}
  ],
  "stream": true
}

Authorizations

Authorization · string · header · required

All API endpoints require Bearer Token authentication.

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model · string · required

Model name.

Example:

"gpt-5.2"

messages · object[] · required

List of conversation messages. Example: [{"role": "user", "content": "Explain vector databases in one sentence."}].

Show child attributes

temperature · number

Controls output randomness, range 0-2. Default: 1.0.

Required range: 0 <= x <= 2

Example:

1

max_tokens · integer

Maximum number of tokens to generate. Model limits vary.

Required range: x >= 1

Example:

256

stream · boolean

Whether to use streaming output (SSE). Default: false.

Example:

false

top_p · number

Nucleus sampling parameter, range 0-1. Default: 1.0.

Required range: 0 <= x <= 1

Example:

1

frequency_penalty · number

Frequency penalty, range -2.0 to 2.0. Default: 0.

Required range: -2 <= x <= 2

Example:

0

presence_penalty · number

Presence penalty, range -2.0 to 2.0. Default: 0.

Required range: -2 <= x <= 2

Example:

0

stop · string string[]

Stop sequences (up to 4).

Example:

"\n\nHuman:"

n · integer

Number of completions to generate. Default: 1.

Required range: x >= 1

Example:

1

Response

200 - application/json

Completion created

code · integer

Example:

200

data · object

Show child attributes