# تاروت

ثلاث مجموعات: Rider-Waite-Smith (78 بطاقة)، تاروت مرسيلي (78) و لينورمان (36). كل بطاقة في كل استجابة للـتاروت تحتوي على صورة، و `POST /v1/interpret/tarot` يحول النشر إلى تفسير: كل موضع في السياق، ملخص كامل النشر ونصيحة واحدة.

## اختر تنسيق البطاقات

`GET /v1/tarot/decks` يرجع كل مجموعة، نشراتها ومجموعات التنسيق التي يمكن تمريرها كـ `art` إلى أي مسار تاروت (في جسم الـPOST أو كـ `?art=` في الـGET). جميع المجموعات هي ملكية عامة وتُقدم من CDN الخاص بنا.

| مجموعة | `art` | بطاقات |
|---|---|---|
| Rider-Waite-Smith | `rws-1909` (افتراضي)، `rws-restored`, `rws-vector` | 78 |
| مارسيلي تاروت | `arnoult-1748` | 78 |
| لينورمان | `dondorf` | 35 من 36، بدون القمر |

كل بطاقة تحصل على `image` مع `urlSmall` (300 بكسل عرضًا، للبطاقات حتى حوالي 150 بكسل على الصفحة)، `url` (600 بكسل)، `url2x` (1200 بكسل)، `width`، `height` و `art`. النشر أيضًا يرجع `back`، ظهر البطاقة، حتى تتمكن الصفحة من إظهار البطاقات مقلوبة في البداية. `art` لمجموعة أخرى يعطي `400 INVALID_ART` مع قائمة القيم المسموح بها. البطاقة التي لا توجد لها صورة في المجموعة (القمر في لينورمان) مذكورة في `missing` لهذه المجموعة وتأتي بدون `image`، لذا اعرض لها بطاقة نصية.

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    curl -X POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card \
      -H "X-Api-Key: aw_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{ "seed": 12345, "art": "rws-restored" }'
    ```
  </TabItem>
</Tabs>

```json
{
  "drawn": [
    {
      "position": { "index": 0, "name": "Past", "meaning": "Forces from the past shaping the situation." },
      "card": {
        "slug": "8-of-pentacles",
        "name": "Eight of Pentacles",
        "image": {
          "url": "https://cdn.astroway.info/tarot/rws-restored/8-of-pentacles.webp",
          "url2x": "https://cdn.astroway.info/tarot/rws-restored/8-of-pentacles@2x.webp",
          "urlSmall": "https://cdn.astroway.info/tarot/rws-restored/8-of-pentacles-300.webp",
          "width": 600,
          "height": 1028,
          "art": "rws-restored"
        }
      },
      "reversed": false
    }
  ],
  "back": { "url": "https://cdn.astroway.info/tarot/rws-1909/back.webp", "url2x": "https://cdn.astroway.info/tarot/rws-1909/back@2x.webp", "urlSmall": "https://cdn.astroway.info/tarot/rws-1909/back-300.webp", "width": 600, "height": 1039, "art": "rws-1909" }
}
```

نشر `POST /v1/tarot/rider-waite/draw/three-card` يكلف **10 أرصدة**.

## نصوص البطاقات بدون نموذج

`GET /v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=uk` يعمل بدون مفتاح ويعيد لكل بطاقة `description` من ثلاثة فقرات (الصورة، المعنى المستقيم، المعنى المقلوب) ونص عن `love`, `career`, `finance`, `health` و `spirit` للـ `upright` و `reversed`، مع اسم محلي `name` ومحددة حتى خمس `keywords` لكل جانب. بدون `cards` تُرجع جميع الـ78. النصوص لا تتغير، لذا حمّل البطاقات التي تعرضها الصفحة وخزنها مؤقتًا.

```bash
curl 'https://api.astroway.info/v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=uk'
```

## تفسير كامل النشر

`POST /v1/interpret/tarot` يستقبل مجموعة، نشر، بطاقات وسؤال اختياري ويكتب تفسيرًا باللغة المحددة بـ `language` (21 لغة). يمكن تمرير البطاقات كسلاسل، ككائنات `{ "slug", "reversed" }` أو كمصفوفة `drawn` من أي استجابة للنشر دون تعديل.

<Tabs>
  <TabItem label="Node.js">
    ```js
    const headers = { 'Content-Type': 'application/json', 'X-Api-Key': process.env.ASTROWAY_API_KEY };
    const api = (path, body) =>
      fetch(`https://api.astroway.info/v1${path}`, { method: 'POST', headers, body: JSON.stringify(body) }).then((r) => r.json());
    
    const { data: spread } = await api('/tarot/rider-waite/draw/three-card', { art: 'rws-1909' });
    const { data: reading } = await api('/interpret/tarot', {
      spread: 'three-card',
      question: 'What should I focus on at work?',
      cards: spread.drawn,
      language: 'en',
    });
    
    for (const p of reading.positions) {
      console.log(p.position, p.card.name, p.reversed ? '(reversed)' : '', p.card.image.url);
      console.log(' ', p.reading);
    }
    console.log('Summary:', reading.synthesis);
    ```
  </TabItem>
</Tabs>

في الاستجابة `positions[]` (موضع، بطاقة مع `image`, `reversed`, `reading`)، `synthesis`, `advice` و `disclaimer`. بطاقات Rider-Waite-Smith لديها أيضًا `nameLocalized` و `positionLocalized` بلغة التفسير. التفسير يكلف **100 أرصدة** (Tier 4) ومتوفر في خطة Free؛ مع مفتاح نموذجك الخاص يكون أرخص، انظر [مفتاحك الخاص للنموذج](/agent-setup/).

<Aside type="note">
التفسير هو نص مولد بناءً على المعنى التقليدي لكل بطاقة في موضعها. الـAPI يربط البطاقات، مواضعها ومواقعها بطلبك ويستبعد التفسير الذي يتخطى بطاقة، لكن اعتبر النص كدافع للتفكير وليس تنبؤًا.
</Aside>