API Documentation: Creating Structured Outputs

Interface Description

Given a prompt, the model returns one or more predicted completion responses. It supports forcing the model to output structured data according to a specified JSON Schema.

Official Reference: OpenAI Structured Outputs

Base Information

• Method: POST
• Path: https://api.codingplanx.ai/v1/chat/completions
• Format: application/json

---

Request 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": "{\"is_violating\": false, \"category\": null, \"explanation_if_violating\": null}"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

Frequently Asked Questions (FAQs)

1. What is response_format and how do I ensure strict JSON output?

The response_format parameter allows you to request data in a specific format. To use "Structured Outputs," set it to {"type": "json_schema"} and define your JSON Schema within it, ensuring strict: true is enabled. This guarantees the model will follow your defined fields and data types 100%, eliminating the need for complex JSON error handling in your code.

2. Why is my JSON output truncated?

If the value of choices[0].finish_reason is length, it means the generated text reached the max_tokens limit or exceeded the model's maximum context length. We recommend increasing the max_tokens parameter in your request.

3. What is the difference between temperature and top_p? Which should I adjust?

Both parameters control the randomness of the output:

• temperature scales the output probability distribution. Lower values make the output more precise and deterministic; higher values make it more creative and diverse.
• top_p (nucleus sampling) limits the model to choosing from the top-frequency tokens whose cumulative probability reaches p. Official Recommendation: Adjust only one of these parameters; do not modify both temperature and top_p simultaneously.

4. What happens when stream: true is enabled?

When stream: true is set, the API will not wait for the entire response to be generated. Instead, it returns data fragments in real-time, similar to a typewriter. The data format changes to Server-Sent Events (SSE). Clients must listen to the stream and concatenate delta.content until the [DONE] signal is received.

5. How can I get the exact same answer for the same prompt every time?

While LLMs are inherently stochastic, you can achieve maximum determinism by passing a specific seen (Seed) parameter and setting temperature to 0. Note that if the system_fingerprint in the response changes, it indicates a back-end configuration update, which may result in slight differences even with the same seed.