OpenAPI 3.1

مرجع API للعملاء

تصف هذه الصفحة طلب الاستدلال المدعوم للعملاء والاستجابة المقابلة. نزّل مستند OpenAPI القابل للقراءة آلياً لاستخدامه مع الأدوات.

تنزيل OpenAPI JSON

أمثلة على استخدام واجهات API للنماذج

اختر معرّف نموذج منشوراً وبروتوكول API واللغة لعرض مثال للطلب. احتفظ بمفاتيح API الخاصة بالعملاء على خادم موثوق.

النموذج

اللغة

متطلبات البروتوكول

تستخدم الطلبات المتوافقة مع OpenAI الطريقة POST /chat/completions على عنوان API الأساسي المهيأ للعميل (الافتراضي https://fusionpointai.com/api/v1). صادق باستخدام Authorization: Bearer ومفتاح عميل يتيح الاستدلال. عنوان URL الافتراضي الكامل هو https://fusionpointai.com/api/v1/chat/completions.

الإمكانات المدعومة

تعالج نقطة المحادثة الحالية المتوافقة مع OpenAI الرسائل النصية بصورة متزامنة. ولا تدعم هذه النقطة البث أو استدعاء الأدوات.

تثبيت عميل

ثبّت عميل Python وعميل Node.js كحزمتين منفصلتين:

Python: pip install openai anthropic

Node.js: npm install openai @anthropic-ai/sdk

curl 'https://fusionpointai.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "Astra 6",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this in one sentence."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 300
}'

أنماط الطلبات

إعداد مفاتيح API بأمان

أنشئ مفتاح API للعميل يتيح الاستدلال، ومرره إلى عملية الخادم عبر مدير الأسرار أو متغيرات البيئة.

اضبط FUSIONPOINTAI_API_KEY في بيئة الخادم؛ لا تضع المفتاح في شيفرة المتصفح ولا تودعه في مستودع المصدر.
استخدم HTTPS واقصر المفتاح على الحساب وصلاحيات الاستدلال اللازمة للتطبيق.
احذف ترويستي Authorization وx-api-key من السجلات وآثار التتبع وطلبات الدعم؛ ألغ المفتاح إن احتمل انكشافه.

export FUSIONPOINTAI_API_KEY="YOUR_CUSTOMER_API_KEY"

اختيار معرّف نموذج دقيق

حقل النموذج قيمة توجيه وليس اسماً للعرض. اختر معرّفاً منشوراً في دليل النماذج المباشر.

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

model_id = "Astra 6"
# Use this exact identifier with either protocol.

إرسال رسائل النظام والمحادثات المتعددة

حافظ على ترتيب أدوار المحادثة الأصلي واستخدم الأدوار وأشكال المحتوى التي يدعمها البروتوكول والنموذج المحددان فقط.

في الطلبات المتوافقة مع OpenAI أرسل رسائل system وuser وassistant بالترتيب وبمحتوى نصي.
في Claude Messages أرسل تعليمات النظام والأدوار المتتابعة للمستخدم والمساعد ضمن الحقول الأصلية للبروتوكول.
احتفظ بسياق المحادثة الذي يحتاجه التطبيق فقط، والتزم بحدود سياق النموذج المختار.

