Documentación de la API: Crear Salidas Estructuradas

Descripción de la Interfaz

Dado un prompt (indicación), el modelo devolverá una o más respuestas predictivas, y admite forzar al modelo a generar datos estructurados de acuerdo con un esquema JSON (JSON Schema) especificado.

Documentación oficial de referencia: OpenAI Structured Outputs

Información Básica de la Interfaz

• Método de solicitud: POST
• Ruta de solicitud: https://api.codingplanx.ai/v1/chat/completions
• Formato de datos: application/json

---

Encabezados de la Solicitud (Headers)

---

Cuerpo de la Solicitud (Request Body)

Ejemplo de Solicitud (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
    }
  }
}

---

Cuerpo de la Respuesta (Response Body)

Ejemplo de Respuesta (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
    }
}

---

Preguntas Frecuentes (FAQs)

1. ¿Qué es response_format y cómo garantiza que el modelo emita un JSON estricto?

El parámetro response_format le permite solicitar que el modelo devuelva datos en un formato específico. Si desea utilizar "Salidas Estructuradas" (Structured Outputs), debe establecerlo en {"type": "json_schema"}, definir su esquema JSON en el interior y activar strict: true. Esto garantiza al 100% que el modelo generará el contenido de acuerdo con los campos y tipos de datos que haya definido, eliminando la necesidad de realizar un análisis adicional de tolerancia a errores JSON en su código.

2. ¿Por qué mi salida JSON está truncada o incompleta?

Si el valor de choices[0].finish_reason en sus datos de respuesta es length, significa que el texto generado alcanzó el límite de max_tokens o superó el límite de longitud de contexto máximo del modelo. Se recomienda aumentar el valor del parámetro max_tokens en su solicitud.

3. ¿Cuál es la diferencia entre los parámetros temperature y top_p? ¿Cuál debería ajustar?

Ambos son parámetros utilizados para controlar la aleatoriedad de la salida del modelo:

• temperature escala la distribución de probabilidad de salida del modelo. Valores más bajos producen salidas más rigurosas y deterministas; valores más altos generan salidas más divergentes y creativas.
• top_p (muestreo de núcleo o nucleus sampling) restringe al modelo a elegir solo del vocabulario más frecuente cuya probabilidad acumulada alcance p. Recomendación oficial: Ajuste solo uno de los dos parámetros, no modifique temperature y top_p al mismo tiempo.

4. ¿Qué sucede al activar stream: true?

Cuando se establece stream: true, la API no esperará a que se genere toda la respuesta para devolverla, sino que transmitirá fragmentos de datos en tiempo real (streaming), como una máquina de escribir. El formato de los datos devueltos cambiará a Server-Sent Events (SSE). El cliente debe escuchar el flujo de datos para concatenar delta.content hasta recibir la marca [DONE], que indica el final de la transmisión.

5. ¿Cómo garantizar que la misma llamada (Prompt) obtenga exactamente la misma respuesta en todo momento?

Aunque los modelos de lenguaje grande (LLM) tienen cierta aleatoriedad intrínseca, puede lograr el máximo grado de determinismo en la salida pasando un parámetro seen (Semilla / Seed) específico y configurando la temperature en 0. Si observa que el system_fingerprint en los resultados devueltos cambia, significa que hay actualizaciones o ajustes finos (fine-tuning) en la configuración del modelo de backend; en este caso, incluso con la misma semilla, el resultado puede mostrar ligeras diferencias.