> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# المخرجات المنظّمة

> أعِد JSON يمكن توقّعه باستخدام تنسيقي الإخراج json_object أو json_schema.

تتيح لك المخرجات المنظّمة فرض تنسيق قابل للقراءة آليًا بدلًا من النص الحر.

## دعم نقاط النهاية

استخدم المخرجات المنظّمة مع:

* `/v1/chat/completions` باستخدام `response_format`
* `/v1/responses` باستخدام `text.format`
* لا يزال بإمكان `/v1/messages` إرجاع نص JSON، لكنه لا يستخدم عقد `response_format` نفسه.

## الطلب

```bash theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      { "role": "user", "content": "Return a JSON object with city and weather for London." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "weather_schema",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "weather": { "type": "string" }
          },
          "required": ["city", "weather"],
          "additionalProperties": false
        }
      }
    }
  }'
```

## الرد

```json theme={null}
{
  "id": "chatcmpl_...",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "{\"city\":\"London\",\"weather\":\"Cloudy\"}"
      }
    }
  ]
}
```

## ملاحظات حول العقد

* يجب أن تكون قيمة `response_format.type` هي `text` أو `json_object` أو `json_schema`.
* مع `json_schema`، أدرج كائن مخطط (`response_format.json_schema.schema` في حمولة على نمط chat أو `text.format.schema` في حمولة على نمط Responses).
* تحقّق من JSON على خادمك قبل استخدامه في الأنظمة اللاحقة.

## تصميم المخطط

ابدأ بكائن صغير وحدد الحقول المطلوبة صراحةً واستخدم التعدادات للفئات المعروفة. عيّن `additionalProperties: false` لرفض المفاتيح الإضافية. حافظ على تزامن المخطط المطلوب ومتحقق الخادم وأدِر إصداراتهما معًا.

## التحقق من النتيجة

حلّل النتيجة الكاملة وتحقق منها قبل استخدامها لاحقًا. يستخدم مثال TypeScript هذا Zod ويطابق مخطط الطقس أعلاه:

```typescript theme={null}
import { z } from "zod";

const Weather = z.object({
  city: z.string(),
  weather: z.string(),
}).strict();

function parseWeather(content: string) {
  return Weather.parse(JSON.parse(content));
}
```

عالج الرفض والمحتوى المفقود والاستجابات المبتورة قبل التحليل. إذا فشل التحقق، اسمح بعدد محدود فقط من المحاولات التصحيحية ثم أعد فشلًا آمنًا. قد تترتب رسوم إضافية على إعادة التوليد. لا يثبت JSON صالح صحة القيم واقعيًا ولا يمنح إذنًا لتنفيذ إجراء.

تتبّع إخفاقات التحقق بحسب النموذج وإصدار المخطط. أعد فحص حالات التقييم عند تغير أي منهما. لاستعادة JSON غير سليم، راجع [إصلاح الاستجابة](../cookbook/response-healing-for-structured-json.mdx).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.