# Tarot

Tres barajas: Rider-Waite-Smith (78 cartas), Tarot de Marsella (78) y Lenormand (36). Cada carta en cada respuesta de tarot tiene una imagen, y `POST /v1/interpret/tarot` convierte la tirada en una interpretación: cada posición en contexto, el resumen de toda la tirada y un consejo.

## Elige el diseño de las cartas

`GET /v1/tarot/decks` devuelve cada baraja, sus tiradas y los conjuntos de diseño que puedes pasar como `art` en cualquier ruta de tarot (en el cuerpo POST o como `?art=` en GET). Todos los conjuntos son de dominio público y se sirven desde nuestro CDN.

| Baraja | `art` | Cartas |
|---|---|---|
| Rider-Waite-Smith | `rws-1909` (por defecto), `rws-restored`, `rws-vector` | 78 |
| Tarot de Marsella | `arnoult-1748` | 78 |
| Lenormand | `dondorf` | 35 de 36, sin la Luna |

Cada carta recibe un `image` con `urlSmall` (300 px de ancho, para cartas de aproximadamente 150 px en la página), `url` (600 px), `url2x` (1200 px), `width`, `height` y `art`. La tirada también devuelve `back`, el reverso de la carta, para que la página pueda mostrar primero las cartas boca abajo. Un `art` de otra baraja devuelve `400 INVALID_ART` con la lista de valores válidos. Una carta para la que el conjunto no tiene imagen (la Luna en Lenormand) está indicada en `missing` de ese conjunto y llega sin `image`, así que muestra para ella una carta de texto.

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

La tirada `POST /v1/tarot/rider-waite/draw/three-card` cuesta **10 créditos**.

## Textos de las cartas sin modelo

`GET /v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=uk` funciona sin clave y devuelve para cada carta una `description` de tres párrafos (imagen, significado derecho, significado invertido) y texto sobre `love`, `career`, `finance`, `health` y `spirit` para `upright` y `reversed`, junto con el nombre localizado `name` y hasta cinco `keywords` por lado. Sin `cards` se devuelven todas las 78. Los textos no cambian, así que descarga las cartas que muestra la página y cachéjalas.

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

## Interpretación de toda la tirada

`POST /v1/interpret/tarot` acepta la baraja, la tirada, las cartas y una pregunta opcional, y escribe la interpretación en el idioma especificado por `language` (21 idiomas). Las cartas se pueden pasar como parámetros, objetos `{ "slug", "reversed" }` o un arreglo `drawn` de cualquier respuesta de tirada sin modificaciones.

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

En la respuesta `positions[]` (posición, carta con `image`, `reversed`, `reading`), `synthesis`, `advice` y `disclaimer`. Las cartas Rider-Waite-Smith también tienen `nameLocalized` y `positionLocalized` en el idioma de la interpretación. La interpretación cuesta **100 créditos** (Tier 4) y está disponible en el plan Free; con tu propia clave de modelo es más barata, mira [Tu clave para el modelo](/agent-setup/).

<Aside type="note">
La interpretación es un texto generado basado en el significado tradicional de cada carta en su posición. El API asocia las cartas, su posición y posición a tu solicitud y descarta la interpretación que omite una carta, pero considera el texto como una guía para reflexionar, no como una predicción.
</Aside>