Базовое использование

Начало работы с Responses API

Responses API поддерживает как простой строковый ввод, так и структурированные массивы сообщений, что упрощает начало работы с базовой генерацией текста.

Простой строковый ввод

Самый простой способ использования API - с строковым вводом:

TypeScriptPythoncURL

typescript

const response = await fetch('https://api.aitunnel.ru/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    input: 'В чем смысл жизни?',
    max_output_tokens: 9000,
  }),
});

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

python

import requests

response = requests.post(
    'https://api.aitunnel.ru/v1/responses',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-4o',
        'input': 'В чем смысл жизни?',
        'max_output_tokens': 9000,
    }
)

result = response.json()
print(result)

bash

curl -X POST https://api.aitunnel.ru/v1/responses \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "В чем смысл жизни?",
    "max_output_tokens": 9000
  }'

Структурированный ввод сообщений

Для более сложных разговоров используйте формат массива сообщений:

TypeScriptPython

typescript

const response = await fetch('https://api.aitunnel.ru/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'Расскажи шутку про программирование',
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

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

python

response = requests.post(
    'https://api.aitunnel.ru/v1/responses',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-4o',
        'input': [
            {
                'type': 'message',
                'role': 'user',
                'content': [
                    {
                        'type': 'input_text',
                        'text': 'Расскажи шутку про программирование',
                    },
                ],
            },
        ],
        'max_output_tokens': 9000,
    }
)

result = response.json()
print(result)

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

API возвращает структурированный ответ с сгенерированным контентом:

json

{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1234567890,
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Смысл жизни - это философский вопрос, который веками занимает умы человечества...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 45,
    "total_tokens": 57
  },
  "status": "completed"
}

Структура ответа

id: Уникальный идентификатор ответа
object: Тип объекта (всегда "response")
created_at: Unix timestamp создания
model: Использованная модель
output: Массив выходных элементов
usage: Информация об использовании токенов
status: Статус ответа ("completed", "in_progress", etc.)

Стриминговые ответы

Включите стриминг для генерации ответов в реальном времени:

TypeScriptPython

typescript

const response = await fetch('https://api.aitunnel.ru/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    input: 'Напиши короткий рассказ об ИИ',
    stream: true,
    max_output_tokens: 9000,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader!.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') return;

      try {
        const parsed = JSON.parse(data);
        console.log(parsed);
      } catch (e) {
        // Пропускаем невалидный JSON
      }
    }
  }
}

python

import requests
import json

response = requests.post(
    'https://api.aitunnel.ru/v1/responses',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-4o',
        'input': 'Напиши короткий рассказ об ИИ',
        'stream': True,
        'max_output_tokens': 9000,
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data = line[6:]
            if data == '[DONE]':
                break
            
            try:
                parsed = json.loads(data)
                print(parsed)
            except json.JSONDecodeError:
                continue

Пример стримингового вывода

Стриминговый ответ возвращает Server-Sent Events (SSE) чанки:

data: {"type":"response.created","response":{"id":"resp_1234567890","object":"response","status":"in_progress"}}

data: {"type":"response.output_item.added","response_id":"resp_1234567890","output_index":0,"item":{"type":"message","id":"msg_abc123","role":"assistant","status":"in_progress","content":[]}}

data: {"type":"response.content_part.added","response_id":"resp_1234567890","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":"Однажды"}

data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":" в"}

data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":" мире"}

data: {"type":"response.output_item.done","response_id":"resp_1234567890","output_index":0,"item":{"type":"message","id":"msg_abc123","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Однажды в мире, где искусственный интеллект стал таким же обычным, как смартфоны..."}]}}

