API-K Агрегатор - доступ к API реесторв и сервисов

Введение

Эндпоинт /api/completion представляет собой REST API сервис для генерации текста с использованием современных моделей искусственного интеллекта. Данный интерфейс позволяет интегрировать возможности AI-генерации текста в сторонние приложения и системы.

Назначение: Генерация текстового контента различного типа (программный код, статьи, ответы на вопросы, исправление ошибок и т.д.) на основе входных промптов.

Базовый URL: https://api-k.ru/api/completion Метод: POST

Параметры запроса

Тело запроса (application/json)

completionOptions

Тип: Object
Обязательный: Нет
Описание: Дополнительные параметры для настройки генерации текста.
Параметры:
- stream: boolean - потоковая передача ответа (false по умолчанию)
- temperature: number (0.0-1.0) - креативность ответов (0.6 по умолчанию)
- maxTokens: number | string - максимальное количество токенов в ответе (1000 по умолчанию)
- reasoningOptions: Object - параметры логического вывода
  - mode: string - режим логического вывода (“DISABLED”, “ENABLED”)

messages

Тип: Array[Object]
Обязательный: Да
Описание: Массив сообщений для организации диалога с моделью.
Структура объекта:

{
  "role": "string", // "system" или "user"
  "text": "string"  // текст сообщения
}

Заголовки запроса

Content-Type: application/json - обязательно
X-API-Key: your-secret-api-key-here - аутентификация

Примеры использования

Пример 1: Базовый запрос на русском языке (cURL)

curl -X POST "https://api-k.ru/api/completion" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key-here" \
  -d '{
    "completionOptions": {
      "stream": false,
      "temperature": 0.6,
      "maxTokens": "2000",
      "reasoningOptions": {
        "mode": "DISABLED"
      }
    },
    "messages": [
      {
        "role": "system",
        "text": "Найди ошибки в тексте и исправь их"
      },
      {
        "role": "user",
        "text": "Напиши шаблон письма для клиента от имени нашей компании о том, что Ваш запрос получен. Имя клиента обозначь как {name}. Наименование нашей компании ООО '\''Альтернатива-Консалтинформ'\''"
      }
    ]
  }'

Пример 2: Запрос с числовым maxTokens (Python)

import requests
import json

