塔罗牌阵API文档

接口说明

本接口用于生成塔罗牌阵，支持多种经典牌阵（如单张牌、三张牌、凯尔特十字等）。接口可返回牌阵的详细信息、生成的牌阵图片（Base64编码）以及由AI生成的详细解读。

基本信息

参数	值
Base URL	`https://chart.12sign.top`
接口URL	`/api/tarot/spread`
请求方式	POST
Content-Type	application/json

请求参数

参数名	类型	必选	说明
spread_type	string	是	牌阵类型代码。可选值：`1card` (单张牌), `3card` (时间之流/圣三角), `5card` (二选一), `celtic` (凯尔特十字), `arrow` (爱之维纳斯), `holy_triangle` (神圣三角), `love_triangle` (爱情三角), `elements` (四大元素), `seasons` (四季牌阵), `two_paths` (二选一详细版) 等。
include_image	boolean	否	是否生成牌阵图片。默认为 `true`。
include_ai	boolean	否	是否包含AI解读。默认为 `false`。注意：此功能需要调用 AI 服务，响应时间较长（约 10-30 秒）。
question	string	否	用户咨询的问题（如"我的财运如何？"）。当 `include_ai` 为 `true` 时，此字段用于辅助AI进行针对性解读。

请求示例

示例 1：仅抽牌（不含AI解读）

{
  "spread_type": "1card",
  "include_image": true
}

示例 2：抽牌 + AI解读

{
  "spread_type": "celtic",
  "include_image": true,
  "include_ai": true,
  "question": "我最近的工作变动会对未来产生什么影响？"
}

返回参数

参数名	类型	说明
spread_type	string	请求时的牌阵类型，如 "1card", "3card", "celtic" 等。
spread_description	string	牌阵的英文描述，如 "One card tarot reading"。
deck	string	使用的牌组名称，如 "swiss"。
cards	array	抽出的卡牌列表，包含每张牌的详细信息。
cards[].id	integer	卡牌ID。正数表示正位，负数表示逆位。
cards[].name	string	卡牌英文名称。
cards[].facing	string	牌面方向：`upright` (正位) 或 `reversed` (逆位)。
cards[].meaning	string	当前方向的牌意解释。
cards[].image_path	string	卡牌图片路径。
cards[].position	integer	在牌阵中的位置编号（从1开始）。
cards[].position_name	string	位置名称（如 "Daily Card", "Card 1" 等）。
cards[].position_type	string	位置类型，如 "sequential" (顺序牌)。
cards[].details	array	卡牌详细信息，包含元素、数字、正位/逆位含义等。
image_base64	string	牌阵图片的 Base64 编码。仅在 `include_image` 为 `true` 时返回。
ai_response	string	(可选) AI生成的详细解读文本。仅在 `include_ai` 为 `true` 时返回。

返回示例

{
  "spread_type": "3card",
  "spread_description": "Three card tarot reading",
  "deck": "swiss",
  "cards": [
    {
      "id": 45,
      "name": "Nine of Swords",
      "facing": "upright",
      "meaning": "anxiety, hopelessness, trauma",
      "image_path": "/code/common/../decks/tarot/swiss/9S.jpg",
      "position": 1,
      "position_name": "Card 1",
      "position_type": "sequential",
      "details": [
        ["Suit:", "Swords"],
        ["Rank:", "9"],
        ["Element:", "Air"],
        ["Upright Meaning:", "anxiety, hopelessness, trauma"],
        ["Reversed Meaning:", "emotional baggage, unresolved issues"]
      ]
    },
    {
      "id": -42,
      "name": "Six of Swords",
      "facing": "reversed",
      "meaning": "emotional baggage, unresolved issues, resisting transition",
      "image_path": "/code/common/../decks/tarot/swiss/6S.jpg",
      "position": 2,
      "position_name": "Card 2",
      "position_type": "sequential",
      "details": [
        ["Suit:", "Swords"],
        ["Rank:", "6"],
        ["Element:", "Air"],
        ["Upright Meaning:", "transition, leaving behind, moving on"],
        ["Reversed Meaning:", "emotional baggage, unresolved issues"]
      ]
    },
    {
      "id": 22,
      "name": "The World",
      "facing": "upright",
      "meaning": "fulfillment, harmony, completion",
      "image_path": "/code/common/../decks/tarot/swiss/21M.jpg",
      "position": 3,
      "position_name": "Card 3",
      "position_type": "sequential",
      "details": [
        ["Suit:", "Majors"],
        ["Number:", "21"],
        ["Upright Meaning:", "fulfillment, harmony, completion"],
        ["Reversed Meaning:", "incompletion, no closure"]
      ]
    }
  ],
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "ai_response": "..."
}