response = client.messages.create(
    model="Astra 6",
    max_tokens=512,
    system="Answer in clear, concise German.",
    messages=[
        {"role": "user", "content": "What is an API?"},
        {"role": "assistant", "content": "An API lets software exchange requests and responses."},
        {"role": "user", "content": "Give a practical example."},
    ],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

طلب استجابات JSON

إذا احتاج التطبيق إلى مخرجات منظمة، فتحقق من مطابقة الاستجابة لمخططه قبل استخدامها.

استخدم أدوات المخرجات المنظمة التي يدعمها البروتوكول المختار والنموذج المحدد لدى المزود الأصلي.
تعامل مع JSON المنشأ بوصفه مدخلاً غير موثوق: حلله وتحقق من الحقول والأنواع المطلوبة وعالج الصيغ غير الصالحة.
لا تفترض دعم وضع JSON لمزيج نموذج وبروتوكول إلا إذا أكدته وثائق النموذج.

import json

# JSON is generated content, not trusted application input.
response = client.messages.create(
    model="Astra 6", max_tokens=256,
    messages=[{"role": "user", "content": 'Return only JSON with a string field named "summary". Explain an API in one sentence.'}],
)
text = "".join(block.text for block in response.content if block.type == "text")
try:
    result = json.loads(text)
    if not isinstance(result, dict) or not isinstance(result.get("summary"), str):
        raise ValueError("Unexpected response schema")
    print(result["summary"])
except (json.JSONDecodeError, ValueError) as error:
    print("Handle invalid model output:", error)

تلقي مخرجات SSE لحظياً

يعتمد البث على البروتوكول المختار والنموذج الأصلي؛ فالاستجابة العادية بصيغة JSON ليست بثاً.

تعيد المحادثة المتوافقة مع OpenAI حالياً نصاً متزامناً ولا توفر البث.
في Claude Messages استخدم وضع stream عندما يدعمه النموذج المحدد لدى المزود الأصلي؛ يمرر الوسيط أحداث الخادم المرسلة الأصلية.
استهلك الأحداث تباعاً وأنهِ الاتصال عند الاكتمال أو الخطأ، ولا تعتبر المخرجات الجزئية إجابة مكتملة.

# client is the Anthropic client configured above.
with client.messages.stream(
    model="Astra 6", max_tokens=512,
    messages=[{"role": "user", "content": "Explain API authentication."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print("\nStop reason:", final_message.stop_reason)

التعامل مع الأدوات وكتل المحتوى والأخطاء

حافظ على البنى الأصلية للبروتوكول وحدد سلوك التطبيق بوضوح عند استدعاء الأدوات والمحتوى متعدد الوسائط والإخفاقات.

لا تدعم المحادثة المتوافقة مع OpenAI حالياً استدعاء الأدوات أو كتل المحتوى غير النصية.
يحافظ Claude على كتل المحتوى الأصلية وبيانات استخدام الأدوات ونتائجها عند دعم النموذج لها؛ تحقق من أسماء الأدوات ومدخلاتها قبل التنفيذ.
افحص حالة HTTP ومتن الاستجابة، وميّز أخطاء المصادقة والصلاحيات والتحقق وتحديد المعدل، وأعد المحاولة للأخطاء العابرة مع تراجع زمني.

import json
from datetime import datetime, timezone
from anthropic import APIError

messages = [{"role": "user", "content": "What time is it in UTC?"}]
tools = [{
    "name": "current_utc_time", "description": "Read the current UTC time.",
    "input_schema": {"type": "object", "properties": {}, "additionalProperties": False},
}]
try:
    reply = client.messages.create(model="Astra 6", max_tokens=256, messages=messages, tools=tools)
    results = []
    for block in reply.content:
        if block.type == "tool_use":
            if block.name != "current_utc_time" or block.input != {}:
                raise ValueError("Unapproved tool request")
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": json.dumps({"utc": datetime.now(timezone.utc).isoformat()})})
    if results:
        messages.append({"role": "assistant", "content": reply.content})
        messages.append({"role": "user", "content": results})
        reply = client.messages.create(model="Astra 6", max_tokens=256, messages=messages, tools=tools)
    print("".join(block.text for block in reply.content if block.type == "text"))
except APIError as error:
    # Log status only; never log keys or private prompts.
    print("API request failed:", getattr(error, "status_code", None))

الأسئلة الشائعة

هل يمكنني استخدام اسم النموذج الظاهر في الطلب؟

استخدم المعرّف الدقيق المنشور للاستدلال فقط. الاسم الظاهر ليس قيمة توجيه، ولا يجوز تخمين معرّف غير منشور.

ما متغير البيئة الذي يحوي مفتاح العميل؟

استخدم FUSIONPOINTAI_API_KEY للبروتوكولين. احتفظ بقيمته في بيئة خادم موثوقة وبعيداً عن شيفرة العميل والسجلات.

ما عنوان URL الذي أضبطه لعميل OpenAI؟

استخدم عنوان API الأساسي المهيأ للعميل، والافتراضي https://fusionpointai.com/api/v1. وتضيف نقطة المحادثة /chat/completions.

لماذا يختلف عنوان Claude SDK الأساسي عن cURL؟

يضيف Anthropic SDK المسار /v1/messages، لذا اضبط عنوانه الأساسي على https://fusionpointai.com/api. أما طلب HTTP المباشر فيستخدم العنوان الكامل /api/v1/messages.

هل تدعم المحادثة المتوافقة مع OpenAI البث أو الأدوات؟

لا. تدعم النقطة الحالية الرسائل النصية المتزامنة فقط، ولا توفر البث أو استدعاء الأدوات.

هل تضمن جميع نماذج Claude دعم الكتل أو الأدوات أو البث؟

لا. تُحفظ هذه الإمكانات الأصلية عندما يدعمها النموذج المختار لدى المزود الأصلي. تحقق من إمكانات النموذج وعالج الطلبات غير المدعومة.

Claude Messages · `POST /messages`

تستخدم طلبات Claude Messages الطريقة POST /api/v1/messages. أرسل مفتاح العميل في x-api-key واضبط anthropic-version على 2023-06-01. عنوان URL الأساسي لـ Anthropic SDK هو https://fusionpointai.com/api لأن SDK يضيف /v1/messages؛ كما يدعم البروتوكول المصادقة بصيغة bearer.

يحافظ وسيط Claude Messages على كتل المحتوى الأصلية وبيانات الأدوات والبث الفعلي عبر أحداث الخادم المرسلة، عندما يدعمها النموذج المحدد لدى المزود الأصلي.

الحقل	النوع	مطلوب	القيود
`model`	`string`	نعم	`{"minLength":1,"maxLength":160}`
`max_tokens`	`integer`	نعم	`{"minimum":1,"maximum":100000}`
`messages`	`array`	نعم	`{"minItems":1,"maxItems":100,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","maxLength":80}},"additionalProperties":true}}]}}}}`
`system`	`string \| array`	لا	`{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"const":"text"},"text":{"type":"string"}},"additionalProperties":true}}]}`
`stream`	`boolean`	لا	`{"default":false}`
`temperature`	`number`	لا	`{"minimum":0,"maximum":1}`
`top_p`	`number`	لا	`{"minimum":0,"maximum":1}`
`top_k`	`integer`	لا	`{"minimum":0,"maximum":100000}`
`stop_sequences`	`array`	لا	`{"items":{"type":"string"}}`
`tools`	`array`	لا	`{"items":{"type":"object","additionalProperties":true}}`
`tool_choice`	`object`	لا	`{"additionalProperties":true}`
`thinking`	`object`	لا	`{"additionalProperties":true}`
`metadata`	`object`	لا	`{"additionalProperties":true}`
`output_config`	`object`	لا	`{"additionalProperties":true}`
`service_tier`	`string`	لا	`[]`

{
    "id": "msg_example",
    "type": "message",
    "role": "assistant",
    "model": "Astra 6",
    "content": [
        {
            "type": "text",
            "text": "A concise answer to the supplied question."
        }
    ],
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 12,
        "output_tokens": 10
    }
}

{"type":"error","error":{"type":"authentication_error","message":"Invalid or missing API key."}}

بدء سريع باستخدام SDK

استخدم عنوان URL الأساسي للإنتاج مع عميل متوافق لـPython أو Node.js، أو أرسل طلب JSON نفسه باستخدام cURL.

عنوان URL الأساسي لـ API: https://fusionpointai.com/api/v1

أرسل مفتاح API للعميل في ترويسة Authorization: Bearer. يجب أن يملك المفتاح نطاق ai:inference وإمكانية الوصول إلى حساب الخدمة. احتفظ به على خادم موثوق.

# Install the client for your application language.
# Python:
python -m pip install openai
# Node.js:
npm install openai

# Bash: enter the key without storing it in shell history.
read -rs -p 'FusionPointAI API key: ' FUSIONPOINTAI_API_KEY
export FUSIONPOINTAI_API_KEY
printf '\n'
# After finishing:
# unset FUSIONPOINTAI_API_KEY

curl 'https://fusionpointai.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "Jurassic-2",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this in one sentence."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 300
}'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
    base_url="https://fusionpointai.com/api/v1",
)

response = client.chat.completions.create(
    model="Jurassic-2",
    messages=[{"role": "user", "content": "Summarize this in one sentence."}],
    temperature=0.7,
    max_tokens=300,
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FUSIONPOINTAI_API_KEY,
  baseURL: "https://fusionpointai.com/api/v1",
});

