# Tarocchi

Tre mazzi: Rider-Waite-Smith (78 carte), Marsiglia Tarocchi (78) e Lenormand (36). Ogni carta in ogni risposta del tarocco ha un'immagine, e `POST /v1/interpret/tarot` trasforma lo spread in un'interpretazione: ogni posizione nel contesto, il riepilogo di tutto lo spread e un consiglio.
## Scegli lo stile delle carte
`GET /v1/tarot/decks` restituisce ogni mazzo, i suoi spread e i set di stile che possono essere passati come `art` in qualsiasi percorso del tarocco (nel corpo POST o come `?art=` in GET). Tutti i set sono di pubblico dominio e vengono forniti dal nostro CDN.

| Mazzo | `art` | Carte |
|---|---|---|
| Rider-Waite-Smith | `rws-1909` (tipo predefinito), `rws-restored`, `rws-vector` | 78 |
| Marsiglia Tarocchi | `arnoult-1748` | 78 |
| Lenormand | `dondorf` | 35 su 36, senza il Mese

Ogni carta riceve un `image` con `urlSmall` (300 px di larghezza, per le carte circa 150 px sulla pagina), `url` (600 px), `url2x` (1200 px), `width`, `height` e `art`. Lo spread restituisce anche `back`, il retro della carta, così la pagina può mostrare inizialmente le carte coperte. Un `art` di un altro mazzo restituisce `400 INVALID_ART` con l'elenco dei valori validi. Una carta per cui nel set manca l'immagine (il Mese nel Lenormand) è indicata nel `missing` di quel set e arriva senza `image`, quindi mostrale come una carta di testo.

<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" }
}
```

Lo spread `POST /v1/tarot/rider-waite/draw/three-card` costa **10 crediti**.

## Testi delle carte senza modello
`GET /v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=uk` funziona senza chiave e restituisce per ogni carta una `description` di tre paragrafi (immagine, significato diretto, significato rovesciato) e testo su `love`, `career`, `finance`, `health` e `spirit` per `upright` e `reversed`, insieme al nome localizzato `name` e fino a cinque `keywords` per ciascun lato. Senza `cards` vengono restituite tutte le 78 carte. I testi non cambiano, quindi scarica le carte che la pagina mostra e memorizzale nella cache.

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

## Interpretazione di tutto lo spread
`POST /v1/interpret/tarot` accetta il mazzo, lo spread, le carte e una domanda opzionale e scrive l'interpretazione nella lingua specificata da `language` (21 lingue). Le carte possono essere inviate come valori separati, oggetti `{ "slug", "reversed" }` o come array `drawn` da qualsiasi risposta di spread senza modifiche.

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

Nella risposta `positions[]` (posizione, carta con `image`, `reversed`, `reading`), `synthesis`, `advice` e `disclaimer`. Le carte Rider-Waite-Smith hanno anche `nameLocalized` e `positionLocalized` nella lingua dell'interpretazione. L'interpretazione costa **100 crediti** (Tier 4) ed è disponibile nel piano Free; con la propria chiave del modello è più economica, vedere [La tua chiave del modello](/agent-setup/).

<Aside type="note">
L'interpretazione è un testo generato basato sul significato tradizionale di ogni carta nella sua posizione. L'API associa le carte, la loro posizione e il loro orientamento alla tua richiesta e scarta l'interpretazione che salta una carta, ma considera il testo come un spunto per riflettere, non come una previsione.
</Aside>