使用说明

注意事项：

牌阵类型代码必须为支持的值，否则会返回错误。
卡牌的 facing 字段为 upright（正位）或 reversed（逆位）。
卡牌的 id 正数表示正位，负数表示逆位。
当 include_ai 为 true 时，响应时间较长（通常 10-30 秒），请合理设置请求超时时间。
image_base64 返回的是完整的 Base64 编码图片，可直接用于 <img src="data:image/png;base64,...">。
返回的 details 数组包含卡牌的详细信息，如元素、数字、正位/逆位含义等。

应用场景

每日运势 - 使用单张牌牌阵快速获取每日指引
关系分析 - 使用爱情三角或爱之维纳斯牌阵分析感情问题
决策辅助 - 使用二选一牌阵帮助做出选择
深度解读 - 使用凯尔特十字牌阵进行全面的形势分析
元素平衡 - 使用四大元素牌阵了解能量分布

Python测试代码示例

import requests
import json
import base64
import os

def test_tarot_spread(base_url="https://chart.12sign.top"):
    url = f"{base_url}/api/tarot/spread"

    # 测试1：单张牌
    payload = {
        "spread_type": "1card",
        "include_image": True,
        "include_ai": False
    }

    try:
        print("正在测试单张牌塔罗API...")
        response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'})
        print(f"响应状态码: {response.status_code}")

        if response.status_code == 200:
            data = response.json()
            print(f"牌阵类型: {data.get('spread_type')}")
            print(f"牌阵描述: {data.get('spread_description')}")
            print(f"牌组: {data.get('deck')}")
            print(f"卡牌数量: {len(data.get('cards', []))}")

            # 保存牌阵图片
            if data.get('image_base64'):
                import base64
                import os
                os.makedirs('test_outputs', exist_ok=True)
                img_data = base64.b64decode(data['image_base64'])
                with open('test_outputs/tarot_spread.png', 'wb') as f:
                    f.write(img_data)
                print("牌阵图片已保存: test_outputs/tarot_spread.png")

            # 打印卡牌信息
            for card in data.get('cards', []):
                facing_str = " (逆位)" if card.get('facing') == 'reversed' else ""
                print(f"位置{card.get('position')} [{card.get('position_name')}]: {card.get('name')}{facing_str}")
                print(f"  牌意: {card.get('meaning')}")

            return data
        else:
            print(f"API请求失败: {response.status_code}")
            print(f"错误信息: {response.text}")
            return None

    except Exception as e:
        print(f"请求出错: {e}")
        return None

def test_tarot_with_ai(base_url="https://chart.12sign.top"):
    url = f"{base_url}/api/tarot/spread"

    # 测试2：凯尔特十字 + AI解读
    payload = {
        "spread_type": "celtic",
        "include_image": True,
        "include_ai": True,
        "question": "我最近的工作变动会对未来产生什么影响？"
    }

    try:
        print("\n正在测试凯尔特十字+AI解读...")
        response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'})

        if response.status_code == 200:
            data = response.json()
            print(f"卡牌数量: {len(data.get('cards', []))}")
            if data.get('ai_response'):
                print("\n=== AI解读 ===")
                print(data['ai_response'])
            return data
        else:
            print(f"AI解读请求失败: {response.status_code}")
            return None

    except Exception as e:
        print(f"请求出错: {e}")
        return None

if __name__ == "__main__":
    test_tarot_spread()
    test_tarot_with_ai()

在线测试

请求地址：

https://chart.12sign.top/api/tarot/spread

请求参数（JSON）：

返回结果：

点击"发送请求"后在此显示结果

牌阵图片：

牌阵图片将在请求成功后显示在这里

抽出的卡牌：

卡牌信息将在请求成功后显示在这里

AI解读：

AI解读将在请求成功后显示在这里（需设置 include_ai: true）