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

# X402 سعر الشرح

> Platform API guide - Ace Data Cloud

توضح هذه الوثيقة كيفية تحديد السعر عند استدعاء Ace Data Cloud API باستخدام X402، وكذلك العلاقة بينه وبين سعر **Credits** (الاعتمادات) العادي على المنصة.

## الاستنتاجات الأساسية

X402 ليست نظام تسعير مستقل. كل استدعاء API له تكلفة محسوبة بـ **Credits**، وهذه هي المصدر الوحيد للأسعار المشتركة لجميع طرق الفوترة (خصم الاعتمادات من API Token، رصيد الحساب، الدفع على السلسلة باستخدام X402). X402 فقط تقوم بتحويل تكلفة الاعتمادات هذه إلى USDC على السلسلة بسعر ثابت:

> **1 Credit = 0.095215 USDC** (أي `95215` atomic USDC، USDC بـ 6 أرقام عشرية)

بمعنى آخر:

```text theme={null}
سعر X402 (USDC) = تكلفة الاعتمادات لهذه المكالمة × 0.095215
```

هذا السعر ليس محددًا بشكل عشوائي، بل يساوي **أفضل سعر للاعتمادات** على المنصة. لذا، فإن الدفع باستخدام X402 ≈ شراء الاعتمادات بأفضل سعر ثم استهلاكها، **لا يوجد سعر زائد لـ X402**، بل يتمتع المستخدم بسعر الاعتمادات الأرخص مباشرة، دون الحاجة إلى إعادة شحن مسبق، ودون الحاجة إلى API Token.

## معايير التسعير

| العنصر | القيمة | الشرح |
| - | - | - |
| سعر التحويل | `1 Credit = 0.095215 USDC` | سعر ثابت محدد من قبل المنصة |
| الوحدة atomic | `1 Credit = 95215 atomic USDC` | USDC بـ 6 أرقام عشرية، `atomic = floor(credits × 0.095215 × 1e6)` |
| الحد الأدنى للخصم | `1 atomic USDC` (0.000001 دولار) | حتى لو كانت التكلفة منخفضة جدًا، يتم تسوية 1 atomic على الأقل |
| عملة التسعير | USDC | Base / SKALE هو ERC-20 USDC، Solana هو SPL USDC |

يتم التحويل بواسطة المنصة بشكل موحد، والمبلغ متساوي لجميع الشبكات المدعومة (Base، SKALE، Solana)؛ الشبكات المختلفة فقط تختلف في عقود الأصول وطرق التوقيع، لكن الأسعار متساوية.

### العلاقة مع سعر الاعتمادات العادي

تبيع المنصة الاعتمادات وفقًا لمبدأ "كلما زادت الكمية، انخفض السعر". عند احتساب X402، يتم استخدام سعر أفضل شريحة موحد:

| طريقة الشراء/الدفع | سعر الاعتمادات التقريبي | الشرح |
| - | - | - |
| الدخول / إعادة الشحن الصغيرة | حوالي `$0.13 / Credit` | سعر القائمة، سعر الاعتمادات عند الشراء بكميات صغيرة |
| الشراء الكبير / أفضل شريحة | `$0.095215 / Credit` | أرخص سعر |
| **X402 الدفع حسب الاستدعاء** | **`$0.095215 / Credit`** | **دائمًا يساوي سعر أفضل شريحة** |

بمعنى آخر، تقوم X402 بتسوية كل استدعاء بسعر الاعتمادات من أفضل شريحة. سيكون سعر المستخدمين الذين يشترون الاعتمادات بإعادة شحن صغيرة أعلى من X402؛ بينما سيكون سعر المستخدمين الذين يشترون بكميات كبيرة متساويًا مع X402.

## نوعان من أسعار: `exact` و `upto`

في استجابة 402 لـ X402، `maxAmountRequired` هو المبلغ الذي تحتاج إلى توقيعه. له نوعان:

