### GET /models

Source: https://polza.ai/docs/glavnoe/quickstart

Retrieves the list of available models supported by the Polza.ai platform.

```APIDOC
## GET /models

### Description
Lists all available LLM models that can be used with the chat completions endpoint.

### Method
GET

### Endpoint
https://polza.ai/api/v1/models

### Response
#### Success Response (200)
- **data** (array) - List of available model objects

#### Response Example
{
  "data": [
    {"id": "openai/gpt-4o", "description": "Флагманская модель OpenAI"},
    {"id": "anthropic/claude-3-5-sonnet", "description": "Лучшая модель Anthropic"}
  ]
}
```

--------------------------------

### Install OpenCode using npm

Source: https://polza.ai/docs/integracii/opencode

Install OpenCode globally using npm. This is an alternative installation method for users who have Node.js and npm set up.

```bash
npm install -g opencode-ai
```

--------------------------------

### Check jq Installation

Source: https://polza.ai/docs/integracii/opencode

Verify that jq is installed on your system. This is a dependency for the automated setup script.

```bash
jq --version
```

--------------------------------

### Automated Setup Script for Polza.ai and OpenCode

Source: https://polza.ai/docs/integracii/opencode

Execute a setup script to automatically connect Polza.ai with OpenCode. The script checks for dependencies, prompts for your API key, and configures OpenCode.

```bash
curl -fsSL https://s3.polza.ai/scripts/opencode.sh | bash
```

--------------------------------

### Install jq on macOS

Source: https://polza.ai/docs/integracii/opencode

Install the jq command-line JSON processor on macOS using Homebrew. jq is a required dependency for the OpenCode setup script.

```bash
brew install jq
```

--------------------------------

### Install OpenCode using cURL

Source: https://polza.ai/docs/integracii/opencode

Install OpenCode, a terminal AI assistant, using the recommended cURL command. This method fetches the installation script and executes it directly.

```bash
curl -fsSL https://opencode.ai/install | bash
```

--------------------------------

### Check cURL Installation

Source: https://polza.ai/docs/integracii/opencode

Verify that cURL is installed on your system. This is a dependency for the automated setup script and some installation methods.

```bash
curl --version
```

--------------------------------

### POST /chat/completions

Source: https://polza.ai/docs/glavnoe/quickstart

Creates a model response for the given chat conversation. This endpoint is compatible with the OpenAI SDK format.

```APIDOC
## POST /chat/completions

### Description
Sends a list of messages to the model and returns a completion response. Supports various models like GPT-4o, Claude, and Gemini.

### Method
POST

### Endpoint
https://polza.ai/api/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The ID of the model to use (e.g., "openai/gpt-4o")
- **messages** (array) - Required - A list of messages comprising the conversation so far

### Request Example
{
  "model": "openai/gpt-4o",
  "messages": [{"role": "user", "content": "Привет!"}]
}

### Response
#### Success Response (200)
- **choices** (array) - The list of completion choices generated by the model

#### Response Example
{
  "id": "chatcmpl-123",
  "choices": [{"message": {"role": "assistant", "content": "Привет! Чем могу помочь?"}}]
}
```

--------------------------------

### Install OpenCode using Chocolatey (Windows)

Source: https://polza.ai/docs/integracii/opencode

Install OpenCode on Windows using the Chocolatey package manager. This command simplifies the installation process on Windows systems.

```bash
choco install opencode
```

--------------------------------

### Install OpenCode using Homebrew

Source: https://polza.ai/docs/integracii/opencode

Install OpenCode on macOS using the Homebrew package manager. This command adds the necessary repository and installs the OpenCode package.

```bash
brew install anomalyco/tap/opencode
```

--------------------------------

### List Available Models via API (cURL)

Source: https://polza.ai/docs/glavnoe/quickstart

Fetches a list of all available models from the Polza.ai API using cURL. This command requires no authentication and returns a JSON object containing model details.

