Create a Response

POST /v1/responses

Create a Response

cURL

curl --request POST \
  --url https://api.neosantara.xyz/v1/responses \
  --header 'x-api-key: <api-key>'

200

{
  "id": "<string>",
  "object": "<string>",
  "created_at": 123,
  "status": "<string>",
  "error": {},
  "incomplete_details": {},
  "instructions": {},
  "max_output_tokens": {},
  "model": "<string>",
  "output": [
    {}
  ],
  "parallel_tool_calls": true,
  "previous_response_id": {},
  "reasoning": {},
  "store": true,
  "temperature": 123,
  "text": {},
  "tool_choice": {},
  "tools": [
    {}
  ],
  "top_p": 123,
  "truncation": "<string>",
  "usage": {
    "input_tokens": 123,
    "input_tokens_details": {},
    "output_tokens": 123,
    "output_tokens_details": {},
    "total_tokens": 123
  },
  "user": {},
  "metadata": {}
}

Get your free API key

Start with 10,000 Monthly Token Limit on our Free Plan. No credit card required. Your tokens automatically reset on the 1st of each month.

model · string · required

Model identifier (see /v1/models.

input · string or array · required

User input (string or conversation array).

max_output_tokens · integer · required

Maximum tokens in response (≥1).

max_tokens · integer

Alias for max_output_tokens (deprecated, use max_output_tokens).

instructions · string or array

System instructions/prompt.

temperature · number · default: "0.7"

Sampling temperature (0.0-1.0).

top_p · number · default: "1.0"

Nucleus sampling (0.0-1.0).

stream · boolean · default: "false"

Enable streaming response.

tools · array · default: "[]"

Available function/tool definitions.

tool_choice · string/object · default: "auto"

Tool selection strategy.

parallel_tool_calls · boolean · default: "true"

Enable parallel tool execution.

truncation · string · default: "disabled"

Truncation strategy: “auto” or “disabled”.

user · string

End-user identifier for tracking.

metadata · object

Custom metadata (max 16 key-value pairs).

store · boolean · default: "true"

Store conversation in database.

previous_response_id · string

Previous response ID for conversation continuation.

text · object

Text output format configuration.

reasoning · object

Reasoning configuration (effort: “low”, “medium”, “high”).

Returns

id · string

Response ID (format: resp_ + 48 hex chars).

object · string

Always “response”.

created_at · integer

Unix timestamp (seconds).

status · string

“completed”, “failed”, “incomplete”, “in_progress”, “cancelled”, “queued”.

error · object/null

Error details if status is “failed”.

incomplete_details · object/null

Reason if status is “incomplete”.

instructions · string/array/null

Echoed instructions parameter.

max_output_tokens · integer/null

Echoed max output tokens.

model · string

Model used for generation.

output · array

Array of output items (messages, function calls, etc.).

parallel_tool_calls · boolean

Whether parallel tool calls are enabled.

previous_response_id · string/null

Previous response ID if continuation.

reasoning · object

Reasoning effort and summary.

store · boolean

Whether conversation was stored.

temperature · number

Temperature used.

text · object

Text format configuration.

tool_choice · string/object

Tool choice strategy.

tools · array

Available tools.

top_p · number

Nucleus sampling parameter.

truncation · string

Truncation strategy.

usage · object

Detailed token usage.

Show usage properties

input_tokens · integer

Number of input tokens.

input_tokens_details · object

Cached, text, and audio token breakdown.

output_tokens · integer

Number of output tokens.

output_tokens_details · object

Reasoning, text, and audio token breakdown.

total_tokens · integer

Total tokens used.

user · string/null

User identifier if provided.

metadata · object

Custom metadata if provided.

Return Examples

Response 200

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": 1024,
  "model": "nusantara-base",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123...",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! I'm doing well, thank you for asking.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 15,
    "input_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 15,
      "audio_tokens": 0
    },
    "output_tokens": 12,
    "output_tokens_details": {
      "reasoning_tokens": 0,
      "text_tokens": 12,
      "audio_tokens": 0
    },
    "total_tokens": 27
  },
  "user": null,
  "metadata": {}
}