> ## 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.

# البدء السريع

> أنشئ مفتاح API وأرسل أول طلب إلى Phaseo باستخدام نموذج نصي متاح حالياً.

استخدم هذا الدليل لإرسال طلب Phaseo ناجح، بنص مولّد أو قرار منظّم، وتأكد من موضع ظهور الاستجابة.

<Note>
  **تستخدم وكيل برمجة؟** انسخ هذا الموجّه والصقه قبل البدء:

  ```text theme={null}
  You are integrating this project with Phaseo Gateway. Read the Phaseo agent guidance at https://phaseo.app/docs/skill.md and the relevant API reference before editing anything. Inspect the existing provider configuration and identify the smallest safe change needed. Use https://api.phaseo.app with a server-side PHASEO_API_KEY, preserve the current provider/model behavior unless I explicitly ask for a migration, and never print or commit credentials. Explain the files you would change and the verification commands first. Do not deploy, rotate keys, send external messages, or make unrelated edits without my approval.
  ```
</Note>

ستتعلّم في هذا الدليل كيفية:

* إنشاء مفتاح API
* إرسال طلب نص أو قرار منظّم
* قراءة النص المولّد أو الإجابات ذات الأنواع المحددة
* معرفة أول ما يجب التحقق منه إذا فشل الطلب

***

## 1. أنشئ مفتاح API