* **`exact` (سعر ثابت)**: يمكن تحديد السعر قبل معالجة الطلب (صور، فيديو، موسيقى، بحث، دفع الطلبات). `maxAmountRequired = تكلفة الاعتمادات لهذه المكالمة × 0.095215`، أي المبلغ المستحق لهذه المكالمة (يتطابق مع `cost.amount` في الاستجابة الناجحة).
* **`upto` (قياس الاستخدام بعد)**: واجهات مثل إكمال الدردشة التي "لا تعرف كم تم استخدامه حتى نهاية الاستجابة". `maxAmountRequired` هو **حد أقصى** (محسوب وفقًا للحد الأقصى المحدد في هذا النموذج: الحد الأقصى من الاعتمادات × 0.095215)، ويتم التسوية فعليًا وفقًا للاستخدام الحقيقي، ولا تتجاوز الحد الأقصى.

تفاصيل بروتوكول هذين النوعين من الخطط موجودة في [خطط الفوترة `exact` و `upto`](https://platform.acedata.cloud/documents/x402-metered-upto). فيما يلي نتحدث فقط عن الأسعار.

## أسعار الدردشة (إكمال الدردشة)

إكمال الدردشة يتم قياسه بـ `upto`: يتم احتساب الرسوم وفقًا للاستخدام الفعلي لـ prompt / completion token. سعر كل مليون (1M) token = `تكلفة الاعتمادات لكل 1M token في هذا النموذج × 0.095215`، وهو متطابق تمامًا مع السعر بالدولار الأمريكي المعروض في دليل النماذج العام للمنصة (`/api/v1/models?with_pricing=true`).

الجدول أدناه يوضح الأسعار الحقيقية (مأخوذة من دليل النماذج، وفقًا لسعر X402)، الوحدة USD / 1M token:

| النموذج | الإدخال / 1M | الإخراج / 1M | الحد الأقصى لـ `upto` |
| - | - | - | - |
| gpt-4o-mini | \$0.0796 | \$0.3183 | 1 Credit (0.095215 دولار) |
| gemini-2.5-flash | \$0.1591 | \$1.3262 | 5 Credits (0.476074 دولار) |
| gpt-5 / gpt-5.1 | \$0.6631 | \$5.3050 | 20 Credits (1.904299 دولار) |
| gemini-2.5-pro | \$0.6631 | \$5.3050 | 50 Credits (4.760750 دولار) |
| gpt-4.1 | \$1.0610 | \$4.2440 | 20 Credits (1.904299 دولار) |
| claude-sonnet-4-5 | \$0.6006 | \$3.0028 | 50 Credits (4.760750 دولار) |
| grok-4 | \$1.5915 | \$7.9574 | 10 Credits (0.952149 دولار) |
| claude-opus-4-1 | \$3.0028 | \$15.0140 | 50 Credits (4.760750 دولار) |

ملاحظات:

* الجدول يعرض سعر الوحدة حسب token؛ تكلفة الطلب الواحد = إدخال token × سعر الإدخال + إخراج token × سعر الإخراج.
* الحد الأقصى لـ `upto` هو المبلغ الأقصى المسموح بتوقيعه في طلب واحد لهذا النموذج؛ ليس هو المبلغ الفعلي المخصوم، حيث أن معظم الطلبات تكون أقل بكثير من الحد الأقصى.
* الحد الأقصى يحدد فقط "أقصى ما يمكن خصمه"، بينما يتم التسوية الفعلية وفقًا لاستخدام token.

### مثال: تطابق السعر والخصم ( `exact` )

فيما يلي استخدام X402Client الرسمي لإجراء استدعاء **مدفوع حقيقي** لـ `serp/google` (Base `exact`). يظهر هذا تطابق الثلاثة: سعر 402، المبلغ الموقّع، والاستجابة الناجحة التي تعيد `cost`.

```text theme={null}
# 1) طلب غير مدفوع -> 402، الحصول على السعر (لا خصم)
POST /serp/google  ->  402
base/exact maxAmountRequired = 952 atomic = $0.000952 = 0.01 Credit
# 0.01 × 0.095215 = 0.00095215، يتم التقريب لأسفل إلى atomic = 952

# 2) توقيع 952 atomic باستخدام المحفظة كـ PAYMENT-SIGNATURE، إعادة المحاولة
POST /serp/google (PAYMENT-SIGNATURE) -> 200
body.cost = {"amount": 0.000952, "currency": "usdc", "settlement": "authorized"}
```

响应返回的 `cost.amount`（0.000952 USDC）与 402 报价、与 `Credits × 0.095215` 完全一致。`settlement` 字段是该笔支付的结算状态（`authorized` = 已授权）；链上结算由平台处理，机制见 [`exact` 与 `upto` 计费方案](https://platform.acedata.cloud/documents/x402-metered-upto)。

### `upto` 报价计算（聊天）

聊天按 token 计量。某次请求的报价（不是上限）按下式计算（以 gpt-4o-mini 为例）：

```text theme={null}
Credits = 1e-6 × (0.835733 × prompt_tokens + 3.342933 × completion_tokens)
USDC    = Credits × 0.095215
```

一次 500 prompt + 200 completion token 的请求：

```text theme={null}
Credits = 1e-6 × (0.835733 × 500 + 3.342933 × 200) ≈ 0.001086 Credits
报价 USDC ≈ 0.001086 × 0.095215 ≈ $0.0001034
```

客户端按 `upto` 上限（gpt-4o-mini 为 1 Credit = `95215` atomic）签名，这只是**最多可能扣多少**；该次请求的真实报价（上例约 \$0.0001）远低于上限，按 token 用量结算。`upto` 的链上结算机制见 [`exact` 与 `upto` 计费方案](https://platform.acedata.cloud/documents/x402-metered-upto)。

## 其他服务价格（固定价 `exact`）

图片、视频、音乐、搜索这类接口在请求时价格即可确定，使用 `exact`。下表为真实价格，取自线上接口对未支付请求返回的 402 `maxAmountRequired`（查询报价不会产生扣费）：

| 服务 | 示例模型 / 参数 | Credits | USDC | atomic |
| - | - | - | - | - |
| 网页搜索 | serp/google，≤10 条结果 | 0.01 | \$0.000952 | 952 |
| 图片 | nano-banana | 0.14 | \$0.013330 | 13330 |
| 图片 | gpt-image-1，1024×1024 | 0.20 | \$0.019043 | 19043 |
| 图片 | flux-dev | 0.24 | \$0.022851 | 22851 |
| 图片 | midjourney imagine | 0.27 | \$0.025708 | 25708 |
| 图片 | seedream-4 | 0.32 | \$0.030468 | 30468 |
| 音乐 | suno generate | 0.55 | \$0.052368 | 52368 |
| 音乐 | producer generate | 0.68 | \$0.064746 | 64746 |
| 视频 | luma | 1.19 | \$0.113305 | 113305 |
| 视频 | hailuo（minimax-hailuo-2-3） | 1.72 | \$0.163769 | 163769 |
| 视频 | kling-v2-6 std | 2.10 | \$0.199951 | 199951 |
| 视频 | kling-v3 std | 4.20 | \$0.399903 | 399903 |
| 视频 | veo-3 text→video | 5.00 | \$0.476074 | 476074 |
| 视频 | seedance-1-0-pro，1080p / 5s | 5.60 | \$0.533204 | 533204 |
| 视频 | wan2.6-t2v | 13.50 | \$1.285402 | 1285402 |

说明：

* 同一服务的价格随**模型、分辨率、时长、动作**变化（尤其是视频）。上表是某一组参数下的真实取值，仅供量级参考。
* 这类固定价（`exact`）接口，该请求 402 响应里的 `maxAmountRequired` 即该次应付金额（与成功响应的 `cost.amount` 一致，上节已实测）。
* 每个价格都由 `Credits × 0.095215` 向下取整到 atomic 单位得到（见上文计价基准），与聊天用的是同一套换算。因浮点表示与取整，个别值可能与朴素乘积相差 1 atomic（\$0.000001），一律以 402 返回值为准。

## 订单支付价格

用 X402 支付控制台订单（购买套餐 / 充值 Credits）时，价格以订单页面显示为准，402 的 `amount` 为最终签名依据。订单支付走平台 API、需要账户令牌，详见 [订单支付教程](https://platform.acedata.cloud/documents/x402-order-payment)。

订单支付教程中的一个真实例子（购买 10 Credits）：

```text theme={null}
description Ace Data Cloud Credits x 10.0
created price 1.26          # 订单创建价（USD）
settled    1.20 USDC        # 最终签名/结算金额（= 402 amount）
            = 1200000 atomic USDC
```

注意：**按调用付费**（上文 Chat / 其他服务）和**订单支付**是两条不同路径。按调用付费统一用 `0.095215`/Credit 的最优档单价；订单支付按套餐定价，其创建价与最终结算金额的差异以 [订单支付教程](https://platform.acedata.cloud/documents/x402-order-payment) 为准。

## 如何实时获取价格

价格随模型和参数变化，请用程序实时获取，不要硬编码：

* **按调用价格**：对目标 API 发一次**不带** `PAYMENT-SIGNATURE`（也不带 `Authorization`）的请求，读取返回的 402 `accepts[].maxAmountRequired`。这一步不会扣费。对 `exact` 接口它是最终价格；对 `upto` 接口（聊天）它是上限，实际按用量结算。
* **聊天每 token 单价**：`GET https://platform.acedata.cloud/api/v1/models?with_pricing=true&type=chat`，读取每个模型的 `pricing.input_usd` / `pricing.output_usd`（已按 `credit_usd_rate` 计算）。
* **换算校验**：`atomic = floor(Credits × 0.095215 × 1e6)`，`USDC = atomic / 1e6`（即 `USDC ≈ Credits × 0.095215`）。

获取价格的最小请求示例：

```bash theme={null}
curl -sS -X POST https://x402.acedata.cloud/midjourney/imagine \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "a cat"}'
# 返回 402，accepts[].maxAmountRequired 即为该次（exact）调用价格
```

## 小结

* سعر X402 = تكلفة الاعتمادات لهذه المكالمة × `0.095215`، وهو نفس سعر الاعتمادات العادية، فقط يتم التسوية باستخدام USDC على السلسلة.
* `0.095215`/اعتماد هو **أفضل سعر** (للكميات الكبيرة) للاعتمادات؛ سعر الاعتمادات عند الشحن بكميات صغيرة أعلى، لذا فإن X402 تعني تلقائيًا الحصول على أفضل سعر.
* المبلغ الموقّع في واجهة `exact` (صور / فيديوهات / موسيقى / بحث / طلبات) هو المبلغ المستحق؛ المبلغ الموقّع في واجهة `upto` (دردشة) هو الحد الأقصى، ويتم التسوية حسب الاستخدام الفعلي.
* السعر المعتمد هو ما يتم إرجاعه في `maxAmountRequired` من 402: `exact` هو المبلغ المستحق (يتطابق مع `cost.amount` في الاستجابة الناجحة، وقد تم اختباره بالفعل)؛ `upto` هو الحد الأقصى، و`cost.amount` في الاستجابة الناجحة هو المبلغ الحقيقي الذي يتم تسويته حسب الاستخدام (≤ الحد الأقصى).

## الوثائق ذات الصلة

| الوثيقة | الرابط |
| - | - |
| دليل تكامل X402 (نظرة عامة) | [دليل تكامل X402](https://platform.acedata.cloud/documents/x402-integration) |
| البدء السريع | [البدء السريع X402](https://platform.acedata.cloud/documents/x402-quickstart) |
| خطط التسعير `exact` و `upto` | [شرح خطط التسعير](https://platform.acedata.cloud/documents/x402-metered-upto) |
| الشبكات وطرق الدفع | [الشبكات وطرق الدفع](https://platform.acedata.cloud/documents/x402-networks) |
| دليل دفع الطلبات | [دليل دفع الطلبات](https://platform.acedata.cloud/documents/x402-order-payment) |


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