> ## 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.

# Model Pricing API

> Retrieve the price summary and full pricing catalog for a single model.

## Overview

Use this endpoint to retrieve the price of one model before sending a generation request.

The response contains a headline price summary and the full pricing catalog. For token models, the headline price is quoted per 1 million tokens. For image, video, and 3D models, the catalog contains the exact price for each supported resolution, duration, size, or other parameter combination.

> [!TIP]
>
> Call `GET https://api.siray.ai/v1/models/pricing` to list the headline price of every public model, then use this endpoint for the full catalog of a single model.

## Endpoint

* `GET https://api.siray.ai/v1/models/pricing/{model_name}`

**Headers**

* `Authorization: Bearer <SIRAY_API_TOKEN>`

**Path parameters**

| Name | Description |
| - | - |
| `model_name` | Model name, such as `openai/gpt-5` or `kling/v2.6-pro`. |

## Response structure

The response uses the standard Siray response envelope. `data` contains the headline summary and the `catalog` used to calculate the final request price.

```json theme={null}
{
  "request_uuid": "f1c2d3e4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "code": 200,
  "message": "OK",
  "data": {
    "id": "openai/gpt-5",
    "name": "GPT-5",
    "billing_type": "token",
    "discount": 0.2,
    "free": false,
    "input_price": {
      "price": "0.312",
      "original_price": "0.390",
      "unit": "1M tokens",
      "unit_size": 1000000
    },
    "output_price": {
      "price": "1.250",
      "original_price": "1.562",
      "unit": "1M tokens",
      "unit_size": 1000000
    },
    "catalog": {
      "dimensions": [
        { "key": "input", "name": "Input" },
        { "key": "output", "name": "Output" }
      ],
      "pricing_options": [
        {
          "parameters": [
            { "key": "input", "value": "$0.312 / 1M" },
            { "key": "output", "value": "$1.250 / 1M" }
          ]
        }
      ],
      "pricing_description": "",
      "token_pricing_rules": [
        {
          "rule_name": "input",
          "direction": "input",
          "tiered_mode": "",
          "min_tokens": 0,
          "max_tokens": 0,
          "tier_by": "",
          "price": "0.312",
          "unit_size": 1000000,
          "display_only": false
        },
        {
          "rule_name": "output",
          "direction": "output",
          "tiered_mode": "",
          "min_tokens": 0,
          "max_tokens": 0,
          "tier_by": "",
          "price": "1.250",
          "unit_size": 1000000,
          "display_only": false
        }
      ]
    }
  }
}
```

### Fields

* `request_uuid`: Identifier of this API call, useful for support and log correlation.
* `code` / `message`: Service-level indicators for the request outcome (`200` / `OK` on success).
* `data.id`: Model name used when calling the generation endpoint.
* `data.name`: Human-readable model name.
* `data.billing_type`: Billing model. One of `token`, `image`, `video`, or `3d`.
* `data.discount`: Effective discount applied to this account, as a decimal fraction. `0.2` means 20% off; `0` means no discount.
* `data.free`: Whether the model is free for this account. When `catalog_only` is `true`, this is `false` because the summary cannot determine the exact price; use `catalog` instead.
* `data.catalog_only`: Present and `true` when the exact price depends on request parameters or token usage; omitted when `false`. In that case `output_price` is omitted and you must read `data.catalog`.
* `data.input_price`: Token input price summary. Only returned for token models.
* `data.output_price`: Output price summary. Returned for token models and for media models without parameter-based rules. Omitted when `catalog_only` is `true`.
* `data.catalog`: Full pricing catalog. Always present for this endpoint.
* `data.input_price` / `data.output_price` fields:
  * `price`: Price this account pays, as a display string. Parse it as a decimal instead of assuming a JSON number.
  * `original_price`: Price before the effective discount (model and account discounts), as a display string.
  * `unit`: `1M tokens` for token prices; `image`, `second`, or `generation` for media prices; `unit` for an unrecognized billing type.
  * `unit_size`: Number of tokens represented by one unit. Present for token prices.

All amounts are in **USD**.

### Catalog fields

* `catalog.dimensions`: Parameters that affect the price, such as `resolution`, `duration`, or `prompt_size`. May be empty when the price does not depend on parameters.
* `catalog.pricing_options`: One entry per supported parameter combination. May be empty when the model has no catalog options. Each entry contains:
  * `parameters`: Parameter key/value pairs for the combination. For token matrices, the price may appear here as a display string such as `$0.090 / 1M`.
  * `cost`: Price for the combination, in USD. May be a single value (`0.250`) or a range (`0.200~0.310`). May include an add-on clause, for example `0.036  + $0.002 each input image`. Omitted for token matrices where prices appear in `parameters`.
  * `original_cost`: Price before the effective discount. Uses the same single-value, range, and add-on formats as `cost`; omitted together with `cost` for token matrices.
