{
  "openapi": "3.1.0",
  "info": {
    "title": "Dika Neural Translation & Dictionary API",
    "description": "\n# 🚀 پلتفرم جامع هوش مصنوعی و وب‌سرویس ترجمه دیکا (Dika AI Translation API)\n\nبه مستندات تعاملی **وب‌سرویس و API چندزبانه دیکا (نسخه ۳.۹.۰)** خوش آمدید. این وب‌سرویس توسط **شرکت راهکار الکترونیک سهند ([irres.ir](https://irres.ir))** توسعه یافته و کلیه قابلیت‌های ترجمه عصبی، استخراج متن از تصویر (OCR)، تبدیل متن به صوت (TTS)، بومی‌سازی صفحات HTML، مدیریت واژه‌نامه تخصصی (Glossary) و درگاه پرداخت آنلاین متصل به **[spinora.ir](https://spinora.ir)** را در قالب اندپوینت‌های استاندارد RESTful و Server-Sent Events (SSE) ارائه می‌دهد.\n\n---\n\n### 🔑 نحوه احراز هویت (Authentication)\nکلیه درخواست‌ها باید کلید معتبر را در هدر ارسال کنند:\n- هدر پیشنهادی: `X-API-Key: dika_dev_your_api_key`\n- یا هدر استاندارد: `Authorization: Bearer dika_dev_your_api_key`\n- درخواست‌های مدیریت ارشد (Admin): `Authorization: Bearer <DIKA_ADMIN_TOKEN>`\n\n---\n\n### 🌐 زبان‌های پشتیبانی‌شده (۲۴ زبان):\n`fa` (فارسی), `en` (انگلیسی), `ar` (عربی), `tr` (ترکی استانبولی), `az` (آذربایجانی), `ckb` (کردی سورانی), `kmr` (کردی کرمانجی), `ur` (اردو), `ps` (پشتو), `tg` (تاجیکی), `tk` (ترکمنی), `hy` (ارمنی), `ka` (گرجی), `ru` (روسی), `fr` (فرانسوی), `de` (آلمانی), `es` (اسپانیایی), `it` (ایتالیایی), `pt` (پرتغالی), `nl` (هلندی), `zh` (چینی), `ja` (ژاپنی), `ko` (کره‌ای), `hi` (هندی).\n\n---\n\n### 🎭 لحن‌ها و سبک‌های ترجمه قابل انتخاب (`tone`):\n- `general`: ترجمه استاندارد و عمومی (پیش‌فرض)\n- `formal`: اداری، رسمی و حقوقی (تبدیل افعال شکسته به رسمی)\n- `academic`: دانشگاهی، علمی و مقالات تخصصی\n- `casual`: عامیانه، صمیمی و گفتاری\n- `technical`: فنی، برنامه‌نویسی و مهندسی نرم‌افزار\n- `medical`: پزشکی، پیراپزشکی و داروسازی\n\n---\n\n### ⚡ سقف مجاز درخواست‌ها (Rate Limits):\n- **پلن توسعه‌دهنده (Developer):** ۱۲۰ درخواست در دقیقه (120 RPM) | سقف ۵۰,۰۰۰ کاراکتر روزانه\n- **پلن سازمانی (Enterprise):** ۶۰۰ تا ۱,۲۰۰ درخواست در دقیقه | سقف ۵,۰۰۰,۰۰۰ کاراکتر ماهانه\n\n---\n\n### 💳 درگاه پرداخت متصل (Payment Gateway):\nسیستم صدور فاکتور و خرید آنلاین اشتراک به‌صورت مستقیم به درگاه پرداخت فعال **spinora.ir** متصل است و تراکنش‌ها با واحد پولی **تومان (IRT)**، **ریال (IRR)** یا **دلار (USD)** پردازش می‌شوند.\n",
    "contact": {
      "name": "شرکت راهکار الکترونیک سهند (Sahand Electronic Solutions)",
      "url": "https://irres.ir/",
      "email": "support@irres.ir"
    },
    "license": {
      "name": "Commercial / Proprietary",
      "url": "https://irres.ir/terms"
    },
    "version": "3.9.8"
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "General"
        ],
        "summary": "بررسی وضعیت سرویس (Health Check)",
        "description": "تست اتصال به سرور و اطمینان از آماده‌به‌کار بودن موتور هوش مصنوعی و دیتابیس.",
        "operationId": "api_root_api_v1_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/api": {
      "get": {
        "tags": [
          "General"
        ],
        "summary": "بررسی سلامت و مشخصات سرور (API Health & Service Root)",
        "description": "استعلام زنده بودن سرویس ترجمه، نسخه پلتفرم، آدرس مستندات تعاملی Swagger و تعداد زبان‌های فعال سیستم.",
        "operationId": "api_root_api_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/api/v1/dictionary": {
      "get": {
        "tags": [
          "Dictionary"
        ],
        "summary": "جستجوی واژه در دیکشنری (GET Word Lookup)",
        "description": "جستجوی سریع یک واژه در دیکشنری از طریق پارامتر کوئری GET، به همراه معانی فارسی/انگلیسی، فونتیک، مثال‌ها و نقش گرامری کلمه.",
        "operationId": "get_dictionary_word_api_v1_dictionary_get",
        "parameters": [
          {
            "name": "word",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Word"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/languages": {
      "get": {
        "tags": [
          "Languages"
        ],
        "summary": "فهرست ۲۴ زبان پشتیبانی‌شده (Get Supported Languages)",
        "description": "دریافت آرایه کامل ۲۴ زبان فعال در پلتفرم شامل کدهای استاندارد ISO 639-1 (مانند fa, en, tr, ar)، کدهای استاندارد بین‌المللی FLORES، نام بومی زبان‌ها و جهت نوشتاری (RTL راست‌به‌چپ یا LTR چپ‌به‌راست).",
        "operationId": "get_languages_api_v1_languages_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/api/v1/detect": {
      "post": {
        "tags": [
          "Language Detection"
        ],
        "summary": "تشخیص خودکار زبان متن (Automatic Language Detection)",
        "description": "شناسایی زبان متن ورودی از میان ۲۴ زبان با تحلیل حروف اختصاصی، ریشه‌شناسی واژگان و الگوهای بیزی بدون نیاز به تعیین قبلی توسط کاربر.",
        "operationId": "detect_lang_endpoint_api_v1_detect_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DetectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/translate": {
      "post": {
        "tags": [
          "Translation"
        ],
        "summary": "ترجمه متون چندزبانه با تعیین لحن (Neural Text Translation)",
        "description": "موتور اصلی ترجمه متون ساده یا دسته‌ای (Batch). امکان تعیین لحن (`tone`): عمومی (`general`)، رسمی و اداری (`formal`)، دانشگاهی و علمی (`academic`)، عامیانه و گفتاری (`casual`)، فنی و IT (`technical`) و پزشکی (`medical`). همچنین با ارسال format='html' تگ‌های سند حفظ می‌شوند.",
        "operationId": "translate_endpoint_api_v1_translate_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/translate/stream": {
      "post": {
        "tags": [
          "Translation"
        ],
        "summary": "Translate Stream Endpoint",
        "description": "Real-Time Streaming Translation (Server-Sent Events / SSE).\nYields translated chunks sentence-by-sentence with non-blocking async execution.",
        "operationId": "translate_stream_endpoint_api_v1_translate_stream_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StreamTranslationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tts": {
      "get": {
        "tags": [
          "Speech"
        ],
        "summary": "Tts Endpoint",
        "description": "High-Quality Neural Audio TTS Proxy.\nFetches pronunciation audio streams from neural speech services with proper headers,\ncaching, and fallback so all web browsers, phones, and operating systems can play audio reliably.",
        "operationId": "tts_endpoint_api_v1_tts_get",
        "parameters": [
          {
            "name": "text",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "title": "Text"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 10,
              "default": "en",
              "title": "Lang"
            }
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Action"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ocr": {
      "post": {
        "tags": [
          "OCR (Image Text Extraction)"
        ],
        "summary": "استخراج متن از تصویر (Optical Character Recognition)",
        "description": "Universal High-Precision OCR Endpoint.\n- Accepts base64 encoded image string or Data URL.\n- Supports 24 languages including Persian (fa), English (en), Arabic (ar), Turkish (tr), Russian (ru), etc.\n- Seamlessly falls back between Windows Media OCR, Tesseract, and Neural Cloud OCR.",
        "operationId": "ocr_endpoint_api_v1_ocr_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OCRRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ocr/status": {
      "get": {
        "tags": [
          "OCR (Image Text Extraction)"
        ],
        "summary": "بررسی وضعیت و قابلیت‌های موتور OCR",
        "description": "Check whether offline and online OCR capabilities are ready for the selected language.",
        "operationId": "ocr_status_endpoint_api_v1_ocr_status_get",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Language code to check",
              "default": "auto",
              "title": "Lang"
            },
            "description": "Language code to check"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/document/extract": {
      "post": {
        "tags": [
          "Document Translation"
        ],
        "summary": "استخراج ساختار و عناصر سند با حفظ استایل و جداول (Document Element Extraction)",
        "description": "استخراج تیترها، پاراگراف‌ها، جداول، زیرنویس‌ها، فرمول‌ها و تصاویر سند برای ترجمه هوشمند.",
        "operationId": "document_extract_endpoint_api_v1_document_extract_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentExtractRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/document/generate": {
      "post": {
        "tags": [
          "Document Translation"
        ],
        "summary": "تولید و دانلود سند ترجمه‌شده با فرمت اصلی (Exact Same Format Document Generator)",
        "description": "تولید فایل نهایی ترجمه‌شده با حفظ ۱۰۰٪ استایل، تصاویر، جداول، فرمول‌ها و فرمت اصلی سورس (.docx, .xlsx, .srt, .vtt, .ass, .csv, .md, .json, .html, .txt).",
        "operationId": "document_generate_endpoint_api_v1_document_generate_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/localize/json": {
      "post": {
        "tags": [
          "i18n & Localization"
        ],
        "summary": "Localize Json Endpoint",
        "operationId": "localize_json_endpoint_api_v1_localize_json_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LocalizeJsonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/stats": {
      "get": {
        "tags": [
          "Developer Analytics"
        ],
        "summary": "Get Analytics Stats",
        "operationId": "get_analytics_stats_api_v1_analytics_stats_get",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dictionary/lookup": {
      "post": {
        "tags": [
          "Dictionary"
        ],
        "summary": "Dictionary Lookup",
        "description": "Instant 50,000+ word dictionary search with SQLite index and FTS5 prefix match.",
        "operationId": "dictionary_lookup_api_v1_dictionary_lookup_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DictLookupRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dictionary/search": {
      "post": {
        "tags": [
          "Dictionary"
        ],
        "summary": "Dictionary Search",
        "description": "Full-Text search across 50,000+ words, definitions, and Persian meanings using SQLite FTS5.",
        "operationId": "dictionary_search_api_v1_dictionary_search_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DictSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/generate": {
      "post": {
        "tags": [
          "Developer Authentication"
        ],
        "summary": "Generate Api Key",
        "operationId": "generate_api_key_api_v1_keys_generate_post",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyGenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/list": {
      "get": {
        "tags": [
          "Developer Authentication"
        ],
        "summary": "List Api Keys",
        "description": "List project keys (Admin sees all, key owners see their own authenticated key).",
        "operationId": "list_api_keys_api_v1_keys_list_get",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/report": {
      "get": {
        "tags": [
          "Developer Authentication"
        ],
        "summary": "گزارش زنده وضعیت و سهمیه کلید کاربری (User Live Quota Report)",
        "description": "Get real-time consumption report and quota breakdown for the authenticated API key.",
        "operationId": "get_my_key_report_api_v1_keys_report_get",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/me": {
      "get": {
        "tags": [
          "Developer Authentication"
        ],
        "summary": "گزارش زنده وضعیت و سهمیه کلید کاربری (User Live Quota Report)",
        "description": "Get real-time consumption report and quota breakdown for the authenticated API key.",
        "operationId": "get_my_key_report_api_v1_keys_me_get",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List Webhook Events",
        "operationId": "list_webhook_events_api_v1_webhooks_events_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/subscribe": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Subscribe Webhook",
        "operationId": "subscribe_webhook_api_v1_webhooks_subscribe_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookSubscribeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Test Webhook Dispatch",
        "operationId": "test_webhook_dispatch_api_v1_webhooks_test_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookTestRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/proxy/test": {
      "post": {
        "tags": [
          "Admin & Gateway Settings"
        ],
        "summary": "Test Proxy Connection on Server",
        "operationId": "proxy_test_endpoint_api_v1_proxy_test_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProxyTestRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/proxy/fetch-webpage": {
      "get": {
        "tags": [
          "HTML Localization"
        ],
        "summary": "Proxy Fetch Webpage Content (GET)",
        "operationId": "proxy_fetch_webpage_get_api_v1_proxy_fetch_webpage_get",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Url"
            }
          },
          {
            "name": "use_tor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false,
              "title": "Use Tor"
            }
          },
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "HTML Localization"
        ],
        "summary": "Proxy Fetch Webpage Content (POST)",
        "operationId": "proxy_fetch_webpage_post_api_v1_proxy_fetch_webpage_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebpageProxyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/plans": {
      "get": {
        "tags": [
          "Billing & Payments"
        ],
        "summary": "مشاهده پلن‌های اشتراک و بسته‌های اعتباری (Get Billing Plans)",
        "description": "دریافت مشخصات پلن‌های اشتراک ماهانه (پایه، حرفه‌ای، سازمانی) و بسته‌های اعتباری نویسه به همراه تعرفه‌ها و امکانات.",
        "operationId": "get_billing_plans_api_v1_billing_plans_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/checkout": {
      "post": {
        "tags": [
          "Billing & Payments"
        ],
        "summary": "Billing Checkout",
        "description": "Initiate a payment order with Spinora or other configured payment gateways.",
        "operationId": "billing_checkout_api_v1_billing_checkout_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/verify": {
      "post": {
        "tags": [
          "Billing & Payments"
        ],
        "summary": "Billing Verify",
        "description": "Verify payment completion idempotently with payment gateway and activate user quota / API key.",
        "operationId": "billing_verify_api_v1_billing_verify_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentVerifyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/settings": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "مشاهده تنظیمات درگاه‌های پرداخت و سیستم (Admin Get Settings)",
        "description": "دریافت وضعیت و پیکربندی درگاه پرداخت پیش‌فرض (اسپینورا، زرین‌پال، زیبال، آی‌دی‌پی)، واحد پولی تسویه و آدرس‌های پرداخت (نیاز به توکن ادمین).",
        "operationId": "get_admin_settings_api_v1_admin_settings_get",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Update Admin Settings",
        "description": "Update payment gateways and platform configuration (Admin only).",
        "operationId": "update_admin_settings_api_v1_admin_settings_post",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminSettingsUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/payments": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "مشاهده گزارش و سوابق پرداخت‌ها (Admin Payment Reports)",
        "description": "مشاهده لیست کامل تراکنش‌های پرداختی کاربران، مبالغ، درگاه‌های استفاده‌شده و وضعیت تسویه حساب‌ها (نیاز به توکن ادمین).",
        "operationId": "get_admin_payments_api_v1_admin_payments_get",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "title": "Limit"
            }
          },
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/users": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "مشاهده لیست کامل کاربران و میزان مصرف (Admin User List)",
        "description": "Get full list of registered clients and keys with live today's consumption.",
        "operationId": "list_admin_users_api_v1_admin_users_get",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/users/update": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "به‌روزرسانی سطح و اعتبار کاربر (Admin Update User)",
        "description": "Update user tier, credits, or project name.",
        "operationId": "update_admin_user_api_v1_admin_users_update_post",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminUserUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/users/revoke": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "ابطال و حذف کلید کاربر (Admin Revoke Key)",
        "description": "Revoke and permanently remove user key.",
        "operationId": "revoke_admin_user_api_v1_admin_users_revoke_post",
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminUserRevokeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/glossary": {
      "get": {
        "tags": [
          "Translation Memory & Glossary"
        ],
        "summary": "Get Glossary Endpoint",
        "description": "Retrieve domain-specific glossary terms and translation memory rules.",
        "operationId": "get_glossary_endpoint_api_v1_glossary_get",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "source_lang",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Source Lang"
            }
          },
          {
            "name": "target_lang",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Target Lang"
            }
          },
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Translation Memory & Glossary"
        ],
        "summary": "Add Glossary Endpoint",
        "description": "Add a custom domain term to the organization's Translation Memory.",
        "operationId": "add_glossary_endpoint_api_v1_glossary_post",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GlossaryTermRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/glossary/{term_id}": {
      "delete": {
        "tags": [
          "Translation Memory & Glossary"
        ],
        "summary": "Delete Glossary Endpoint",
        "description": "Delete a custom glossary term.",
        "operationId": "delete_glossary_endpoint_api_v1_glossary__term_id__delete",
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "term_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Term Id"
            }
          },
          {
            "name": "authorization",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AdminSettingsUpdateRequest": {
        "properties": {
          "settings": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Settings",
            "description": "Dictionary of key-value gateway settings"
          },
          "default_gateway": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Default Gateway"
          },
          "currency": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Currency"
          },
          "spinora_payment_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Spinora Payment Url"
          },
          "spinora_api_key": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Spinora Api Key"
          },
          "spinora_merchant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Spinora Merchant Id"
          },
          "zarinpal_merchant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Zarinpal Merchant Id"
          },
          "zarinpal_sandbox": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Zarinpal Sandbox"
          },
          "zibal_merchant": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Zibal Merchant"
          },
          "zibal_merchant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Zibal Merchant Id"
          },
          "idpay_api_key": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Idpay Api Key"
          },
          "payment_gateway_mock": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Payment Gateway Mock"
          }
        },
        "additionalProperties": true,
        "type": "object",
        "title": "AdminSettingsUpdateRequest"
      },
      "AdminUserRevokeRequest": {
        "properties": {
          "key_id": {
            "type": "string",
            "title": "Key Id",
            "description": "شناسه یا هش کلید کاربری جهت ابطال"
          }
        },
        "type": "object",
        "required": [
          "key_id"
        ],
        "title": "AdminUserRevokeRequest"
      },
      "AdminUserUpdateRequest": {
        "properties": {
          "key_id": {
            "type": "string",
            "title": "Key Id",
            "description": "شناسه یا هش کلید کاربری"
          },
          "tier": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tier",
            "description": "سطح دسترسی: Developer یا Enterprise"
          },
          "credits": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credits",
            "description": "تنظیم مستقیم اعتبار کاراکتر"
          },
          "add_credits": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Add Credits",
            "description": "افزایش اعتبار کاراکتر"
          },
          "project_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Project Name",
            "description": "نام پروژه یا سازمان"
          }
        },
        "type": "object",
        "required": [
          "key_id"
        ],
        "title": "AdminUserUpdateRequest"
      },
      "CheckoutRequest": {
        "properties": {
          "plan_id": {
            "type": "string",
            "title": "Plan Id",
            "description": "Plan ID (e.g. pro, enterprise, pack_100k, pack_1m)"
          },
          "user_email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "User Email",
            "description": "Customer email address"
          },
          "email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Email",
            "description": "Customer email address alias"
          },
          "user_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "User Name",
            "description": "Customer full name",
            "default": "Customer"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name",
            "description": "Customer name alias"
          },
          "gateway": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Gateway",
            "description": "Preferred gateway: spinora, zarinpal, zibal, idpay"
          },
          "callback_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Callback Url",
            "description": "Redirect URL after payment completion"
          }
        },
        "type": "object",
        "required": [
          "plan_id"
        ],
        "title": "CheckoutRequest"
      },
      "DetectionRequest": {
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 20000,
            "title": "Text",
            "description": "نمونه متن جهت شناسایی و تشخیص خودکار زبان از میان ۲۴ زبان پشتیبانی‌شده.",
            "examples": [
              "Bonjour tout le monde, comment allez-vous today?"
            ]
          }
        },
        "type": "object",
        "required": [
          "text"
        ],
        "title": "DetectionRequest"
      },
      "DictLookupRequest": {
        "properties": {
          "word": {
            "type": "string",
            "maxLength": 200,
            "title": "Word",
            "description": "واژه انگلیسی یا فارسی جهت جستجو در دیتابیس واژه‌نامه تخصصی.",
            "examples": [
              "artificial intelligence"
            ]
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source",
            "description": "زبان واژه ورودی (fa یا en یا auto).",
            "default": "auto",
            "examples": [
              "en"
            ]
          }
        },
        "type": "object",
        "required": [
          "word"
        ],
        "title": "DictLookupRequest"
      },
      "DictSearchRequest": {
        "properties": {
          "query": {
            "type": "string",
            "maxLength": 200,
            "title": "Query",
            "description": "عبارت جستجوی تمام‌متن در میان کلمات، معانی و مثال‌ها.",
            "examples": [
              "translation"
            ]
          },
          "limit": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Limit",
            "description": "حداکثر تعداد نتایج بازگشتی (بین ۱ تا ۱۰۰).",
            "default": 20,
            "examples": [
              20
            ]
          }
        },
        "type": "object",
        "required": [
          "query"
        ],
        "title": "DictSearchRequest"
      },
      "DocumentExtractRequest": {
        "properties": {
          "filename": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Filename",
            "default": "document.txt"
          },
          "content_base64": {
            "type": "string",
            "title": "Content Base64",
            "description": "محتوای باینری فایل به صورت Base64"
          }
        },
        "type": "object",
        "required": [
          "content_base64"
        ],
        "title": "DocumentExtractRequest"
      },
      "DocumentGenerateRequest": {
        "properties": {
          "filename": {
            "type": "string",
            "title": "Filename",
            "description": "نام فایل اصلی سورس"
          },
          "content_base64": {
            "type": "string",
            "title": "Content Base64",
            "description": "محتوای باینری فایل سورس به صورت Base64"
          },
          "translations": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object",
            "title": "Translations",
            "description": "نگاشت متن‌های استخراج شده به ترجمه‌های مقصد"
          },
          "target_lang": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Target Lang",
            "description": "کد زبان مقصد (مانند fa, en, tr, ar)",
            "default": "fa"
          },
          "format": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Format",
            "description": "فرمت فایل خروجی ('native' برای حفظ فرمت اصلی فایل)",
            "default": "native"
          }
        },
        "type": "object",
        "required": [
          "filename",
          "content_base64",
          "translations"
        ],
        "title": "DocumentGenerateRequest"
      },
      "GlossaryTermRequest": {
        "properties": {
          "source_lang": {
            "type": "string",
            "title": "Source Lang",
            "description": "Source language code (e.g. en)"
          },
          "target_lang": {
            "type": "string",
            "title": "Target Lang",
            "description": "Target language code (e.g. fa)"
          },
          "source_term": {
            "type": "string",
            "title": "Source Term",
            "description": "Original domain term"
          },
          "target_term": {
            "type": "string",
            "title": "Target Term",
            "description": "Approved translated domain term"
          },
          "category": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Category",
            "description": "Category: medical, legal, tech, brand",
            "default": "general"
          }
        },
        "type": "object",
        "required": [
          "source_lang",
          "target_lang",
          "source_term",
          "target_term"
        ],
        "title": "GlossaryTermRequest"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "KeyGenRequest": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1,
            "title": "Name",
            "description": "نام دارنده کلید یا توسعه‌دهنده"
          },
          "email": {
            "type": "string",
            "maxLength": 254,
            "title": "Email",
            "description": "ایمیل",
            "default": ""
          },
          "tier": {
            "type": "string",
            "title": "Tier",
            "default": "Developer"
          },
          "project_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 120
              },
              {
                "type": "null"
              }
            ],
            "title": "Project Name",
            "description": "نام پروژه اختصاصی جهت تفکیک سهمیه و ره‌گیری"
          }
        },
        "type": "object",
        "required": [
          "name"
        ],
        "title": "KeyGenRequest"
      },
      "LocalizeJsonRequest": {
        "properties": {
          "json_data": {
            "additionalProperties": true,
            "type": "object",
            "title": "Json Data",
            "description": "Nested JSON object to localize"
          },
          "target": {
            "type": "string",
            "title": "Target",
            "description": "Target language code",
            "default": "fa"
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source",
            "description": "Source language code",
            "default": "auto"
          }
        },
        "type": "object",
        "required": [
          "json_data"
        ],
        "title": "LocalizeJsonRequest"
      },
      "OCRRequest": {
        "properties": {
          "image": {
            "type": "string",
            "title": "Image",
            "description": "رشته تصویر با کدگذاری Base64 یا Data URL (مانند data:image/png;base64,...)",
            "examples": [
              "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
            ]
          },
          "lang": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Lang",
            "description": "کد زبان مورد نظر برای استخراج نویسه‌ها (fa, en, ar, tr, ru و... یا auto)",
            "default": "auto",
            "examples": [
              "fa"
            ]
          },
          "allow_online": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Allow Online",
            "description": "مجوز استفاده از موتور عصبی آنلاین در صورت نبود بسته آفلاین زبان",
            "default": true,
            "examples": [
              true
            ]
          }
        },
        "type": "object",
        "required": [
          "image"
        ],
        "title": "OCRRequest"
      },
      "PaymentVerifyRequest": {
        "properties": {
          "payment_id": {
            "type": "string",
            "title": "Payment Id",
            "description": "Payment Order ID"
          },
          "reference_id": {
            "type": "string",
            "title": "Reference Id",
            "description": "Bank/Gateway tracking reference ID"
          },
          "gateway": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Gateway",
            "description": "Gateway name"
          },
          "claim_secret": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 32
              },
              {
                "type": "null"
              }
            ],
            "title": "Claim Secret",
            "description": "Payment claim returned by checkout"
          }
        },
        "type": "object",
        "required": [
          "payment_id",
          "reference_id"
        ],
        "title": "PaymentVerifyRequest"
      },
      "ProxyTestRequest": {
        "properties": {
          "proxy_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Type",
            "description": "Proxy type: socks5 or http",
            "default": "socks5"
          },
          "proxy_host": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Host",
            "description": "Proxy host",
            "default": "127.0.0.1"
          },
          "proxy_port": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Port",
            "description": "Proxy port",
            "default": 9050
          },
          "proxy_user": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy User",
            "description": "Proxy username",
            "default": ""
          },
          "proxy_pass": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Pass",
            "description": "Proxy password",
            "default": ""
          },
          "use_server_tor": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Use Server Tor",
            "description": "Test internal server Tor proxy",
            "default": false
          }
        },
        "type": "object",
        "title": "ProxyTestRequest"
      },
      "StreamTranslationRequest": {
        "properties": {
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Text to translate in real-time streaming chunks"
          },
          "target": {
            "type": "string",
            "title": "Target",
            "description": "Target language code",
            "default": "fa"
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source",
            "description": "Source language code",
            "default": "auto"
          }
        },
        "type": "object",
        "required": [
          "text"
        ],
        "title": "StreamTranslationRequest"
      },
      "TranslationRequest": {
        "properties": {
          "q": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "title": "Q",
            "description": "متن ساده، کد HTML یا آرایه‌ای از متون جهت ترجمه دسته‌ای (حداکثر ۲۰,۰۰۰ نویسه در هر درخواست).",
            "examples": [
              "هوش مصنوعی در حال تغییر دادن صنعت ترجمه و ارتباطات بین‌المللی است."
            ]
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source",
            "description": "کد دوحرفی زبان مبدا بر اساس استاندارد ISO (مانند 'en', 'fa', 'ar', 'tr') یا 'auto' برای تشخیص خودکار.",
            "default": "auto",
            "examples": [
              "auto"
            ]
          },
          "target": {
            "type": "string",
            "title": "Target",
            "description": "کد دوحرفی زبان مقصد (مانند 'fa', 'en', 'tr', 'ar', 'de', 'fr').",
            "default": "fa",
            "examples": [
              "en"
            ]
          },
          "format": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Format",
            "description": "فرمت ورودی: 'text' برای متون ساده یا 'html' برای حفظ کامل تگ‌ها و ساختار صفحات وب.",
            "default": "text",
            "examples": [
              "text"
            ]
          },
          "tone": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tone",
            "description": "لحن یا حوزه تخصصی ترجمه: 'general' (عمومی)، 'formal' (رسمی و اداری)، 'academic' (دانشگاهی و علمی)، 'casual' (عامیانه و گفتاری)، 'technical' (فنی و مهندسی نرم‌افزار)، 'medical' (پزشکی و سلامت).",
            "default": "general",
            "examples": [
              "academic"
            ]
          }
        },
        "type": "object",
        "required": [
          "q"
        ],
        "title": "TranslationRequest"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "WebhookSubscribeRequest": {
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 4096,
            "title": "Url"
          },
          "events": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "maxItems": 2,
            "title": "Events"
          },
          "secret": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 256,
                "minLength": 32
              },
              {
                "type": "null"
              }
            ],
            "title": "Secret"
          }
        },
        "type": "object",
        "required": [
          "url"
        ],
        "title": "WebhookSubscribeRequest"
      },
      "WebhookTestRequest": {
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 4096,
            "title": "Url"
          },
          "event": {
            "type": "string",
            "title": "Event",
            "default": "translation.completed"
          }
        },
        "type": "object",
        "required": [
          "url"
        ],
        "title": "WebhookTestRequest"
      },
      "WebpageProxyRequest": {
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 4096,
            "title": "Url",
            "description": "URL of public webpage to fetch."
          },
          "use_tor": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Use Tor",
            "description": "Route through server Tor / SOCKS5 proxy",
            "default": false
          },
          "proxy_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Type",
            "description": "Proxy type: socks5 or http",
            "default": "socks5"
          },
          "proxy_host": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Host",
            "description": "Proxy host (Admin only)"
          },
          "proxy_port": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Port",
            "description": "Proxy port (Admin only)"
          },
          "proxy_user": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy User",
            "description": "Proxy username"
          },
          "proxy_pass": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Proxy Pass",
            "description": "Proxy password"
          }
        },
        "type": "object",
        "required": [
          "url"
        ],
        "title": "WebpageProxyRequest"
      }
    },
    "securitySchemes": {
      "APIKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Document Translation",
      "description": "استخراج و ترجمه اسناد اداری، اکسل، جداول، زیرنویس فیلم و مارک‌داون با حفظ کامل ساختار و خروجی با همان فرمت اصلی."
    },
    {
      "name": "General",
      "description": "بررسی سلامت سرویس، نسخه API و وضعیت اتصال به سرور (Health Check & Service Discovery)."
    },
    {
      "name": "Languages",
      "description": "فهرست ۲۴ زبان پشتیبانی‌شده به همراه کدهای استاندارد ISO و FLORES، نام‌های بومی و جهت نگارش (RTL/LTR)."
    },
    {
      "name": "Language Detection",
      "description": "تشخیص خودکار و هوشمند زبان متن از میان ۲۴ زبان با الگوریتم‌های ابتکاری و بیزی بدون وابستگی خارجی."
    },
    {
      "name": "Translation",
      "description": "موتور اصلی ترجمه متون، ترجمه دسته‌ای (Batch)، انتخاب لحن (رسمی، آکادمیک، صمیمی، پزشکی، IT) و استریم بلادرنگ (SSE)."
    },
    {
      "name": "HTML Localization",
      "description": "ترجمه عمیق کدهای HTML، اسناد وب و قالب‌ها با حفظ ۱۰۰٪ ساختار تگ‌ها، ویژگی‌ها (Attributes) و اتریبیوت‌های ترجمه‌ناپذیر."
    },
    {
      "name": "Dictionary",
      "description": "واژه‌نامه تخصصی چندزبانه، جستجوی ریشه‌ای کلمات، فونتیک، دسته‌بندی گرامری و جستجوی تمام‌متن (Full-Text Search)."
    },
    {
      "name": "OCR (Image Text Extraction)",
      "description": "استخراج متن از تصاویر و عکس‌های آپلودشده یا کلیپ‌بورد با موتور Tesseract و کتابخانه‌های بهینه‌سازی پردازش تصویر."
    },
    {
      "name": "TTS (Text-to-Speech)",
      "description": "سنتز گفتار و تبدیل متن به صدای طبیعی با تفکیک جنسیت گوینده (زن/مرد/طبیعی)، تنظیم سرعت (Speed) و زیروبم (Pitch)."
    },
    {
      "name": "Billing & Subscriptions",
      "description": "مدیریت پلن‌های اشتراک (Starter, Pro, Enterprise)، بسته‌های اعتباری نویسه و پرداخت امن آنلاین از طریق درگاه فعال **spinora.ir**."
    },
    {
      "name": "Glossary & Translation Memory",
      "description": "حافظه ترجمه و واژه‌نامه اختصاصی سازمانی جهت جایگزینی عبارات و اصطلاحات خاص تجاری، حقوقی، پزشکی و مهندسی."
    },
    {
      "name": "Keys & Authentication",
      "description": "صدور، اعتبارسنجی و بررسی سهمیه باقیمانده کلیدهای API (`dika_dev_...` و `dika_ent_...`)."
    },
    {
      "name": "Admin & Gateway Settings",
      "description": "مدیریت ارشد سیستم، پیکربندی درگاه‌های پرداخت (اسپینورا، زرین‌پال، زیبال، آی‌دی‌پی)، تعیین واحد پولی و گزارش‌های مالی."
    }
  ]
}