> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siray.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Models API
> List available models, inspect supported endpoint types, and track model lifecycle metadata.
## Overview
Use the Models API to discover which models are available to you.
Each model includes the endpoint families it supports and lifecycle metadata you can use to migrate away from deprecated or retired models.
Use `supported_endpoint_types` to choose the correct generation endpoint instead of relying only on model naming conventions.
## Endpoints
* `GET https://api.siray.ai/v1/models`
* `GET https://api.siray.ai/v1/models/{model}`
**Headers**
* `Authorization: Bearer `
**Path parameters**
| Name | Description |
| ------- | ---------------------------------------------------------- |
| `model` | Model ID to retrieve, such as `openai/gpt-4o` or `gpt-4o`. |
## List response structure
```json theme={null}
{
"success": true,
"object": "list",
"data": [
{
"id": "openai/gpt-4o",
"object": "model",
"created": 1626777600,
"owned_by": "openai",
"supported_endpoint_types": [
"openai"
],
"status": "active"
},
{
"id": "openai/gpt-4",
"object": "model",
"created": 1626777600,
"owned_by": "openai",
"supported_endpoint_types": [
"openai"
],
"status": "deprecated",
"deprecated_at": 1710000000,
"replaced_by": "openai/gpt-4.1"
}
]
}
```
## Retrieve response structure
```json theme={null}
{
"id": "openai/gpt-4o",
"object": "model",
"created": 1626777600,
"owned_by": "openai",
"supported_endpoint_types": [
"openai"
],
"status": "active"
}
```
### Fields
* `id`: Model identifier used in request payloads.
* `object`: Always `model` for each model item.
* `created`: Unix timestamp attached to the model metadata.
* `owned_by`: Owner derived from `id`. If the ID contains `/`, this is the part before the first `/`; otherwise it is the full model ID.
* `supported_endpoint_types`: Endpoint families supported by the model. Empty array means the API could not determine a supported endpoint type.
* `status`: Lifecycle state of the model. Values are listed below.
* `deprecated_at`: Unix timestamp when the model was deprecated. Omitted when empty.
* `retired_at`: Unix timestamp when the model was retired. Omitted when empty.
* `replaced_by`: Replacement model ID. Omitted when empty.
### Supported endpoint types
| Type | Use case |
| ------------------ | ------------------------------------------------------------------- |
| `openai` | OpenAI-compatible chat completions. |
| `openai-response` | OpenAI-compatible Responses API. |
| `anthropic` | Anthropic-compatible messages endpoint. |
| `gemini` | Gemini-compatible content generation. |
| `jina-rerank` | Rerank requests. |
| `embeddings` | Embedding generation. |
| `image-generation` | Text-to-image or image-to-image generation. |
| `video-generation` | Video, text-to-video, image-to-video, or video-to-video generation. |
| `3d-generation` | Text-to-3D or image-to-3D generation. |
| `openai-video` | OpenAI-compatible video endpoint. |
### Lifecycle status values
| Status | Meaning |
| ------------ | ------------------------------------------------------------------------------- |
| `active` | Model is currently available for normal use. |
| `deprecated` | Model still works, but you should migrate to `replaced_by` when provided. |
| `retired` | Model is no longer intended for use. Migrate before sending production traffic. |
## Usage examples
List all models available to the token:
```bash theme={null}
curl -X GET "https://api.siray.ai/v1/models" \
-H "Authorization: Bearer ${SIRAY_API_TOKEN}"
```
Retrieve one model:
```bash theme={null}
curl -X GET "https://api.siray.ai/v1/models/openai/gpt-4o" \
-H "Authorization: Bearer ${SIRAY_API_TOKEN}"
```
> For provider-qualified IDs that contain `/`, URL-encode the slash if your HTTP client does not preserve it in path parameters.
## OpenAPI
````yaml openapi-spec/models.json GET /v1/models
openapi: 3.1.0
info:
title: Models API
summary: List and retrieve available models
description: >-
OpenAI-compatible model discovery endpoints. The model list is scoped by the
caller's token model limits, user group, or token group. Each
OpenAI-compatible model object includes supported endpoint types and
lifecycle metadata.
version: 1.0.0
servers:
- url: https://api.siray.ai
description: Siray API Server
security: []
tags:
- name: Models
description: Discover models available to the authenticated caller.
paths:
/v1/models:
get:
tags:
- Models
summary: List models
description: >-
Returns the OpenAI-compatible list of models available to the
authenticated caller. The response includes model lifecycle metadata and
supported endpoint types.
operationId: list_models
responses:
'200':
description: Model list or an error envelope
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ListModelsResponse'
- $ref: '#/components/schemas/ErrorEnvelope'
examples:
success:
summary: Model list
value:
success: true
object: list
data:
- id: openai/gpt-4o
object: model
created: 1626777600
owned_by: openai
supported_endpoint_types:
- openai
status: active
- id: openai/gpt-4
object: model
created: 1626777600
owned_by: openai
supported_endpoint_types:
- openai
status: deprecated
deprecated_at: 1710000000
replaced_by: openai/gpt-4.1
security:
- bearerAuth: []
components:
schemas:
ListModelsResponse:
type: object
description: OpenAI-compatible model list response.
properties:
success:
type: boolean
const: true
data:
type: array
items:
$ref: '#/components/schemas/Model'
object:
type: string
const: list
required:
- success
- data
- object
additionalProperties: false
ErrorEnvelope:
type: object
properties:
error:
$ref: '#/components/schemas/OpenAIError'
required:
- error
additionalProperties: false
Model:
type: object
description: OpenAI-compatible model metadata.
properties:
id:
type: string
description: Model identifier.
object:
type: string
description: Object type.
const: model
created:
type: integer
format: int64
description: Unix timestamp for model creation metadata.
owned_by:
type: string
description: >-
Owner derived from the model ID. If the ID contains '/', this is the
substring before the first '/'; otherwise it is the full model ID.
supported_endpoint_types:
type: array
description: >-
Endpoint types supported by the model. Empty when no supported
endpoint type can be determined.
items:
$ref: '#/components/schemas/EndpointType'
status:
$ref: '#/components/schemas/ModelLifecycleStatus'
deprecated_at:
type: integer
format: int64
description: >-
Unix timestamp when the model was deprecated. Omitted when empty or
zero.
retired_at:
type: integer
format: int64
description: >-
Unix timestamp when the model was retired. Omitted when empty or
zero.
replaced_by:
type: string
description: Replacement model ID. Omitted when empty.
required:
- id
- object
- created
- owned_by
- supported_endpoint_types
- status
additionalProperties: false
examples:
- id: openai/gpt-4o
object: model
created: 1626777600
owned_by: openai
supported_endpoint_types:
- openai
status: active
OpenAIError:
type: object
description: OpenAI-compatible error object.
properties:
message:
type: string
type:
type: string
param:
oneOf:
- type: string
- type: 'null'
code:
oneOf:
- type: string
- type: 'null'
required:
- message
- type
- param
- code
additionalProperties: true
EndpointType:
type: string
description: Endpoint family supported by the model.
enum:
- openai
- openai-response
- anthropic
- gemini
- jina-rerank
- image-generation
- embeddings
- openai-video
- video-generation
- 3d-generation
ModelLifecycleStatus:
type: string
description: Lifecycle state of the model.
enum:
- active
- deprecated
- retired
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API token passed as a Bearer token in the Authorization header.
````