const response = await client.chat.completions.create({
  model: "Jurassic-2",
  messages: [{ role: "user", content: "Summarize this in one sentence." }],
  temperature: 0.7,
  max_tokens: 300,
});
console.log(response.choices[0].message.content);

OpenAI · حقول الطلب

قيم النموذج هي المعرّفات المسجلة الدقيقة المنشورة حالياً للاستدلال. إذا لم يُنشر أي منها، فراجع كتالوج مقدم الخدمة قبل إرسال الطلب.

الحقل	النوع	مطلوب	القيود
`model`	`string`	نعم	بحد أقصى 160 حرفاً؛ استخدم معرّفاً منشوراً كما هو.
`messages`	`array`	نعم	من 1 إلى 100 رسالة، وتُرسل بالترتيب.
`messages[].role`	`string`	نعم	system أو user أو assistant.
`messages[].content`	`string`	نعم	بحد أقصى 100,000 حرف لكل رسالة.
`temperature`	`number`	لا	من 0 إلى 2.
`max_tokens`	`integer`	لا	من 1 إلى 100,000؛ وقد يفرض النموذج حداً أقل.

استجابة ناجحة

تحتوي استجابة JSON الناجحة على id وobject (chat.completion) وcreated وmodel وchoices. ويتضمن كل choice الفهرس ورسالة للمساعد وfinish_reason. وقد يُعاد أيضاً استخدام الرموز.

