API-документация: Создание структурированного вывода

Описание интерфейса

Получая промпт (Prompt), модель возвращает один или несколько предсказанных вариантов ответов (completions). Также поддерживается принудительный вывод структурированных данных в соответствии с заданным форматом JSON Schema.

Официальная документация: OpenAI Structured Outputs

Основная информация об API

• Метод запроса: POST
• URL запроса: https://api.codingplanx.ai/v1/chat/completions
• Формат данных: application/json

---

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

---

Тело запроса (Request Body)

Пример запроса (Request Example)

{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "Determine if the user input violates specific guidelines and explain if they do."
    },
    {
      "role": "user",
      "content": "How do I prepare for a job interview?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "Determines if content is violating specific moderation rules",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "Indicates if the content is violating guidelines"
          },
          "category": {
            "type": ["string", "null"],
            "description": "Type of violation, if the content is violating guidelines. Null otherwise.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "Explanation of why the content is violating"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

Тело ответа (Response Body)

Пример ответа (Response Example)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

Часто задаваемые вопросы (FAQ)

1. Что такое response_format и как гарантировать строгий вывод JSON моделью?

Параметр response_format позволяет вам потребовать от модели возврата данных в определенном формате. Если вы хотите использовать «структурированный вывод», необходимо установить {"type": "json_schema"}, определить вашу JSON Schema внутри этого объекта и включить strict: true. Это гарантирует, что модель на 100% сгенерирует контент в соответствии с заданными вами полями и типами данных, избавляя вас от необходимости писать дополнительный код для отказоустойчивого парсинга JSON на вашей стороне.

2. Почему мой JSON-вывод был обрезан?

Если в данных ответа значение choices[0].finish_reason равно length, это означает, что сгенерированный текст достиг лимита max_tokens или превысил ограничение модели на максимальную длину контекста. Рекомендуется увеличить значение параметра max_tokens в вашем запросе.

3. В чем разница между параметрами temperature и top_p? Какой из них мне следует настроить?

Оба параметра используются для контроля случайности (креативности) вывода модели:

• temperature масштабирует распределение вероятностей вывода. Чем ниже значение, тем более строгим и детерминированным будет ответ; чем выше значение, тем более разнообразным он будет.
• top_p (ядерное сэмплирование) ограничивает выбор модели только теми токенами, чья совокупная вероятность достигает значения p. Официальная рекомендация: Настраивайте только один из этих параметров. Не изменяйте temperature и top_p одновременно.

4. Что произойдет, если включить stream: true?

При установке stream: true API не будет ждать полного завершения генерации ответа, а начнет возвращать фрагменты данных в реальном времени в виде потока (подобно печатной машинке). Формат возвращаемых данных изменится на Server-Sent Events (SSE). Клиенту необходимо прослушивать поток данных и склеивать фрагменты delta.content до тех пор, пока не будет получен маркер [DONE], обозначающий завершение потока.

5. Как гарантировать получение абсолютно одинакового ответа при каждом вызове с одним и тем же Prompt?

Хотя большие языковые модели по своей природе обладают случайностью, вы можете добиться максимальной детерминированности, передав заданный параметр seen (Seed) и установив temperature на 0. Если вы заметите, что system_fingerprint в результатах возврата изменился, это означает, что конфигурация бэкенд-модели была микро-скорректирована, и в этом случае даже при одинаковом Seed результаты могут иметь незначительные отличия.