1. افتح [لوحة تحكم Phaseo](https://phaseo.app/gateway/keys).
2. أنشئ مفتاحاً ضمن **Gateway -> المفاتيح**.
3. انسخه مرة واحدة واحفظه في مكان آمن.

استخدم التنسيق التالي:

```http theme={null}
Authorization: Bearer phaseo_v1_sk_<kid>_<secret>
```

<Danger>
  تعامل مع مفتاح API كما تتعامل مع كلمة المرور. لا تكشفه في التعليمات البرمجية على جانب العميل.
</Danger>

***

## 2. أرسل طلباً نصياً

استخدم `POST /v1/responses` في طلبك الأول. هذه هي نقطة النهاية الموصى بها لعمليات إنشاء النصوص الجديدة.

### الطلب

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.phaseo.app/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-6-astra",
      "input": "Reply with: quickstart works"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.phaseo.app/v1/responses", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "openai/gpt-6-astra",
      input: "Reply with: quickstart works",
    }),
  });

  const data = await response.json();
  const assistantText = data.output
    ?.find((item) => item.type === "message")
    ?.content?.find((part) => part.type === "output_text")
    ?.text;

  console.log(assistantText);
  ```

  ```typescript TypeScript SDK theme={null}
  import Phaseo from "@phaseo/sdk";

  const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

  const response = await client.generateResponse({
    model: "openai/gpt-6-astra",
    input: "Reply with: quickstart works",
  });

  const assistantText = response.output
    ?.find((item: any) => item.type === "message")
    ?.content?.find((part: any) => part.type === "output_text")
    ?.text;

  console.log(assistantText);
  ```

  ```python Python SDK theme={null}
  from phaseo import Phaseo

  client = Phaseo(api_key="YOUR_API_KEY")

  response = client.generate_response(
      {
          "model": "openai/gpt-6-astra",
          "input": "Reply with: quickstart works",
      }
  )

  assistant_text = next(
      (
          part.get("text")
          for item in response.get("output", [])
          if item.get("type") == "message"
          for part in item.get("content", [])
          if part.get("type") == "output_text"
      ),
      None,
  )

  print(assistant_text)
  ```

  ```go Go SDK theme={null}
  package main

  import (
    "context"
    "fmt"

    phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go/v3"
  )

  func main() {
    client := phaseo.New("YOUR_API_KEY", "https://api.phaseo.app/v1")
    input := map[string]interface{}{
      "role": "user",
      "content": []map[string]interface{}{
        {
          "type": "input_text",
          "text": "Reply with: quickstart works",
        },
      },
    }

    response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
      Model: "openai/gpt-6-astra",
      Input: &input,
    })
    if err != nil {
      panic(err)
    }

    fmt.Println(response)
  }
  ```

  ```csharp C# SDK theme={null}
  using PhaseoSdk;
  using System.Collections.Generic;

  var client = new Phaseo("YOUR_API_KEY");

  var response = await client.GenerateResponse(new Dictionary<string, object>
  {
      ["model"] = "openai/gpt-6-astra",
      ["input"] = "Reply with: quickstart works",
  });

  Console.WriteLine(response);
  ```

  ```php PHP SDK theme={null}
  <?php
  require 'vendor/autoload.php';

  use Phaseo\Sdk\Phaseo;

  $client = new Phaseo(getenv('PHASEO_API_KEY') ?: 'YOUR_API_KEY');

  $response = $client->generateResponse([
      'model' => 'openai/gpt-6-astra',
      'input' => 'Reply with: quickstart works',
  ]);

  print_r($response);
  ```

  ```ruby Ruby SDK theme={null}
  require 'phaseo_sdk'

  client = PhaseoSdk::Phaseo.new(api_key: ENV.fetch('PHASEO_API_KEY', 'YOUR_API_KEY'))

  response = client.generate_response(
    model: 'openai/gpt-6-astra',
    input: 'Reply with: quickstart works',
  )

  puts response
  ```

  ```rust Rust SDK theme={null}
  use phaseo::Phaseo;
  use serde_json::{json, Value};

  fn main() -> Result<(), Box<dyn std::error::Error>> {
      let client = Phaseo::from_env()?;
      let response = client.responses(&json!({
          "model": "openai/gpt-6-astra",
          "input": "Reply with: quickstart works"
      }))?;

      let assistant_text = response.body
          .get("output")
          .and_then(Value::as_array)
          .into_iter()
          .flatten()
          .filter(|item| item.get("type").and_then(Value::as_str) == Some("message"))
          .flat_map(|item| {
              item.get("content")
                  .and_then(Value::as_array)
                  .into_iter()
                  .flatten()
          })
          .find_map(|part| {
              (part.get("type").and_then(Value::as_str) == Some("output_text"))
                  .then(|| part.get("text").and_then(Value::as_str))
                  .flatten()
          })
          .unwrap_or("");

      println!("{assistant_text}");
      Ok(())
  }
  ```

  ```typescript Vercel AI SDK theme={null}
  import { phaseo } from "@phaseo/ai-sdk-provider";
  import { generateText } from "ai";

  const result = await generateText({
    model: phaseo("openai/gpt-6-astra"),
    prompt: "Reply with: quickstart works",
  });

  console.log(result.text);
  ```
</CodeGroup>

### الاستجابة

```json theme={null}
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1730000000,
  "status": "completed",
  "completed_at": 1730000001,
  "model": "openai/gpt-6-astra",
  "output": [
    {
      "type": "message",
      "id": "msg_...",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "quickstart works", "annotations": [] }]
    }
  ],
  "usage": {
    "input_tokens": 9,
    "output_tokens": 3,
    "total_tokens": 12
  },
  "error": null,
  "incomplete_details": null
}
```

عند استدعاء Responses API مباشرةً، اقرأ رد المساعد من `output[].content[]` حيث تكون قيمة `type` هي `output_text`.

إذا كنت تستخدم Vercel AI SDK، فاقرأ الرد من `result.text`.

***

## 3. اتخاذ قرار منظّم

استخدم `POST /v1/decisions` عندما يحتاج تطبيقك إلى إجابات ذات أنواع محددة بدل النص المولّد. يوفّر Phaseo نموذج Jev 1.13 من TypeSafe بمعرّف `typesafe/jev-1.13.0`. أرسل قيمة `state` وسؤالًا مسمّى أو أكثر؛ تُعاد كل إجابة بالاسم نفسه.

<Note>
  Decisions قدرة تجريبية وقد تتطلب تفعيلًا لمساحة العمل. تبلغ تكلفة Jev 1.13 مقدار \$0.042 لكل مليون رمز إدخال؛ رموز الإخراج مجانية.
</Note>

شغّل الأمثلة على خادمك مع تعيين `PHASEO_API_KEY`. لا تكشف مفتاح API للبوابة في كود المتصفح أبدًا.

أنواع الأسئلة الثلاثة هي:

* يختار `choice` خيارًا من خريطة معايير ويعيد الاحتمالات والثقة.
* يعيد `noul` احتمال نعم/لا بين 0 و1.
* يقيّم `score` مصفوفة معايير مرتبة ويعيد نتيجة موزونة بالاحتمالات.

يمكنك الجمع بين أنواع الأسئلة في الطلب نفسه.

### الطلب

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.phaseo.app/v1/decisions \
    -H "Authorization: Bearer $PHASEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "typesafe/jev-1.13.0",
      "state": {
        "customer_message": "I was charged twice and need help with a refund.",
        "account_tier": "pro",
        "days_waiting": 3
      },
      "questions": {
        "department": {
          "type": "choice",
          "instructions": "Which team should handle this request?",
          "criteria": {
            "billing": "Payments, invoices, refunds, and duplicate charges.",
            "support": "Product usage questions and troubleshooting.",
            "sales": "Upgrades and new accounts."
          }
        },
        "is_urgent": {
          "type": "noul",
          "instructions": "Does this request require urgent handling?",
          "criteria": {
            "true": "The customer is blocked or the issue is time-sensitive.",
            "false": "The request can follow the normal support queue."
          }
        },
        "customer_impact": {
          "type": "score",
          "instructions": "How severe is the customer impact?",
          "criteria": [
            "No impact",
            "Minor inconvenience",
            "Significant impact",
            "Service blocked"
          ]
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.phaseo.app/v1/decisions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PHASEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "typesafe/jev-1.13.0",
      state: {
        customer_message: "I was charged twice and need help with a refund.",
        account_tier: "pro",
        days_waiting: 3,
      },
      questions: {
        department: {
          type: "choice",
          instructions: "Which team should handle this request?",
          criteria: {
            billing: "Payments, invoices, refunds, and duplicate charges.",
            support: "Product usage questions and troubleshooting.",
            sales: "Upgrades and new accounts.",
          },
        },
        is_urgent: {
          type: "noul",
          instructions: "Does this request require urgent handling?",
          criteria: {
            true: "The customer is blocked or the issue is time-sensitive.",
            false: "The request can follow the normal support queue.",
          },
        },
        customer_impact: {
          type: "score",
          instructions: "How severe is the customer impact?",
          criteria: [
            "No impact",
            "Minor inconvenience",
            "Significant impact",
            "Service blocked",
          ],
        },
      },
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  console.log(data.answers);
  ```

  ```typescript TypeScript SDK theme={null}
  import Phaseo from "@phaseo/sdk";

  const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

  const decision = await client.decisions.make({
    model: "typesafe/jev-1.13.0",
    state: {
      customer_message: "I was charged twice and need help with a refund.",
      account_tier: "pro",
      days_waiting: 3,
    },
    questions: {
      department: {
        type: "choice",
        instructions: "Which team should handle this request?",
        criteria: {
          billing: "Payments, invoices, refunds, and duplicate charges.",
          support: "Product usage questions and troubleshooting.",
          sales: "Upgrades and new accounts.",
        },
      },
      is_urgent: {
        type: "noul",
        instructions: "Does this request require urgent handling?",
        criteria: {
          true: "The customer is blocked or the issue is time-sensitive.",
          false: "The request can follow the normal support queue.",
        },
      },
      customer_impact: {
        type: "score",
        instructions: "How severe is the customer impact?",
        criteria: [
          "No impact",
          "Minor inconvenience",
          "Significant impact",
          "Service blocked",
        ],
      },
    },
  });

  console.log(decision.answers);
  ```

  ```python Python SDK theme={null}
  from phaseo import Phaseo

  client = Phaseo()  # Uses PHASEO_API_KEY from the environment

  decision = client.decisions.make(
      {
          "model": "typesafe/jev-1.13.0",
          "state": {
              "customer_message": "I was charged twice and need help with a refund.",
              "account_tier": "pro",
              "days_waiting": 3,
          },
          "questions": {
              "department": {
                  "type": "choice",
                  "instructions": "Which team should handle this request?",
                  "criteria": {
                      "billing": "Payments, invoices, refunds, and duplicate charges.",
                      "support": "Product usage questions and troubleshooting.",
                      "sales": "Upgrades and new accounts.",
                  },
              },
              "is_urgent": {
                  "type": "noul",
                  "instructions": "Does this request require urgent handling?",
                  "criteria": {
                      "true": "The customer is blocked or the issue is time-sensitive.",
                      "false": "The request can follow the normal support queue.",
                  },
              },
              "customer_impact": {
                  "type": "score",
                  "instructions": "How severe is the customer impact?",
                  "criteria": [
                      "No impact",
                      "Minor inconvenience",
                      "Significant impact",
                      "Service blocked",
                  ],
              },
          },
      }
  )

  print(decision["answers"])
  ```