```bash
curl https://polza.ai/api/v1/models
```

--------------------------------

### Check OpenCode Installation

Source: https://polza.ai/docs/integracii/opencode

Verify that OpenCode is installed correctly and accessible in your system's PATH. This command helps troubleshoot 'opencode not found' errors.

```bash
which opencode
```

--------------------------------

### Run OpenCode using Docker

Source: https://polza.ai/docs/integracii/opencode

Run OpenCode directly from a Docker container. This is useful for testing or environments where direct installation is not preferred.

```bash
docker run -it --rm ghcr.io/anomalyco/opencode
```

--------------------------------

### Configure Web Search Plugin with Custom Parameters

Source: https://polza.ai/docs/gaidy/plugins

Provides an example of configuring the `web` plugin with specific parameters such as `engine`, `max_results`, and `search_prompt`. This allows for fine-tuning the search behavior, including the search engine used and the number of results returned.

```json
{
  "model": "openai/gpt-4o",
  "plugins": [
    {
      "id": "web",
      "engine": "exa",
      "max_results": 3,
      "search_prompt": "Найти актуальную информацию:"
    }
  ]
}
```

--------------------------------

### OpenAI-Compatible API Request Example (Bash)

Source: https://polza.ai/docs/glavnoe/providers

This code snippet demonstrates how to make a POST request to the OpenAI-compatible Chat Completions API endpoint. It includes the necessary headers and a sample JSON payload for a user message.

```bash
POST /v1/chat/completions
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "model": "your-model-name",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ]
}
```

--------------------------------

### Configure Multiple Plugins and Response Format

Source: https://polza.ai/docs/gaidy/plugins

Shows how to enable multiple plugins simultaneously and specify a JSON schema for the response format. This advanced configuration allows for complex interactions, such as combining web search with response healing and ensuring structured output.

```json
{
  "model": "openai/gpt-4o",
  "messages": [...],
  "plugins": [
    { "id": "web", "max_results": 3 },
    { "id": "response-healing" }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": { ... }
  }
}
```

--------------------------------

### GET /v1/media/{id}

Source: https://polza.ai/docs/api-reference/media/status

Retrieves the generation status for a specific media item using its unique ID. This endpoint is part of the Polza.ai API for AI-driven content generation.

```APIDOC
## GET /v1/media/{id}

### Description
Retrieves the status of a media generation process using its unique identifier.

### Method
GET

### Endpoint
/v1/media/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the generation process.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the generation.
- **object** (string) - The type of object, expected to be 'media.generation'.
- **status** (string) - The current status of the generation (e.g., 'pending', 'processing', 'completed', 'failed', 'cancelled').
- **created** (number) - Unix timestamp indicating when the generation was created.
- **model** (string) - The ID of the model used for generation.
- **completed_at** (number) - Unix timestamp indicating when the generation was completed (if applicable).
- **data** (object) - Contains the generated content data (structure depends on the generation type).
- **usage** (object) - Information about resource usage during generation.
- **error** (object) - Information about any errors encountered during generation (if status is 'failed').
- **content** (string) - Textual response from the model, if applicable.
- **reasoning_summary** (string) - A brief summary of the model's reasoning process.
- **warnings** (array) - A list of warnings related to the generation process.

#### Response Example
```json
{
  "id": "gen_581761234567890123",
  "object": "media.generation",
  "status": "pending",
  "created": 1703001234,
  "model": "google/gemini-2.5-flash-image",
  "completed_at": null,
  "data": null,
  "usage": {
    "input_units": 0,
    "output_units": 0,
    "duration_seconds": null,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "cost_rub": 0,
    "cost": 0
  },
  "error": null,
  "content": null,
  "reasoning_summary": null,
  "warnings": []
}
```

#### Error Responses
- **401** - Unauthorized: Authentication key is invalid.
- **403** - Forbidden: Access rights for the key are insufficient.
- **500** - Internal Server Error: An error occurred on the server.
```

--------------------------------