data: {"type":"response.done","response":{"id":"resp_1234567890","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}}

data: [DONE]

События стриминга

response.created: Ответ создан
response.output_item.added: Добавлен новый элемент вывода
response.content_part.added: Добавлена новая часть контента
response.content_part.delta: Дельта (новый текст) части контента
response.output_item.done: Элемент вывода завершен
response.done: Ответ полностью завершен

Общие параметры

Параметр	Тип	Описание
`model`	string	Обязательно. Модель для использования (например, gpt-4o)
`input`	string или array	Обязательно. Текст или массив сообщений
`stream`	boolean	Включить стриминговые ответы (по умолчанию: false)
`max_output_tokens`	integer	Максимальное количество токенов для генерации
`temperature`	number	Температура сэмплирования (0-2)
`top_p`	number	Параметр nucleus sampling (0-1)

Обработка ошибок

Обрабатывайте распространенные ошибки корректно:

TypeScriptPython

typescript

try {
  const response = await fetch('https://api.aitunnel.ru/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-aitunnel-xxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-4o',
      input: 'Привет, мир!',
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('Ошибка API:', error.error.message);
    return;
  }

  const result = await response.json();
  console.log(result);
} catch (error) {
  console.error('Ошибка сети:', error);
}

python

import requests

try:
    response = requests.post(
        'https://api.aitunnel.ru/v1/responses',
        headers={
            'Authorization': 'Bearer sk-aitunnel-xxx',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'gpt-4o',
            'input': 'Привет, мир!',
        }
    )
    
    if response.status_code != 200:
        error_data = response.json()
        print(f"Ошибка API: {error_data['error']['message']}")
        return
    
    result = response.json()
    print(result)
    
except requests.exceptions.RequestException as e:
    print(f"Ошибка сети: {e}")

Многоходовые разговоры

Поскольку Responses API не сохраняет состояние, вы должны включать полную историю разговора в каждый запрос для поддержания контекста:

TypeScriptPython

typescript

// Первый запрос
const firstResponse = await fetch('https://api.aitunnel.ru/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'Какая столица Франции?',
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

const firstResult = await firstResponse.json();

// Второй запрос - включаем предыдущий разговор
const secondResponse = await fetch('https://api.aitunnel.ru/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'Какая столица Франции?',
          },
        ],
      },
      {
        type: 'message',
        role: 'assistant',
        id: 'msg_abc123',
        status: 'completed',
        content: [
          {
            type: 'output_text',
            text: 'Столица Франции - Париж.',
            annotations: []
          }
        ]
      },
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'Какое население этого города?',
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

const secondResult = await secondResponse.json();

python

# Первый запрос
first_response = requests.post(
    'https://api.aitunnel.ru/v1/responses',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-4o',
        'input': [
            {
                'type': 'message',
                'role': 'user',
                'content': [
                    {
                        'type': 'input_text',
                        'text': 'Какая столица Франции?',
                    },
                ],
            },
        ],
        'max_output_tokens': 9000,
    }
)

first_result = first_response.json()

# Второй запрос - включаем предыдущий разговор
second_response = requests.post(
    'https://api.aitunnel.ru/v1/responses',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-4o',
        'input': [
            {
                'type': 'message',
                'role': 'user',
                'content': [
                    {
                        'type': 'input_text',
                        'text': 'Какая столица Франции?',
                    },
                ],
            },
            {
                'type': 'message',
                'role': 'assistant',
                'id': 'msg_abc123',
                'status': 'completed',
                'content': [
                    {
                        'type': 'output_text',
                        'text': 'Столица Франции - Париж.',
                        'annotations': []
                    }
                ]
            },
            {
                'type': 'message',
                'role': 'user',
                'content': [
                    {
                        'type': 'input_text',
                        'text': 'Какое население этого города?',
                    },
                ],
            },
        ],
        'max_output_tokens': 9000,
    }
)

second_result = second_response.json()

Обязательные поля

Поля id и status обязательны для любых сообщений с ролью assistant, включенных в историю разговора.

История разговора

Всегда включайте полную историю разговора в каждый запрос. API не хранит предыдущие сообщения, поэтому контекст должен поддерживаться на стороне клиента.

Лучшие практики

Используйте правильный формат: Строки для простых запросов, массивы для сложных разговоров
Обрабатывайте ошибки: Всегда проверяйте статус ответа
Управляйте токенами: Используйте max_output_tokens для контроля длины ответа
Поддерживайте контекст: Включайте полную историю для многоходовых разговоров
Используйте стриминг: Для длинных ответов стриминг улучшает пользовательский опыт

Следующие шаги

Изучите возможности Рассуждений
Исследуйте функциональность Вызова инструментов
Попробуйте интеграцию Веб-поиска

Базовое использование ​

Простой строковый ввод ​

Структурированный ввод сообщений ​

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

Структура ответа ​

Стриминговые ответы ​

Пример стримингового вывода ​

События стриминга ​

Общие параметры ​

Обработка ошибок ​

Многоходовые разговоры ​

Лучшие практики ​

Следующие шаги ​

Базовое использование

Простой строковый ввод

Структурированный ввод сообщений

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

Структура ответа

Стриминговые ответы

Пример стримингового вывода

События стриминга

Общие параметры

Обработка ошибок

Многоходовые разговоры

Лучшие практики

Следующие шаги