</CodeGroup>

### الاستجابة

```json theme={null}
{
  "model": "typesafe/jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.91, "support": 0.06, "sales": 0.03 },
      "confidence": 0.89
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.84
    },
    "customer_impact": {
      "type": "score",
      "score": 2.4,
      "legend": {
        "0": "No impact",
        "1": "Minor inconvenience",
        "2": "Significant impact",
        "3": "Service blocked"
      },
      "probabilities": { "0": 0.02, "1": 0.12, "2": 0.61, "3": 0.25 },
      "confidence": 0.76
    }
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 18,
    "total_tokens": 60
  }
}
```

اقرأ القيمة ذات النوع المحدد من الإجابة المطابقة لمعرّف سؤالك، مثل `answers.department.choice` أو`answers.is_urgent.noul` أو`answers.customer_impact.score`. استخدم `confidence` و`probabilities` لتحديد عتبة للتطبيق بدل اتخاذ القرار على أساس القيمة وحدها.

راجع [مرجع Decisions API](./api-reference/endpoint/decisions) لعقد الطلب والاستجابة الكامل، و[مرجع نموذج Jev](https://docs.typesafe.ai/models) من TypeSafe لسلوك النموذج وحدود المزوّد.

***

## 4. استكشاف أخطاء الطلب الأول وإصلاحها

* `401`: تحقّق من مفتاح API وترويسة `Authorization`.
* `400`: تحقّق من محتوى الطلب ومعرّف النموذج.
* `402`: انتقل إلى نموذج `:free` أو أضف رصيداً قبل استخدام نموذج مدفوع.
* `429` أو `5xx`: أعد المحاولة مع زيادة مدة الانتظار تدريجياً.

استخدم [مرجع معالجة الأخطاء](./api-reference/errors.mdx) لتحديد المشكلة بسرعة.

***

## 5. إذا كنت تطوّر ميزة فيديو

إنشاء الفيديو غير متزامن. أنشئ مهمة أولاً، ثم استعلم عن حالتها أو اشترك لتلقّي النتيجة.

1. أنشئ مهمة باستخدام `POST /v1/videos`.
2. استعلم عن الحالة باستخدام `GET /v1/videos/{video_id}` حتى تكتمل المهمة.
3. نزّل المحتوى باستخدام `GET /v1/videos/{video_id}/content`.

```bash theme={null}
# Create
curl https://api.phaseo.app/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<video-model-id>",
    "prompt": "A cinematic sunrise over a mountain lake"
  }'

# Poll status
curl https://api.phaseo.app/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## 6. تابع البناء

<Columns cols={2}>
  <Card title="التكامل مع Gateway" icon="plug" href="./developers/integrating-with-the-gateway.mdx">
    أنماط التكامل في بيئة الإنتاج واختيار نقطة النهاية.
  </Card>

  <Card title="مرجع API" icon="book" href="./api-reference/introduction.mdx">
    توثيق كامل للطلبات والاستجابات لكل نقطة نهاية.
  </Card>

  <Card title="أمثلة" icon="code" href="./guides/examples.mdx">
    أمثلة طلبات أكثر اكتمالاً لسير العمل الشائع.
  </Card>

  <Card title="الدعم" icon="message-circle" href="https://phaseo.app/help">
    احصل على مساعدة في تصحيح الأخطاء والتوجيه وسلوك النماذج.
  </Card>
</Columns>


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