* `catalog.pricing_description`: Human-readable explanation of the billing formula and any add-ons. May be empty when there is nothing extra to explain.
* `catalog.token_pricing_rules`: Optional. Token-level pricing rules. Omitted when the model has no token pricing rules.

#### Token pricing rule fields

* `rule_name`: Name of the pricing rule.
* `token_type`: Token type. Values include `text`, `audio`, `cached`, `cache_write`, `cache_write_5m`, `cache_write_1h`, `image`, and `reasoning`. Empty means all token types for the direction.
* `direction`: `input` or `output`.
* `tiered_mode`: `flat` or `graduated`; empty means a fixed (non-tiered) price.
* `min_tokens`: Inclusive lower bound of the tier.
* `max_tokens`: Exclusive upper bound of the tier. `0` means no upper bound.
* `tier_by`: `input` means the tier is selected by total input volume. Empty means the tier is selected by the rule's own token quantity.
* `price`: USD price per `unit_size` tokens. May be a single value (`0.312`) or a range (`0.200~0.310`).
* `unit_size`: Number of tokens represented by one price unit, for example `1000000`.
* `display_only`: `true` means the rule is only for display and does not participate in billing.
* `match_conditions`: Optional list of conditions that must match for the rule to apply:
  * `param`: Request parameter name.
  * `value`: Expected value.
  * `operator`: Match operator: empty for equality, `not_empty` for a non-empty parameter, or `count` to match an array length.
  * `param_alias`: Display alias for the parameter.
  * `value_alias`: Display alias for the value.

### `catalog_only` models

For image, video, or 3D models with parameter-based pricing rules, and for 3D models billed by token rules, the `data` object looks like:

```json theme={null}
{
  "id": "kling/v2.6-pro",
  "name": "Kling 2.6 Pro",
  "billing_type": "video",
  "discount": 0,
  "free": false,
  "catalog_only": true,
  "catalog": {
    "dimensions": [
      { "key": "resolution", "name": "Resolution" },
      { "key": "duration", "name": "Duration" }
    ],
    "pricing_options": [
      {
        "parameters": [
          { "key": "resolution", "value": "720P" },
          { "key": "duration", "value": "5 seconds" }
        ],
        "cost": "0.250",
        "original_cost": "0.250"
      },
      {
        "parameters": [
          { "key": "resolution", "value": "1080P" },
          { "key": "duration", "value": "5 seconds" }
        ],
        "cost": "0.400",
        "original_cost": "0.400"
      }
    ],
    "pricing_description": "Billing formula: resolution price × video duration."
  }
}
```

In this case there is no single `output_price`. Choose the `pricing_options` entry that matches your request parameters.

## Usage examples

Token model:

```bash theme={null}
curl -X GET "https://api.siray.ai/v1/models/pricing/openai%2Fgpt-5" \
  -H "Authorization: Bearer ${SIRAY_API_TOKEN}"
```

Video model with parameter-based pricing:

```bash theme={null}
curl -X GET "https://api.siray.ai/v1/models/pricing/kling%2Fv2.6-pro" \
  -H "Authorization: Bearer ${SIRAY_API_TOKEN}"
```

## Errors

The endpoint returns the standard response envelope. Non-`200` `code` values indicate failure and come with a `message` and no `data`.

| HTTP status | `code` | Typical cause |
| - | - | - |
| 400 | 400 | `model_name` is empty. |
| 401 | 401 | Missing or malformed `Authorization` header; unknown API key. |
| 403 | 403 | API key is disabled or expired, or the account is forbidden. |
| 404 | 404 | Model does not exist or is not publicly visible. |
| 500 | 500 | Pricing data could not be loaded; retry later. |


## OpenAPI

````yaml openapi-spec/model-pricing.json GET /v1/models/pricing/{model_name}
openapi: 3.1.0
info:
  title: Model Pricing API
  summary: Retrieve the price summary and full pricing catalog for a single model
  description: >-
    Returns the headline price summary and full pricing catalog for one model.
    Token models quote USD per 1 million tokens. Image, video, and 3D models
    expose exact prices for each supported parameter combination in the catalog.
    When catalog_only is true, output_price is omitted because the exact price
    depends on request parameters or token usage.
  version: 1.0.0
servers:
  - url: https://api.siray.ai
    description: Siray API Server