{
    "id": "chatcmpl_example",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "Jurassic-2",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "A concise summary of the supplied text."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 10,
        "total_tokens": 22
    }
}

الحقل	النوع	المعنى
`id`	`string`	معرّف فريد للإكمال.
`object`	`string`	نوع الاستجابة: chat.completion.
`created`	`integer`	وقت الإنشاء كطابع زمني Unix.
`model`	`string`	معرّف النموذج المستخدم للإكمال.
`choices`	`array`	بدائل الإكمال، وتتضمن رسالة للمساعد وسبب الإنهاء.
`usage`	`object`	أعداد الرموز عند إعادتها.

حدود المعدل والأخطاء

لا تحتسب اشتراكات العملاء المباشرة الطلبات أو استخدام الرموز ضمن حصة محددة؛ أما مفاتيح sandbox فتخضع للحد الشهري المنشور لها. وتظل نوافذ سياق النموذج وحدود المخرجات وضوابط الحركة المؤقتة سارية. يدعم Chat Completions النص المتزامن، ويحافظ Claude Messages على كتل المحتوى الأصلية والأدوات وSSE المدعومة. راجع مخططات العمليات المنفصلة قبل إرسال الطلبات.

تعيد عملية المحادثة إخفاقات التحقق وأخطاء مقدم الخدمة ضمن كائن خطأ. وقد تعيد برمجيات المصادقة والنطاق بدلاً من ذلك حقلاً message على المستوى الأعلى؛ ويتوقف شكل الاستجابة والحالة على الطبقة التي رفضت الطلب.

حالة HTTP	المعنى
`200`	تم إنشاء الإكمال بنجاح.
`400`	متن الطلب أو إحدى معلماته غير صالح.
`401`	مفتاح API بصيغة bearer مفقود أو غير صالح.
`403`	نطاق المفتاح المطلوب أو صلاحية الوصول إلى الحساب غير متاح.
`429`	طُبّق تحديد معدل على مستوى التطبيق أو ضابط حركة مؤقت لدى جهة وسيطة؛ أعد المحاولة بعد تراجع زمني.
`500`	تعذّر على الخدمة إعادة إكمال صالح للاستخدام.