### Enable Web Search Plugin using :online Shortcut

Source: https://polza.ai/docs/gaidy/plugins

Demonstrates a convenient shortcut for enabling the web search plugin by appending `:online` to the model name. This is functionally equivalent to explicitly including the `web` plugin in the request.

```json
{
  "model": "openai/gpt-4o:online"
}
```

--------------------------------

### GET /api/v1/media/{media_id}

Source: https://polza.ai/docs/api-reference/media/status

Retrieves the current status and result of a media generation task. Polling is recommended at 3-5 second intervals for images and 5-10 seconds for videos.

```APIDOC
## GET /api/v1/media/{media_id}

### Description
Fetch the status of a media generation request. Use this endpoint to poll for completion after initiating a generation task.

### Method
GET

### Endpoint
https://polza.ai/api/v1/media/{media_id}

### Parameters
#### Path Parameters
- **media_id** (string) - Required - The unique identifier of the media generation task.

### Request Example
GET /api/v1/media/aig_abc123
Authorization: Bearer YOUR_API_KEY

### Response
#### Success Response (200)
- **id** (string) - Unique task ID
- **status** (string) - Current status (pending, processing, completed, failed)
- **data** (object) - Contains the result URL if status is completed
- **usage** (object) - Billing and usage information

#### Response Example
{
  "id": "aig_abc123",
  "object": "media.generation",
  "status": "completed",
  "created": 1703001244,
  "model": "google/gemini-2.5-flash-image",
  "data": {
    "url": "https://s3.polza.ai/f/205141/2026/03/aig_abc123.jpg"
  },
  "usage": {
    "output_units": 1,
    "cost_rub": 5.00,
    "cost": 5.00
  }
}
```

--------------------------------

### OpenAPI Specification for GET /v1/storage/files/{id}

Source: https://polza.ai/docs/api-reference/storage/get-file

This OpenAPI 3.0 specification defines the GET endpoint for retrieving file information. It details the request parameters, response structure, and authentication method (Bearer token). This serves as a formal contract for interacting with the file storage API.

```yaml
openapi: 3.0.0
info:
  title: Polza.ai API
  description: AI агрегатор — унифицированный доступ к сотням AI моделей
  version: '1.0'
  contact: {}
servers:
  - url: https://polza.ai/api
    description: Production
security: []
tags: []
paths:
  /v1/storage/files/{id}:
    get:
      tags:
        - Хранилище
      summary: Получить информацию о файле
      operationId: StorageController_getFile[1]
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageFilePresenter'
      security:
        - bearer: []
components:
  schemas:
    StorageFilePresenter:
      type: object
      properties:
        id:
          type: string
          example: file_123abc
          description: ID файла
        externalUserId:
          type: object
          example: external_user_456
          description: ID внешнего пользователя клиента (для группировки файлов)
          nullable: true
        fileType:
          type: string
          example: IMAGE
          description: Тип файла (IMAGE, VIDEO, AUDIO)
        mimeType:
          type: string
          example: image/jpeg
          description: MIME-тип файла
        source:
          type: string
          example: USER_UPLOAD
          description: Источник файла (USER_UPLOAD, AI_GENERATION)
        storagePolicy:
          type: string
          example: TEMP_UPLOAD
          description: Политика хранения (TEMP_UPLOAD, TEMP_GENERATION, PERMANENT)
        url:
          type: string
          example: https://s3.polza.ai/f/211837/2026/01/t_c2446f3cf93ac9f5.png
          description: URL файла
        size:
          type: number
          example: 154832
          description: Размер файла в байтах
        expiresAt:
          type: object
          example: '2025-01-03T14:00:00.000Z'
          description: Дата истечения срока действия файла
          nullable: true
        createdAt:
          format: date-time
          type: string
          example: '2025-01-03T12:00:00.000Z'
          description: Дата создания
        updatedAt:
          format: date-time
          type: string
          example: '2025-01-03T12:00:00.000Z'
          description: Дата обновления
      required:
        - id
        - fileType
        - mimeType
        - source
        - storagePolicy
        - url
        - size
        - createdAt
        - updatedAt
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API Key
      type: http
      description: >-
        API ключ передаётся в заголовке: Authorization: Bearer
        <POLZA_AI_API_KEY>

```