security: []
tags:
  - name: Pricing
    description: Inspect model prices before sending a generation request.
paths:
  /v1/models/pricing/{model_name}:
    get:
      tags:
        - Pricing
      summary: Get model pricing
      description: >-
        Returns the headline price summary and full pricing catalog for one
        model. The model name may contain slashes, for example openai/gpt-5.
      operationId: get_model_pricing
      parameters:
        - name: model_name
          in: path
          required: true
          description: Model name, such as openai/gpt-5 or kling/v2.6-pro.
          schema:
            type: string
      responses:
        '200':
          description: Model price summary and pricing catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelPricingResponse'
        '400':
          description: model_name is empty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or malformed credentials, or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key disabled or expired, or account forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Model not found or not publicly visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Pricing data could not be loaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ModelPricingResponse:
      type: object
      description: Standard response envelope for a single model price.
      required:
        - request_uuid
        - code
        - message
        - data
      properties:
        request_uuid:
          type: string
          description: Identifier of this API call, useful for support and log correlation.
        code:
          type: integer
          description: Service-level status code (200 on success).
          example: 200
        message:
          type: string
          description: Additional information about the request result.
          example: OK
        data:
          $ref: '#/components/schemas/ModelPricingDetail'
      example:
        request_uuid: f1c2d3e4-5a6b-7c8d-9e0f-1a2b3c4d5e6f
        code: 200
        message: OK
        data:
          id: openai/gpt-5
          name: GPT-5
          billing_type: token
          discount: 0.2
          free: false
          input_price:
            price: '0.312'
            original_price: '0.390'
            unit: 1M tokens
            unit_size: 1000000
          output_price:
            price: '1.250'
            original_price: '1.562'
            unit: 1M tokens
            unit_size: 1000000
          catalog:
            dimensions:
              - key: input
                name: Input
              - key: output
                name: Output
            pricing_options:
              - parameters:
                  - key: input
                    value: $0.312 / 1M
                  - key: output
                    value: $1.250 / 1M
            pricing_description: ''
            token_pricing_rules:
              - rule_name: input
                direction: input
                tiered_mode: ''
                min_tokens: 0
                max_tokens: 0
                tier_by: ''
                price: '0.312'
                unit_size: 1000000
                display_only: false
              - rule_name: output
                direction: output
                tiered_mode: ''
                min_tokens: 0
                max_tokens: 0
                tier_by: ''
                price: '1.250'
                unit_size: 1000000
                display_only: false
    ErrorResponse:
      type: object
      description: Error envelope; no data field is returned on failure.
      required:
        - request_uuid
        - code
        - message
      properties:
        request_uuid:
          type: string
          description: Identifier of this API call.
        code:
          type: integer
          description: Service-level status code matching the HTTP status.
          example: 401
        message:
          type: string
          description: Human-readable failure description.
          example: missing authorization header
    ModelPricingDetail:
      type: object
      description: Headline price summary and full pricing catalog for one model.
      required:
        - id
        - name
        - billing_type
        - discount
        - free
        - catalog
      properties:
        id:
          type: string
          description: Model name used when calling the generation endpoint.
        name:
          type: string
          description: Human-readable model name.
        billing_type:
          type: string
          description: Billing model used by the platform.
          enum:
            - token
            - image
            - video
            - 3d
        discount:
          type: number
          description: >-
            Effective discount applied to this account as a decimal fraction.
            0.2 means 20% off; 0 means no discount.
          example: 0.2
        free:
          type: boolean
          description: >-
            Whether the model is free for this account. When catalog_only is
            true, this is false because the exact price is only available in
            catalog.
        catalog_only:
          type: boolean
          description: >-
            Present and true when the exact price depends on request parameters
            or token usage; omitted when false. When true, output_price is
            omitted and free is false; the exact price is in catalog.
        input_price:
          $ref: '#/components/schemas/PriceQuote'
          description: Token input price summary. Present for token models.
        output_price:
          $ref: '#/components/schemas/PriceQuote'
          description: >-
            Output price summary. Present for token models and media models
            without parameter-based rules; omitted when catalog_only is true.
        catalog:
          $ref: '#/components/schemas/PricingCatalog'
          description: Full pricing catalog for this model.
    PriceQuote:
      type: object
      description: One side of a model's headline price. All amounts are in USD.
      required:
        - price
        - original_price
        - unit
      properties:
        price:
          type: string
          description: >-
            Price this account pays, as a display string. Parse it as a decimal
            instead of assuming a JSON number.
          example: '0.312'
        original_price:
          type: string
          description: >-
            Price before the effective discount (model and account discounts),
            as a display string.
          example: '0.390'
        unit:
          type: string
          description: >-
            Price unit: 1M tokens for token prices; image, second, or generation
            for media prices; unit for an unrecognized billing type.
          example: 1M tokens
        unit_size:
          type: integer
          description: Number of tokens represented by one unit. Present for token prices.
          example: 1000000
    PricingCatalog:
      type: object
      description: >-
        Full pricing catalog for one model. Exact image, video, and 3D prices
        are expressed as parameter combinations in pricing_options or as token
        rules.
      required:
        - dimensions
        - pricing_options
        - pricing_description
      properties:
        dimensions:
          type: array
          description: >-
            Parameters that affect the price. May be empty when the price does
            not depend on parameters.
          items:
            $ref: '#/components/schemas/PricingDimension'
        pricing_options:
          type: array
          description: >-
            One entry per supported parameter combination. May be empty when the
            model has no catalog options. cost may be omitted for token
            matrices, where prices appear in parameters.
          items:
            $ref: '#/components/schemas/PricingOption'
        pricing_description:
          type: string
          description: Human-readable explanation of the billing formula and any add-ons.
        token_pricing_rules:
          type: array
          description: >-
            Optional token-level pricing rules, including direction, token type,
            tier, and price per unit_size tokens. Omitted when the model has no
            token pricing rules.
          items:
            $ref: '#/components/schemas/TokenPricingRule'
    PricingDimension:
      type: object
      required:
        - key
        - name
      properties:
        key:
          type: string
          description: Parameter key, such as resolution or duration.
          example: resolution
        name:
          type: string
          description: Display name of the parameter.
          example: Resolution
    PricingOption:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: array
          description: >-
            Parameter key/value pairs for this price option. For token matrices,
            the price may appear as a display string such as $0.090 / 1M.
          items:
            $ref: '#/components/schemas/PricingParameter'
        cost:
          type: string
          description: >-
            Price for this parameter combination in USD. May be a single value
            (0.250) or a range (0.200~0.310), and may include an add-on clause
            such as 0.036  + $0.002 each input image. Omitted for token matrices
            where prices appear in parameters.
          example: '0.250'
        original_cost:
          type: string
          description: >-
            Price before the effective discount. Uses the same single-value,
            range, and add-on formats as cost; omitted together with cost for
            token matrices.
          example: '0.310'
    TokenPricingRule:
      type: object
      required:
        - rule_name
        - direction
        - min_tokens
        - max_tokens
        - price
        - unit_size
        - display_only
      properties:
        rule_name:
          type: string
          description: Name of the pricing rule.
          example: input
        token_type:
          type: string
          description: >-
            Token type, such as text, audio, cached, cache_write,
            cache_write_5m, cache_write_1h, image, or reasoning. Empty means all
            types for the direction.
          example: text
        direction:
          type: string
          description: Token direction.
          enum:
            - input
            - output
        tiered_mode:
          type: string
          description: 'Tier mode: flat, graduated, or empty for a fixed price.'
          example: ''
        min_tokens:
          type: integer
          description: Inclusive lower bound of the tier.
          example: 0
        max_tokens:
          type: integer
          description: Exclusive upper bound of the tier. 0 means no upper bound.
          example: 0
        tier_by:
          type: string
          description: >-
            Tier selector. input means the tier is selected by total input
            volume; empty means by the rule's own quantity.
          example: ''
        price:
          type: string
          description: >-
            USD price per unit_size tokens. May be a single value or a range
            like 0.2~0.3.
          example: '0.312'
        unit_size:
          type: integer
          description: Number of tokens represented by one price unit.
          example: 1000000
        display_only:
          type: boolean
          description: >-
            True when the rule is only used for display and does not participate
            in billing.
        match_conditions:
          type: array
          description: Conditions that must match for this rule to apply.
          items:
            $ref: '#/components/schemas/TokenPricingCondition'
    PricingParameter:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: Parameter key.
          example: resolution
        value:
          type: string
          description: Parameter value.
          example: 720P
    TokenPricingCondition:
      type: object
      required:
        - param
      properties:
        param:
          type: string
          description: Request parameter name.
          example: service_tier
        value:
          type: string
          description: Expected parameter value.
          example: flex
        operator:
          type: string
          description: >-
            Match operator: empty for equality, not_empty for a non-empty
            parameter, or count to match an array length.
          example: eq
        param_alias:
          type: string
          description: Display alias for the parameter.
        value_alias:
          type: string
          description: Display alias for the value.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token passed as a Bearer token in the Authorization header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.