# Responses

Submit input to a Genesis model that supports Responses, then retrieve generated text from returned output items.

```text
POST https://token.moi.matrixorigin.cn/v1/responses
```

## Before you call

Prepare credentials with Genesis access and select a model that supports Responses. Obtain a model ID from [List models](../models.md).

## Request body

Replace `$GENESIS_ACCESS_TOKEN` with an access token or service-account API key, and `$MODEL_ID` with the selected model ID.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X POST \
  "https://token.moi.matrixorigin.cn/v1/responses" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "input": "Explain the purpose of an index in one sentence.",
    "store": false,
    "stream": false,
    "temperature": 0.7,
    "top_p": 0.9,
    "max_output_tokens": 2048,
    "instructions": "You are a concise API debugging assistant."
  }'
```

:::::
:::::{tab-item} Parameter description

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Responses model ID to call. |
| `input` | string | Yes | Text input for this request. |
| `store` | boolean | No | Whether to store this Response. |
| `stream` | boolean | No | Whether to request native Responses SSE events. |
| `temperature` | number | No | Sampling temperature. |
| `top_p` | number | No | Nucleus-sampling parameter. |
| `max_output_tokens` | integer | No | Maximum output tokens. |
| `instructions` | string | No | Additional instructions for this request. |

:::::
::::::
:::::::

## Successful response

The service returns the Response ID, status, and output items.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "id": "<RESPONSE_ID>",
  "object": "response",
  "status": "completed",
  "model": "<MODEL_ID>",
  "output": [{"type":"message","role":"assistant","content":[{"type":"output_text","text":"An index uses a data structure for fast lookup and reduces the amount of data scanned by a query."}]}]
}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier for this Response. |
| `object` | string | Response object type; the example is `response`. |
| `status` | string | Current response status. |
| `model` | string | Model ID that processed the request. |
| `output` | array of object | Output items returned for the request. |

:::
:::{tab-item} Output item

The following table expands each item in the example `output` array.

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Output item type; the example is `message`. |
| `role` | string | Message role; the example is `assistant`. |
| `content` | array of object | Content items in this message. |

:::
:::{tab-item} Content item

The following table expands each item in the example `output[].content` array.

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Content type; the example is `output_text`. |
| `text` | string | Generated text when the content type is `output_text`. |

:::
::::

:::::
::::::
:::::::

## Error response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{"error":{"message":"<human-readable error message>","type":"<error type; may be omitted>","code":"<error code; may be omitted>"}}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error object. |

:::
:::{tab-item} Error object

| Field | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable error message. |
| `type` | string | Error category returned by the model service; it may be omitted. |
| `code` | string or null | Error code returned by the model service; it may be omitted. |

:::
::::

:::::
::::::
:::::::