--------------------------------

### Initialize OpenAI Client with Polza.ai Base URL (Python & TypeScript)

Source: https://polza.ai/docs/api-reference/introduction

Demonstrates how to configure the OpenAI SDK to work with the Polza.ai API by setting the 'base_url' and providing your API key. This allows you to use familiar OpenAI SDK methods with Polza.ai's models.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://polza.ai/api/v1",
    api_key="<POLZA_AI_API_KEY>"
)
```

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://polza.ai/api/v1',
    apiKey: '<POLZA_AI_API_KEY>'
});
```

--------------------------------

### GET /v1/models/catalog

Source: https://polza.ai/docs/api-reference/models/catalog

Retrieves a catalog of AI models with various filtering and sorting options.

```APIDOC
## GET /v1/models/catalog

### Description
Retrieves a paginated and filterable list of AI models available through the Polza.ai platform.

### Method
GET

### Endpoint
/v1/models/catalog

### Parameters
#### Query Parameters
- **page** (number) - Optional - The page number for pagination. Defaults to 1.
- **limit** (number) - Optional - The number of items per page. Defaults to 20.
- **search** (string) - Optional - Filters models by name or ID.
- **type** (array of strings) - Optional - Filters models by type (e.g., 'chat', 'embedding').
- **inputModalities** (array of strings) - Optional - Filters models by their input modalities.
- **outputModalities** (array of strings) - Optional - Filters models by their output modalities.
- **providers** (array of strings) - Optional - Filters models by their providers.
- **contextLengthMin** (number) - Optional - Filters models by minimum context length.
- **contextLengthMax** (number) - Optional - Filters models by maximum context length.
- **sortBy** (string) - Optional - The field to sort the results by. Allowed values: 'name', 'price', 'createdAt'. Defaults to 'name'.
- **sortOrder** (string) - Optional - The order of sorting. Allowed values: 'asc', 'desc'. Defaults to 'asc'.

### Request Example
```json
{
  "example": "GET /v1/models/catalog?limit=10&type=chat&sortBy=createdAt&sortOrder=desc"
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of `PublicModelPresenter` objects, each representing an AI model.
- **meta** (object) - Pagination metadata.

#### Response Example
```json
{
  "data": [
    {
      "id": "deepseek-r1",
      "name": "DeepSeek R1",
      "type": "chat",
      "short_description": "Powerful text generation model.",
      "created": 1765987078,
      "architecture": {},
      "top_provider": {},
      "providers": []
    }
  ],
  "meta": {
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10
    }
  }
}
```

#### Error Responses
- **401** - Unauthorized. Check your access key.
- **403** - Forbidden. Check your access key permissions.
- **500** - Server error. Contact the service provider.
```

--------------------------------

### Chat Completion API Request (TypeScript, Python, cURL)

Source: https://polza.ai/docs/glavnoe/quickstart

Demonstrates how to make a chat completion request to the Polza.ai API. Supports TypeScript, Python, and cURL. Requires an API key and specifies the model and user message. The output is the model's response.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://polza.ai/api/v1',
  apiKey: '<POLZA_AI_API_KEY>'
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: 'openai/gpt-4o',
    messages: [{
      role: 'user',
      content: 'Что думаешь об этой жизни?',
    }],
  });
  console.log(completion.choices[0].message);
}

main();
```

```python
from openai import OpenAI

client = OpenAI(
  base_url="https://polza.ai/api/v1",
  api_key="<POLZA_AI_API_KEY>",
)

completion = client.chat.completions.create(
  model="openai/gpt-4o",
  messages=[{
    "role": "user",
    "content": "Что думаешь об этой жизни?"
  }]
)

print(completion.choices[0].message.content)
```

```bash
curl -X POST "https://polza.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer <POLZA_AI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'
```

--------------------------------

### Fetch Multimodal Models with Sorting (Bash)

Source: https://polza.ai/docs/api-reference/models/catalog

This Bash example shows how to retrieve multimodal models from the catalog. It filters for models that accept 'image' as input and are of type 'chat'. The results are sorted by 'price' in ascending order, useful for cost-effective model selection.

```bash
curl "https://polza.ai/api/v1/models/catalog?inputModalities=image&type=chat&sortBy=price&sortOrder=asc"
```

--------------------------------

### GET /api/v1/models/catalog

Source: https://polza.ai/docs/api-reference/models/catalog

Retrieves a catalog of AI models with support for search, filtering, and pagination.

```APIDOC
## GET /api/v1/models/catalog

### Description
Retrieves a catalog of AI models with support for search, filtering, and pagination.

### Method
GET

### Endpoint
/api/v1/models/catalog

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search by model name
- **type** (string) - Optional - Type: chat, image, embedding, video, audio
- **inputModalities** (string[]) - Optional - Input modalities: text, image
- **outputModalities** (string[]) - Optional - Output modalities: text, image
- **providers** (string[]) - Optional - Filter by providers
- **contextLengthMin** (number) - Optional - Minimum context length
- **contextLengthMax** (number) - Optional - Maximum context length
- **page** (number) - Optional - Page number (defaults to 1)
- **limit** (number) - Optional - Number of items per page (defaults to 20)
- **sortBy** (string) - Optional - Sort by: price, name, created_at
- **sortOrder** (string) - Optional - Order: asc, desc (defaults to desc)

### Request Example
```bash
curl "https://polza.ai/api/v1/models/catalog?search=claude&type=chat"
```

### Response
#### Success Response (200)
- **data** (array) - Array of model objects.
- **meta** (object) - Pagination metadata.
  - **page** (number) - Current page number.
  - **limit** (number) - Items per page.
  - **total** (number) - Total number of items.
  - **totalPages** (number) - Total number of pages.

#### Response Example
```json
{
  "data": [
    {
      "id": "anthropic/claude-3-5-sonnet",
      "name": "Claude 3.5 Sonnet",
      "type": "chat",
      "created": 1677652288,
      "architecture": {
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"]
      },
      "top_provider": {
        "context_length": 200000,
        "max_completion_tokens": 8192,
        "pricing": {
          "prompt_per_million": "0.27",
          "completion_per_million": "1.35",
          "currency": "RUB"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```
```

--------------------------------

### GET /v1/history/generations/{id}

Source: https://polza.ai/docs/api-reference/history/generations

Retrieves detailed information about a specific generation using its ID.

```APIDOC
## GET /v1/history/generations/{id}

### Description
Returns detailed information about a specific generation using its unique ID.

### Method
GET

### Endpoint
/v1/history/generations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the generation.

### Request Example
```bash
curl "https://polza.ai/api/v1/history/generations/gen_581761234567890123"
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **id** (string) - Generation ID.
- **model** (string) - Model slug.
- **modelDisplayName** (string) - Display name of the model.
- **requestType** (string) - Type of request: chat, image, video, audio.
- **provider** (string|null) - Provider that processed the request.
- **status** (string) - Status: completed, failed, pending.
- **cost** (string) - Cost in rubles.
- **usage** (object|null) - Token usage details.
  - **prompt_tokens** (integer) - Prompt tokens used.
  - **completion_tokens** (integer) - Completion tokens used.
  - **total_tokens** (integer) - Total tokens used.
- **generationTimeMs** (number|null) - Generation time in milliseconds.
- **createdAt** (string) - Creation date.
- **apiKeyName** (string) - API key name (with JWT authorization).
- **apiKeyShort** (string) - Last 6 characters of the API key.

#### Response Example
```json
{
  "id": "gen_581761234567890123",
  "model": "gpt-4o",
  "modelDisplayName": "GPT-4o",
  "requestType": "chat",
  "provider": "openai",
  "status": "completed",
  "cost": "0.15",
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 200,
    "total_tokens": 350
  },
  "generationTimeMs": 1500,
  "createdAt": "2025-01-15T10:30:00Z",
  "apiKeyName": "Production Key",
  "apiKeyShort": "abc123"
}
```
```

--------------------------------

### Generate Video with Wan 2.5 (cURL)

Source: https://polza.ai/docs/gaidy/wan-2-5

This example demonstrates how to generate a video using the Wan 2.5 model via a cURL request. It includes setting the model, prompt, aspect ratio, resolution, duration, seed, negative prompt, and prompt expansion. The request is sent to the Polza AI API endpoint for media creation.

```bash
curl -X POST "https://polza.ai/api/v1/media" \
  -H "Authorization: Bearer <POLZA_AI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan/2.5",
    "input": {
      "prompt": "Описание видео",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": "5",
      "images": [],
      "seed": 42,
      "negative_prompt": "",
      "enable_prompt_expansion": "false"
    },
    "async": true
  }'
```

--------------------------------

### GET /api/v1/models

Source: https://polza.ai/docs/api-reference/models/list

Retrieves a list of available AI models. This endpoint is publicly accessible and does not require authentication.

```APIDOC
## GET /api/v1/models

### Description
Retrieves a list of available AI models. This endpoint is publicly accessible and does not require authentication.

### Method
GET

### Endpoint
/api/v1/models

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by model type: chat, image, embedding, video, audio
- **include_providers** (boolean) - Optional - Include the array of providers for each model

### Request Example
```bash
curl "https://polza.ai/api/v1/models"
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the API
- **name** (string) - Human-readable name
- **context_length** (integer) - Maximum context length in tokens
- **created** (integer) - Unix timestamp of creation
- **input_modalities** (array) - Supported input types: text, image, audio, video
- **output_modalities** (array) - Supported output types: text, image, audio
- **tokenizer** (string) - The tokenizer used
- **instruct_type** (string) - The type of instructions
- **pricing** (object) - Pricing details in rubles per token
  - **prompt** (number) - Input tokens
  - **completion** (number) - Output tokens
  - **image** (number) - Image processing cost
  - **internal_reasoning** (number) - Reasoning tokens cost
  - **input_cache_read** (number) - Cache read cost
  - **input_cache_write** (number) - Cache write cost

#### Response Example
```json
{
  "data": [
    {
      "id": "openai/gpt-4",
      "name": "GPT-4",
      "context_length": 8192,
      "created": 1677610602,
      "architecture": {
        "input_modalities": ["text"],
        "output_modalities": ["text"],
        "tokenizer": "cl100k_base",
        "instruct_type": "default"
      },
      "pricing": {
        "prompt": 0.03,
        "completion": 0.06,
        "image": 0.0,
        "internal_reasoning": 0.0,
        "input_cache_read": 0.0,
        "input_cache_write": 0.0
      }
    }
  ]
}
```
```

--------------------------------

### Fetch Files List with Filtering and Pagination (Bash)

Source: https://polza.ai/docs/api-reference/storage/list-files

This example demonstrates how to use curl to fetch a list of files from the Polza.ai API. It includes parameters for file type, pagination, and sorting. Ensure you replace 'YOUR_API_KEY' with your actual API key. The response contains file metadata and pagination information.

```bash
curl "https://polza.ai/api/v1/storage/files?fileType=IMAGE&page=1&limit=10&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### GET /v1/models

Source: https://polza.ai/docs/api-reference/models/catalog

Retrieves a paginated list of available AI models with their architectural details and provider information.

```APIDOC
## GET /v1/models

### Description
Returns a list of AI models available in the catalog, including their architecture, supported endpoints, and provider details.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
- **page** (number) - Optional - Current page number for pagination.
- **limit** (number) - Optional - Number of models to return per page.

### Response
#### Success Response (200)
- **items** (array) - List of model objects.
- **pagination** (object) - Pagination metadata including total pages and current page.

#### Response Example
{
  "items": [
    {
      "id": "gpt-4",
      "name": "GPT-4",
      "type": "llm",
      "endpoints": ["/v1/chat/completions"],
      "architecture": { "input_modalities": ["text"], "output_modalities": ["text"] }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 288,
    "totalPages": 15
  }
}
```

--------------------------------

### Fetch Models Catalog with Pagination (Bash)

Source: https://polza.ai/docs/api-reference/models/catalog

This Bash example illustrates how to paginate through the models catalog. It requests models of type 'chat' and specifies the page number as '2' with a limit of '10' items per page. This is essential for handling large datasets efficiently.

```bash
curl "https://polza.ai/api/v1/models/catalog?type=chat&page=2&limit=10"
```

--------------------------------

### Generate Sound Effect (Bash)

Source: https://polza.ai/docs/api-reference/audio/speech

This example demonstrates how to generate a sound effect using the Polza.ai API. It requires an API key and specifies the sound effect description, duration, output format, and prompt influence.

```bash
curl -X POST "https://polza.ai/api/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/sound-effect-v2",
    "input": "sound of guitar strumming",
    "duration_seconds": 2.5,
    "loop": false,
    "output_format": "mp3_44100_128",
    "prompt_influence": 0.3
  }'
```

--------------------------------

### GET /api/v1/models

Source: https://polza.ai/docs/gaidy/models

Retrieves a list of all available AI models, with options to filter by type and include provider details.

```APIDOC
## GET /api/v1/models

### Description
Retrieves a list of all available AI models with information about their type, capabilities, and pricing. You can filter the list by model type and choose to include detailed provider information.

### Method
GET

### Endpoint
https://polza.ai/api/v1/models

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by model type. Possible values include `chat`, `image`, `embedding`, `audio`, `video`, `tts`, `stt`.
- **include_providers** (boolean) - Optional - If true, includes detailed information about the providers for each model.

### Request Example
```bash
curl "https://polza.ai/api/v1/models?type=chat&include_providers=true" \
  -H "Authorization: Bearer <POLZA_AI_API_KEY>"
```

### Response
#### Success Response (200)
- **data** (array) - An array of model objects, each containing details like id, name, type, description, creation timestamp, architecture, provider information, and associated endpoints.

#### Response Example
```json
{
  "data": [
    {
      "id": "openai/gpt-4o",
      "name": "GPT-4o",
      "type": "chat",
      "short_description": "Флагманская мультимодальная модель OpenAI",
      "created": 1715367049,
      "architecture": {
        "modality": "text+image->text",
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"],
        "tokenizer": "o200k_base"
      },
      "top_provider": {
        "is_moderated": true,
        "context_length": 128000,
        "max_completion_tokens": 16384,
        "pricing": {
          "prompt_per_million": "7.50",
          "completion_per_million": "22.50",
          "currency": "RUB"
        },
        "supported_parameters": ["temperature", "top_p", "frequency_penalty", "presence_penalty", "tools", "tool_choice", "response_format"],
        "default_parameters": {
          "temperature": 1.0,
          "top_p": 1.0,
          "frequency_penalty": 0
        }
      },
      "endpoints": ["/api/v1/chat/completions"]
    }
  ]
}
```
```

--------------------------------

### Configure file-parser plugin

Source: https://polza.ai/docs/gaidy/plugins

Shows how to integrate the file-parser plugin into an API request to process PDF documents using specific engines like mistral-ocr.

```json
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Проанализируй этот документ" },
        {
          "type": "file",
          "file": {
            "filename": "report.pdf",
            "file_data": "data:application/pdf;base64,..."
          }
        }
      ]
    }
  ],
  "plugins": [
    { "id": "file-parser", "pdf": { "engine": "mistral-ocr" } }
  ]
}
```

--------------------------------

### API Response Formats

Source: https://polza.ai/docs/api-reference/chat/completions

Examples of standard JSON responses and Server-Sent Events (SSE) for streaming requests.

```json
{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-4o",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Текст ответа"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175,
    "cost_rub": 0.04131306,
    "cost": 0.04131306
  }
}
```

--------------------------------

### Редактирование изображения с помощью API Polza.ai

Source: https://polza.ai/docs/gaidy/nanobanano-pro

Этот фрагмент кода демонстрирует, как использовать API Polza.ai для редактирования изображений. Он принимает текстовую подсказку и URL изображения, а затем возвращает измененное изображение. Поддерживаются различные модели, такие как 'google/gemini-3-pro-image-preview'.

```TypeScript
const response = await fetch('https://polza.ai/api/v1/media', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <POLZA_AI_API_KEY>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'google/gemini-3-pro-image-preview',
      input: {
        prompt: "Добавь текст 'SALE 50%' крупными буквами в центре",
        image_resolution: '4K',
        images: [
          { type: 'url', data: 'https://example.com/banner.jpg' }
        ]
      }
    })
  });

  const result = await response.json();
  console.log(result);
