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

# نظرة عامة على Ace Data Cloud SDK

> Platform API guide - Ace Data Cloud

تقدم Ace Data Cloud SDK رسميًا لثلاث لغات: TypeScript / Python / Go، حيث تقوم بتغليف قدرات `api.acedata.cloud` مثل إكمالات الدردشة، الصور، الفيديو، الموسيقى، البحث، x402 وغيرها في طرق قوية النوع، مما يوفر عليك كتابة HTTP، SSE، استقصاء المهام، معالجة الأخطاء وتأخير إعادة المحاولة.

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

## المستودع والحزم

* كود المصدر لـ SDK (monorepo): [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* TypeScript: [`@acedatacloud/sdk`](https://www.npmjs.com/package/@acedatacloud/sdk)
* Python: [`acedatacloud`](https://pypi.org/project/acedatacloud/)
* Go: [`github.com/AceDataCloud/SDK/go`](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)
* عميل X402 (TypeScript): [`@acedatacloud/x402-client`](https://www.npmjs.com/package/@acedatacloud/x402-client)
* عميل X402 (Python): [`acedatacloud-x402`](https://pypi.org/project/acedatacloud-x402/)

## مصفوفة القدرات للغات الثلاث

| القدرة | TypeScript | Python | Go |
| - | - | - | - |
| `chat.completions.create` (غير متدفق) | ✅ | ✅ | ✅ |
| `chat.completions.create` (SSE متدفق) | ✅ | ✅ | ✅ |
| `images.generate` (Midjourney / Flux / NanoBanana / Seedream) | ✅ | ✅ | 🚧 (alpha) |
| `videos.generate` (Sora / Veo / Luma / Kling / Hailuo / Wan) | ✅ | ✅ | 🚧 (alpha) |
| `audios.generate` (Suno / Producer / Fish) | ✅ | ✅ | 🚧 (alpha) |
| `search.google` (Serp) | ✅ | ✅ | 🚧 (alpha) |
| استقصاء المهام غير المتزامن | ✅ (مللي ثانية) | ✅ (ثانية) | 🚧 |
| عميل غير متزامن | ✅ (Promise) | ✅ (`AsyncAceDataCloud`) | ✅ (`context.Context`) |
| إعادة المحاولة التلقائية + تأخير أسي | ✅ | ✅ | ✅ |
| استثناءات نوعية (`AuthenticationError` / `RateLimitError` …) | ✅ | ✅ | ✅ |
| خطاف `paymentHandler` لـ X402 (دفع على السلسلة بدون رمز) | ✅ | ✅ | ❌ (مخطط له) |

> الموارد المتعددة والمهام في SDK Go حاليًا في مرحلة alpha (الإصدار الوهمي `v0.0.0-20260505072132-4a3d921f9bb4`)، والقدرة المستقرة هي `chat.completions`. يُفضل اختيار TypeScript أو Python في السيناريوهات متعددة الوسائط.

## متى تستخدم SDK / MCP / HTTP الأصلي / X402

| السيناريو | الطريقة الموصى بها |
| - | - |
| خدمات الخلفية، CLI، نصوص تلقائية، إطار عمل الوكلاء | **SDK** (هذا الفصل) |
| استدعاءات عملاء MCP مثل Claude Desktop / Cursor / Cline | خوادم MCP |
| تحقق لمرة واحدة باستخدام curl، تصحيح، بيئات تدعم HTTP فقط | HTTP الأصلي (بدء سريع لكل خدمة) |
| لا ترغب في إنشاء رمز API، دفع USDC على سلسلة الاستدعاء | [دليل تكامل X402](https://platform.acedata.cloud/documents/x402-integration) |

لا تتعارض SDK مع X402: تدعم SDK كل من "مسار الرمز" و"مسار `paymentHandler`"، انظر [SDK + خطاف دفع X402](https://platform.acedata.cloud/documents/sdk-x402-payment).

## طلب رمز API

لاستخدام SDK، يجب أولاً الذهاب إلى [وحدة التحكم في Ace Data Cloud - قائمة التطبيقات](https://platform.acedata.cloud/console/applications) لطلب رمز API:

![](https://cdn.acedata.cloud/dvc3cg.jpg)

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول سيتم العودة تلقائيًا إلى الصفحة الحالية.

عند الطلب لأول مرة، سيكون هناك حد مجاني متاح، يمكنك تجربة مجموعة متنوعة من خدمات الذكاء الاصطناعي التي تقدمها Ace Data Cloud مجانًا.

انسخ الرمز الذي حصلت عليه، وسنعتبره موحدًا كـ `{token}`.

## متغيرات البيئة الموحدة

تقوم SDK للغات الثلاث تلقائيًا بقراءة نفس متغير البيئة `ACEDATACLOUD_API_TOKEN`، يُوصى باستخدام `export` في shell، مما يسمح لـ SDK بالتقاطه تلقائيًا:

```bash theme={null}
export ACEDATACLOUD_API_TOKEN={token}
# اختياري: https://api.acedata.cloud الافتراضي
# export ACEDATACLOUD_BASE_URL=https://api.acedata.cloud
```

يمكنك أيضًا تمريرها صراحة عند إنشاء العميل، وأسماء المعلمات المقابلة لكل لغة هي:

* TypeScript: `new AceDataCloud({ apiToken: '{token}' })`
* Python: `AceDataCloud(api_token="{token}")`
* Go: `adc.NewClient(adc.WithAPIToken("{token}"))`

> ملاحظة: في مستودع مشروع AceDataCloud، يُعتبر تقليديًا `ACEDATACLOUD_API_KEY` (في `.env` / CI)، لكن هذه الثلاثة SDK نفسها تتعرف فقط على `ACEDATACLOUD_API_TOKEN`. إذا كان لديك فقط `ACEDATACLOUD_API_KEY` في بيئتك، يرجى تمريرها صراحة عند الإنشاء.

## ثلاث أمثلة للبدء في 30 ثانية

تقوم الفقرات الثلاث التالية بنفس الشيء: استدعاء `gpt-4o-mini`، مما يجعله يرد فقط بـ `ADC_*_OK`. كل فقرة مرفقة بـ **نتيجة تشغيل حقيقية**، يمكنك استخدام رمزك الخاص لإعادة إنتاجها.

### TypeScript

```ts theme={null}
import { AceDataCloud } from '@acedatacloud/sdk';

const client = new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY });

const t0 = Date.now();
const res = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly: ADC_TS_SDK_OK' }],
  max_tokens: 20,
  temperature: 0
});
console.log('elapsed_ms', Date.now() - t0);
console.log('id', res.id);
console.log('model', res.model);
console.log('content', res.choices[0].message.content);
console.log('usage', JSON.stringify(res.usage));
```

> حاليًا، تعلن SDK أن الاستجابة هي `Record<string, unknown>`، وفي وقت التشغيل هي كائن JSON عادي، يمكن الوصول إليه مباشرة حسب الحقول. في مشاريع TS الصارمة، إذا واجهت أخطاء في النوع، يمكنك مؤقتًا استخدام `as any`، أو الرجوع إلى [استقصاء المهام والاستجابة المتدفقة في SDK](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) لإنشاء ملف تغليف مخصص.

نتيجة تشغيل البرنامج:

```text theme={null}
elapsed_ms 2543
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQA
model gpt-4o-mini
content ADC_TS_SDK_OK
usage {"prompt_tokens":16,"completion_tokens":6,"total_tokens":22}
```

### Python

```python theme={null}
import os, time, json
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

t0 = time.time()
res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "رد بدقة: ADC_PY_SDK_OK"}],
    max_tokens=20,
    temperature=0,
)
print("elapsed_ms", int((time.time() - t0) * 1000))
print("id", res["id"])
print("model", res["model"])
print("content", res["choices"][0]["message"]["content"])
print("usage", json.dumps({k: v for k, v in res["usage"].items()
                            if k in ("prompt_tokens","completion_tokens","total_tokens")}))
```

> Python SDK الحالية تعيد `dict`، لذا استخدم `res["id"]` بدلاً من `res.id`. هذه النقطة تختلف عن `openai-python`، يجب الانتباه عند الترحيل.

نتيجة تشغيل البرنامج:

```text theme={null}
elapsed_ms 2963
id chatcmpl-DldFdnIlhSUXINpupgsUmZL78MnBu
model gpt-4o-mini
content ADC_PY_SDK_OK
usage {"prompt_tokens": 17, "completion_tokens": 7, "total_tokens": 24}
```

### Go

```go theme={null}
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_KEY")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    res, err := client.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "رد بدقة: ADC_GO_SDK_OK"}},
        MaxTokens: 20,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("id", res["id"])
    fmt.Println("model", res["model"])
    choices := res["choices"].([]any)
    msg := choices[0].(map[string]any)["message"].(map[string]any)
    fmt.Println("content", msg["content"])
    usage := res["usage"].(map[string]any)
    fmt.Printf("usage prompt=%v completion=%v total=%v\n",
        usage["prompt_tokens"], usage["completion_tokens"], usage["total_tokens"])
}
```

> استجابة Go SDK موحدة هي `map[string]any`، ولا توجد بنية قوية، يجب إجراء تأكيد النوع بنفسك. جميع موصلات الموارد هي سلسلة من الطرق: `client.OpenAI().Chat().Completions().Create(...)`.

نتيجة تشغيل البرنامج:

```text theme={null}
elapsed_ms 6436
id chatcmpl-89DHExvFvBc4ciIPfolZYUOy7ivxv
model gpt-4o-mini
content ADC_GO_SDK_OK
usage prompt=16 completion=5 total=21
```

تأتي استجابات اللغات الثلاثة `id`، `elapsed_ms`، و `usage` من نفس المصدر: عبر PlatformGateway للتحقق → واجهة برمجة التطبيقات المتوافقة مع OpenAI المستهدفة → كتابة سجلات الفوترة. حقل `content` هو الإخراج الحقيقي للنموذج، واستخدام العلامة الثابتة `ADC_*_OK` هو لإثبات أن الاستجابة لم يتم تعديلها بواسطة SDK.

## ترتيب القراءة الموصى به

1. [دليل دمج SDK TypeScript](https://platform.acedata.cloud/documents/sdk-typescript) —— الكود الذي يمكن تشغيله بعد `npm install`.
2. [دليل دمج SDK Python](https://platform.acedata.cloud/documents/sdk-python) —— ثلاث طرق للاستخدام: متزامن، غير متزامن، وتدفق.
3. [دليل دمج SDK Go](https://platform.acedata.cloud/documents/sdk-go) —— أسلوب Go لـ `context.Context` وتدفق القنوات.
4. [استطلاع المهام واستجابة التدفق لـ SDK](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) —— اختلافات وحدة TaskHandle، تفاصيل تنفيذ SSE، إعادة المحاولة.
5. [SDK + خطاف دفع X402](https://platform.acedata.cloud/documents/sdk-x402-payment) —— بدون توكن، تسوية على السلسلة حسب الاستدعاء.

## كيفية عرض الرصيد المتبقي

يمكنك عرض الرصيد المتبقي الحالي لحسابك من خلال [لوحة تحكم Ace Data Cloud - قائمة التطبيقات](https://platform.acedata.cloud/console/applications).

يمكنك عرض جميع سجلات الاستخدام وتفاصيل الخصم من خلال [لوحة تحكم Ace Data Cloud - تاريخ الاستخدام](https://platform.acedata.cloud/console/usages).

## لمعرفة المزيد

* 📦 [شفرة مصدر SDK monorepo](https://github.com/AceDataCloud/SDK)
* 🔌 [دليل تكامل X402](https://platform.acedata.cloud/documents/x402-integration)
* 🛠 دروس خوادم MCP
* 📊 [قائمة الخدمات والأسعار](https://platform.acedata.cloud/services)


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