url = "https://api-k.ru/api/completion"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your-secret-api-key-here"
}
data = {
    "completionOptions": {
        "stream": False,
        "temperature": 0.6,
        "maxTokens": "2000",
        "reasoningOptions": {
            "mode": "DISABLED"
        }
    },
    "messages": [
        {
            "role": "system",
            "text": "You are a senior software engineer"
        },
        {
            "role": "user",
            "text": "Explain microservices architecture patterns"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Пример 3: Запрос на JavaScript

fetch('https://api-k.ru/api/completion', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-secret-api-key-here'
    },
    body: JSON.stringify({
        completionOptions: {
            stream: false,
            temperature: 0.6,
            maxTokens: "2000",
            reasoningOptions: {
                mode: "DISABLED"
            }
        },
        messages: [
            {
                role: 'system',
                text: 'Ты - специалист по маркетингу'
            },
            {
                role: 'user',
                text: 'Напиши коммерческое предложение для IT-компании'
            }
        ]
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Пример 4: Запрос на Go (обновленная структура)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

type ReasoningOptions struct {
    Mode string `json:"mode"`
}

type CompletionOptions struct {
    Stream           bool             `json:"stream"`
    Temperature      float64          `json:"temperature"`
    MaxTokens        interface{}      `json:"maxTokens"` // string или int
    ReasoningOptions ReasoningOptions `json:"reasoningOptions"`
}

type Message struct {
    Role string `json:"role"`
    Text string `json:"text"`
}

type RequestBody struct {
    CompletionOptions CompletionOptions `json:"completionOptions"`
    Messages          []Message         `json:"messages"`
}

func main() {
    url := "https://api-k.ru/api/completion"
    
    requestBody := RequestBody{
        CompletionOptions: CompletionOptions{
            Stream:      false,
            Temperature: 0.6,
            MaxTokens:   "2000", // Можно использовать и число: 2000
            ReasoningOptions: ReasoningOptions{
                Mode: "DISABLED",
            },
        },
        Messages: []Message{
            {
                Role: "system",
                Text: "Найди ошибки в тексте и исправь их",
            },
            {
                Role: "user",
                Text: "Напиши пример кода на Go для HTTP запроса",
            },
        },
    }
    
    jsonData, err := json.Marshal(requestBody)
    if err != nil {
        fmt.Println("Error marshaling JSON:", err)
        return
    }
    
    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }
    
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "your-secret-api-key-here")
    
    client := &http.Client{Timeout: 60 * time.Second}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}

Пример 5: Запрос на 1С (обновленный)

Функция ВызватьAPIГенерацииТекста()
    
    URL = "https://api-k.ru/api/completion";
    APIКлюч = "your-secret-api-key-here";
    
    // Формируем тело запроса
    ТелоЗапроса = Новый Структура;
    ТелоЗапроса.Вставить("completionOptions", Новый Структура);
    ТелоЗапроса.completionOptions.Вставить("stream", Ложь);
    ТелоЗапроса.completionOptions.Вставить("temperature", 0.6);
    ТелоЗапроса.completionOptions.Вставить("maxTokens", "2000");
    
    // Добавляем reasoningOptions
    ReasoningOptions = Новый Структура;
    ReasoningOptions.Вставить("mode", "DISABLED");
    ТелоЗапроса.completionOptions.Вставить("reasoningOptions", ReasoningOptions);
    
    Сообщения = Новый Массив;
    
    Сообщение1 = Новый Структура;
    Сообщение1.Вставить("role", "system");
    Сообщение1.Вставить("text", "Найди ошибки в тексте и исправь их");
    Сообщения.Добавить(Сообщение1);
    
    Сообщение2 = Новый Структура;
    Сообщение2.Вставить("role", "user");
    Сообщение2.Вставить("text", "Объясни основные принципы налогового учета");
    Сообщения.Добавить(Сообщение2);
    
    ТелоЗапроса.Вставить("messages", Сообщения);
    
    // Преобразуем в JSON
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, ТелоЗапроса);
    JSONТекст = ЗаписьJSON.Закрыть();
    
    // Создаем HTTP запрос
    HTTPЗапрос = Новый HTTPЗапрос;
    HTTPЗапрос.АдресРесурса = URL;
    HTTPЗапрос.УстановитьЗаголовок("Content-Type", "application/json");
    HTTPЗапрос.УстановитьЗаголовок("X-API-Key", APIКлюч);
    HTTPЗапрос.УстановитьТелоИзСтроки(JSONТекст);
    
    // Выполняем запрос
    HTTPСоединение = Новый HTTPСоединение("api-k.ru", 443, , , , 60);
    Ответ = HTTPСоединение.ВызватьHTTPМетод("POST", HTTPЗапрос);
    
    Если Ответ.КодСостояния = 200 Тогда
        ЧтениеJSON = Новый ЧтениеJSON;
        ЧтениеJSON.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
        Результат = ПрочитатьJSON(ЧтениеJSON);
        ЧтениеJSON.Закрыть();
        Возврат Результат;
    Иначе
        ВызватьИсключение "Ошибка API: " + Ответ.КодСостояния;
    КонецЕсли;
    
КонецФункции

Форматы ответов

Успешный ответ

{
  "result": {
    "alternatives": [
      {
        "message": {
          "role": "assistant",
          "text": "**Шаблон письма:**\n\nУважаемый(ая) {name}!\n\nБлагодарим Вас за обращение в компанию ООО «Альтернатива-Консалтинформ»!\n\nМы получили Ваш запрос и уже работаем над его обработкой. В ближайшее время мы свяжемся с Вами для обсуждения деталей.\n\nС уважением,\nООО «Альтернатива-Консалтинформ»"
        },
        "status": "ALTERNATIVE_STATUS_FINAL"
      }
    ],
    "usage": {
      "inputTextTokens": "60",
      "completionTokens": "73",
      "totalTokens": "133",
      "completionTokensDetails": {
        "reasoningTokens": "0"
      }
    },
    "modelVersion": "09.02.2025"
  }
}

Основные изменения в API

1. Параметры completionOptions

temperature: значение по умолчанию изменено на 0.6
maxTokens: теперь поддерживает как числовые, так и строковые значения
reasoningOptions: добавлен новый параметр для управления логическим выводом

2. Поддержка строковых значений для maxTokens

API теперь принимает значения maxTokens как в числовом, так и в строковом формате:

"maxTokens": 2000    // Числовой формат
"maxTokens": "2000"  // Строковый формат

3. Параметры логического вывода

Добавлен объект reasoningOptions с полем mode: - "DISABLED" - отключить логический вывод (рекомендуется для большинства задач) - "ENABLED" - включить расширенный логический вывод

4. Рекомендуемые системные сообщения

Для задач исправления текста рекомендуется использовать системное сообщение:

"Найди ошибки в тексте и исправь их"

Best Practices (обновленные)

Оптимальные настройки температуры

0.6: рекомендуется для большинства задач, включая исправление текста
0.1-0.3: для точных технических ответов
0.7-0.9: для креативных задач

Использование reasoningOptions

Для большинства сценариев используйте:

"reasoningOptions": {
  "mode": "DISABLED"
}

Таймауты запросов

Рекомендуется устанавливать таймаут не менее 60 секунд для обработки сложных запросов.

Ограничения и лимиты (обновленные)

Токены

Максимальная длина промпта: 196 токенов
Максимальная длина ответа: 2048 токенов (или значение maxTokens)
Рекомендуемый maxTokens: “2000” для большинства сценариев

Rate Limiting

Базовый лимит: 1000 запросов в час
Лимит токенов: 4000 токенов в минуту

Заключение

Обновленный эндпоинт /api/completion предоставляет расширенные возможности для генерации текста с улучшенными параметрами настройки. Добавление поддержки строковых значений для maxTokens и параметров логического вывода делает API более гибким и удобным для интеграции в различные приложения.

Для дополнительной информации обратитесь к полной документации API или свяжитесь с технической поддержкой.

Техническая документация: REST API эндпоинт "Генерация текста ИИ"