```

```Python
import requests

response = requests.post(
    'https://polza.ai/api/v1/media',
    headers={'Authorization': 'Bearer <POLZA_AI_API_KEY>'}, 
    json={
        'model': 'google/gemini-3-pro-image-preview',
        'input': {
            'prompt': "Добавь текст 'SALE 50%' крупными буквами в центре",
            'image_resolution': '4K',
            'images': [
                {'type': 'url', 'data': 'https://example.com/banner.jpg'}
            ]
        }
    }
)

print(response.json())
```

```cURL
curl -X POST "https://polza.ai/api/v1/media" \
  -H "Authorization: Bearer <POLZA_AI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-pro-image-preview",
    "input": {
      "prompt": "Добавь текст 'SALE 50%' крупными буквами в центре",
      "image_resolution": "4K",
      "images": [
        { "type": "url", "data": "https://example.com/banner.jpg" }
      ]
    }
  }'
```

--------------------------------

### GET /api/v1/storage/files

Source: https://polza.ai/docs/api-reference/storage/list-files

Retrieves a paginated list of files from the storage service with support for filtering by type, source, and storage policy.

```APIDOC
## GET /api/v1/storage/files

### Description
Retrieves a list of files stored in the system. Supports pagination, filtering by file type, source, and storage policy, as well as custom sorting.

### Method
GET

### Endpoint
https://polza.ai/api/v1/storage/files

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Items per page (1-100, default: 20)
- **fileType** (string) - Optional - Filter by: IMAGE, VIDEO, AUDIO
- **source** (string) - Optional - Filter by: USER_UPLOAD, AI_GENERATION
- **storagePolicy** (string) - Optional - Filter by: TEMP_UPLOAD, TEMP_GENERATION, PERMANENT
- **externalUserId** (string) - Optional - Filter by external user ID
- **sortBy** (string) - Optional - Sort field: createdAt, size, expiresAt, externalUserId (default: createdAt)
- **sortOrder** (string) - Optional - Sort direction: asc, desc (default: desc)

### Request Example
curl "https://polza.ai/api/v1/storage/files?fileType=IMAGE&page=1&limit=10&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (array) - List of file objects
- **meta** (object) - Pagination metadata (page, limit, total, totalPages)

#### Response Example
{
  "data": [
    {
      "id": "file_abc123",
      "fileType": "IMAGE",
      "mimeType": "image/png",
      "source": "USER_UPLOAD",
      "storagePolicy": "PERMANENT",
      "url": "https://cdn.polza.ai/files/file_abc123.png",
      "size": 245760,
      "externalUserId": null,
      "expiresAt": null,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}
```