{
  "openapi": "3.0.3",
  "info": {
    "title": "Avasaz Developer API",
    "version": "1.1.0",
    "description": "API آوا ساز برای متن، گفتار، پادکست، موزیک و داستان کودک با صوت و تصویر. اتصال سرور به سرور، ۶۰ درخواست در دقیقه برای هر کلید و حداکثر ۳ کار فعال برای حساب. رزرو سقف سایت و تخفیف سودمحور در تسویه. استریم و وب‌هوک در این نسخه پشتیبانی نمی‌شوند."
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/tts": {
      "post": {
        "operationId": "createTts",
        "summary": "تبدیل متن به صوت",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TtsInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: tts:write. Async generation, charged to the API wallet."
      }
    },
    "/podcasts": {
      "post": {
        "operationId": "createPodcast",
        "summary": "تولید پادکست",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PodcastInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: podcasts:write. Async generation, charged to the API wallet."
      }
    },
    "/estimates": {
      "post": {
        "operationId": "estimateCost",
        "summary": "برآورد بدون مصرف اعتبار",
        "tags": [
          "Billing"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "موفق",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string"
                    },
                    "characters": {
                      "type": "integer"
                    },
                    "reserved_credits": {
                      "type": "number",
                      "minimum": 0,
                      "description": "اعتبار موردنیاز برای رزرو در تعرفهٔ فعلی؛ برآورد به‌تنهایی قیمت آینده یا موجودی را تضمین نمی‌کند."
                    },
                    "pricing": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer"
                        },
                        "surplusShare": {
                          "type": "number"
                        },
                        "operatingPercent": {
                          "type": "number"
                        },
                        "failureReservePercent": {
                          "type": "number"
                        },
                        "fixedCredits": {
                          "type": "number"
                        },
                        "precision": {
                          "type": "integer"
                        },
                        "discount_applied_at": {
                          "type": "string",
                          "enum": [
                            "settlement"
                          ]
                        },
                        "reservation": {
                          "type": "string",
                          "enum": [
                            "site_ceiling"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "برآورد مصرف اعتبار با تعرفهٔ زمان درخواست؛ بدون تولید، برداشت یا رزرو اعتبار. هنگام ثبت تولید هزینه دوباره محاسبه می‌شود. همان گوینده‌ها، بخش‌ها و personal_voice تولید را ارسال کنید."
      }
    },
    "/voices": {
      "get": {
        "operationId": "listVoices",
        "summary": "فهرست صداهای قابل استفاده",
        "tags": [
          "Voices"
        ],
        "responses": {
          "200": {
            "description": "موفق",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "voices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "tier": {
                            "type": "string",
                            "enum": [
                              "standard",
                              "personal"
                            ],
                            "description": "ردهٔ صدا"
                          },
                          "gender": {
                            "type": "string",
                            "nullable": true
                          },
                          "origin": {
                            "type": "string",
                            "enum": [
                              "account",
                              "api"
                            ],
                            "description": "فقط برای صدای personal: منبع ثبت صدا"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "فهرست صداهای عمومی و صداهای آمادهٔ قبلی حساب. فایل‌های کاربران سایت شما در این فهرست ثبت نمی‌شوند؛ personal_voice را با لینک نمونه و رضایت در /tts یا /podcasts بفرستید."
      },
      "post": {
        "summary": "مسیر قدیمی ثبت صدا؛ از personal_voice استفاده کنید",
        "deprecated": true,
        "description": "ثبت فایل جدید در آوا ساز متوقف شده است. فایل‌ها روی فضای خود سایت باقی می‌مانند و دو لینک مستقیم در personal_voice درخواست تولید ارسال می‌شوند.",
        "responses": {
          "410": {
            "description": "DIRECT_VOICE_REQUIRED؛ لینک‌ها را همراه تولید بفرستید",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "retiredCreateVoice"
      }
    },
    "/jobs/{id}": {
      "get": {
        "operationId": "getJob",
        "summary": "وضعیت کار همان کلید",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "موفق",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}/audio": {
      "get": {
        "operationId": "downloadAudio",
        "summary": "دانلود فایل صوتی با کلید ایجادکننده",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "فایل صوتی",
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/flac": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/ogg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "jobs:read و همان کلید ایجادکننده لازم است. فقط در completed؛ پیش از آماده‌شدن 409 و پس از حذف فایل 410. قالب را از Content-Type و نام پیشنهادی را از Content-Disposition بخوانید؛ WAV تضمین نمی‌شود."
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "مصرف و رزرو کلید جاری",
        "tags": [
          "Billing"
        ],
        "responses": {
          "200": {
            "description": "موفق",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requests": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string",
                          "pattern": "^[0-9]+$"
                        }
                      ]
                    },
                    "used_credits": {
                      "oneOf": [
                        {
                          "type": "number",
                          "minimum": 0
                        },
                        {
                          "type": "string",
                          "pattern": "^[0-9]+(?:\\.[0-9]+)?$"
                        }
                      ],
                      "description": "مصرف تسویه‌شده به‌اضافهٔ رزرو کارهای ناتمام همین کلید؛ با دقت حداکثر شش رقم اعشار."
                    },
                    "credit_limit": {
                      "type": "integer",
                      "nullable": true
                    },
                    "remaining_credits": {
                      "type": "number",
                      "nullable": true
                    },
                    "wallet_balance": {
                      "type": "number",
                      "minimum": 0,
                      "description": "موجودی قابل‌مصرف حساب؛ پس از مهاجرت کیف پول مرکزی بین API و استودیو مشترک است. مستقل از سقف کلید است."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/dialogues": {
      "post": {
        "operationId": "createDialogue",
        "summary": "گفتگوی دو نفره",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DialogueInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: dialogues:write. Async generation, charged to the API wallet."
      }
    },
    "/source-podcasts": {
      "post": {
        "operationId": "createSourcePodcast",
        "summary": "پادکست از متن منبع",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SourcePodcastInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: sources:write. Async generation, charged to the API wallet."
      }
    },
    "/advertisements": {
      "post": {
        "operationId": "createAdvertisement",
        "summary": "صوت تبلیغاتی",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdvertisementInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: advertisements:write. Async generation, charged to the API wallet."
      }
    },
    "/articles": {
      "post": {
        "operationId": "createArticle",
        "summary": "مقاله",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ArticleInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: articles:write. Async generation, charged to the API wallet."
      }
    },
    "/compositions": {
      "post": {
        "operationId": "createComposition",
        "summary": "ساخت صوت چندبخشی",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompositionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: compositions:write. Async generation, charged to the API wallet."
      }
    },
    "/tones": {
      "get": {
        "operationId": "listtones",
        "summary": "فهرست لحن‌ها",
        "responses": {
          "200": {
            "description": "Catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tones": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/services": {
      "get": {
        "operationId": "listservices",
        "summary": "فهرست سرویس‌های تولید",
        "responses": {
          "200": {
            "description": "Catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string"
                          },
                          "scope": {
                            "type": "string"
                          },
                          "output": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}/output": {
      "get": {
        "operationId": "getJobOutput",
        "summary": "متن خروجی تولید",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "متن تکمیل‌شده یا متن آمادهٔ بازبینی",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "service": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    },
                    "source_citations": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "review_issues": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "continuation": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "parent_job_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "parent_title": {
                          "type": "string"
                        },
                        "mode": {
                          "type": "string"
                        }
                      }
                    },
                    "music_versions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "label": {
                            "type": "string"
                          },
                          "audio": {
                            "type": "string"
                          },
                          "mime": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "story": {
                      "type": "object",
                      "description": "فقط داستان کودک",
                      "properties": {
                        "state": {
                          "type": "string"
                        },
                        "script": {
                          "type": "object",
                          "nullable": true
                        },
                        "input": {
                          "type": "object"
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "matches": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "needed_credits": {
                          "type": "number"
                        },
                        "image_url": {
                          "type": "string",
                          "nullable": true
                        },
                        "frames": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "index": {
                                "type": "integer"
                              },
                              "start": {
                                "type": "number"
                              },
                              "end": {
                                "type": "number"
                              },
                              "status": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string",
                                "nullable": true
                              },
                              "error": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          },
                          "description": "برای قصه‌های فعلی با یک جلد، آرایه خالی است؛ فریم‌های قدیمی فقط برای سازگاری باقی‌اند."
                        },
                        "timeline": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "adaptation": {
                          "type": "string"
                        },
                        "image_message": {
                          "type": "string",
                          "nullable": true
                        },
                        "image_scenes": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "recovery": {
                          "type": "object",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sources": {
      "post": {
        "operationId": "importWebSource",
        "summary": "خواندن منبع صفحهٔ وب",
        "tags": [
          "Generation"
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Source ready, id can be used as source_id in source-podcasts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "characters": {
                      "type": "integer"
                    },
                    "expires_in_hours": {
                      "type": "integer"
                    },
                    "limitation": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Scope sources:write. Fetches a public web page with SSRF protection; no generation credits consumed."
      }
    },
    "/jobs/{id}/continue": {
      "post": {
        "operationId": "continuePodcast",
        "summary": "ساخت قسمت تازه برای ادامهٔ یادگیری یا پاسخ به سؤال",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PodcastContinueInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "برای پادکست یا پادکست منبع تکمیل‌شدهٔ همین کلید، یک قسمت مستقل با رزرو تازه می‌سازد. podcasts:write و jobs:read و Idempotency-Key لازم‌اند. برای برآورد از service=podcast و parent_job_id استفاده کنید."
      }
    },
    "/jobs/{id}/review/approve": {
      "post": {
        "operationId": "approveJobReview",
        "summary": "تأیید متن و ادامهٔ ساخت صوت",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 200000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "jobs:read and the generation scope required. Read /output at awaiting_review; submit reviewed text. Approval uses the original reservation and does not reserve again."
      }
    },
    "/jobs/{id}/embed": {
      "get": {
        "operationId": "getArticleEmbed",
        "summary": "پخش‌کنندهٔ عمومی مقاله",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "وضعیت انتشار و پیوند پلیر صوتی؛ code در صورت وجود رکورد انتشار برمی‌گردد.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "nullable": true
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "فقط برای خروجی source_podcast، از جمله خوانش مقاله با source_mode=reading؛ /articles متن تولید می‌کند و قابل انتشار با این پلیر نیست. GET به jobs:read و PUT علاوه بر آن به sources:write نیاز دارد. فعال‌سازی فقط پس از completed و وجود صوت مجاز است. انتشار هزینهٔ اضافه ندارد؛ ساخت صوت هزینه دارد. enabled=false انتشار را متوقف و rotate=true همراه enabled=true پیوند قبلی را باطل می‌کند."
      },
      "put": {
        "operationId": "updateArticleEmbed",
        "summary": "پخش‌کنندهٔ عمومی مقاله",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "وضعیت انتشار و پیوند پلیر صوتی؛ code در صورت وجود رکورد انتشار برمی‌گردد.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "nullable": true
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "فقط برای خروجی source_podcast، از جمله خوانش مقاله با source_mode=reading؛ /articles متن تولید می‌کند و قابل انتشار با این پلیر نیست. GET به jobs:read و PUT علاوه بر آن به sources:write نیاز دارد. فعال‌سازی فقط پس از completed و وجود صوت مجاز است. انتشار هزینهٔ اضافه ندارد؛ ساخت صوت هزینه دارد. enabled=false انتشار را متوقف و rotate=true همراه enabled=true پیوند قبلی را باطل می‌کند.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "rotate": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/voices/{id}": {
      "delete": {
        "tags": [
          "Catalog"
        ],
        "summary": "حذف ضبط‌های صدای API",
        "operationId": "deletePersonalVoice",
        "description": "فقط پاک‌سازی ضبط‌های قدیمی ذخیره‌شده با همان کلید و voices:write؛ روش جدید personal_voice هیچ فایل ورودی در آوا ساز ذخیره نمی‌کند. حذف فایل ورودی و لغو لینک‌ها بر عهدهٔ سایت مصرف‌کننده است.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^personal-[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ضبط حذف شد",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "فایل یا بدنه بزرگ‌تر از سقف مجاز",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "قالب فایل پشتیبانی نمی‌شود یا ضبط قابل خواندن نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "deprecated": true
      }
    },
    "/voices/recording-guide": {
      "get": {
        "operationId": "getPersonalVoiceRecordingGuide",
        "summary": "متن و تنظیمات ضبط فعلی آوا ساز",
        "tags": [
          "Voices"
        ],
        "responses": {
          "200": {
            "description": "راهنمای فعلی ضبط",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonalVoiceRecordingGuide"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "متن نمونهٔ فارسی، گزینه‌های رضایت فعلی آوا ساز و مشخصات WAV؛ همان تنظیمات ضبط محصول. شرط هم‌زبانی در API اعمال نمی‌شود. اعتبار تولید مصرف نمی‌کند."
      }
    },
    "/music": {
      "post": {
        "operationId": "createMusic",
        "summary": "ساخت موزیک",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MusicInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required scope: music:write. Uses the studio music pipeline with API-wallet settlement. One active music job per account."
      }
    },
    "/jobs/{id}/music-versions/{version}/audio": {
      "get": {
        "operationId": "getMusicVersionAudio",
        "summary": "دریافت نسخه موزیک",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "فایل صوتی",
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/flac": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/ogg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/children-stories": {
      "post": {
        "operationId": "createChildrenStory",
        "summary": "ساخت داستان کودک با صوت و تصویر",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChildrenStoryInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "درخواست تکراری؛ بدون رزرو مجدد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "کار ثبت شد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "stories:write لازم است. همان Idempotency-Key و همان ورودی را برای تلاش مجدد حفظ کنید. برآورد رایگان است و سقف سایت از کیف پول API رزرو می‌شود. تخفیف سودمحور در تسویه نهایی بازمی‌گردد."
      }
    },
    "/jobs/{id}/story/estimate": {
      "post": {
        "operationId": "storyEstimate",
        "summary": "برآورد ادامه قصه",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoryAction"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "سقف کل و اعتبار اضافه موردنیاز، یا بازپخش ادامه",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reserved_credits": {
                      "type": "number"
                    },
                    "additional_credits": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "jobs:read و stories:write لازم است. فقط کار awaiting_review و تسویه‌نشده؛ بدون رزرو اعتبار، reserved_credits (سقف کل) و additional_credits (افزایش لازم) را می‌دهد."
      }
    },
    "/jobs/{id}/story/continue": {
      "post": {
        "operationId": "storyContinue",
        "summary": "تأیید متن یا ادامه همان قصه",
        "tags": [
          "Generation"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            },
            "description": "شناسه مستقل برای هر تولید؛ در تلاش مجدد همان مقدار و ورودی را ارسال کنید."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/StoryAction"
                  },
                  {
                    "type": "object",
                    "required": [
                      "max_reserved_credits"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "بازپخش همان عملیات بدون رزرو دوباره؛ وضعیت کامل کار و additional_credits=0",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Job"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "additional_credits": {
                          "type": "number",
                          "minimum": 0,
                          "description": "در بازپخش همان عملیات صفر است؛ رزرو دوباره انجام نمی‌شود."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "202": {
            "description": "همان کار دوباره در صف قرار گرفت؛ پاسخ شامل وضعیت کار، سقف کل و اعتبار اضافه است.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Job"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "additional_credits": {
                          "type": "number",
                          "minimum": 0,
                          "description": "در بازپخش همان عملیات صفر است؛ رزرو دوباره انجام نمی‌شود."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "jobs:read و stories:write لازم است. هزینه اضافه فقط با max_reserved_credits صریح و Idempotency-Key رزرو می‌شود. سفارش تسویه‌شده قابل شارژ مجدد نیست."
      }
    },
    "/jobs/{id}/story/image": {
      "get": {
        "operationId": "storyCover",
        "summary": "دریافت جلد قصه",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تصویر آماده",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "jobs:read؛ فایل فقط با کلید سازنده قابل دریافت است."
      }
    },
    "/jobs/{id}/story/frames/{position}": {
      "get": {
        "operationId": "storyFrame",
        "summary": "دریافت تصویر صحنه",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "position",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 19
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تصویر آماده",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "ورودی نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "اعتبار یا سقف کلید ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "پیدا نشد",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "تعارض یا خروجی ناتمام",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "فایل حذف‌شده",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "مسیر سازگاری دریافت تصاویر قصه‌های قدیمی؛ قصه‌های فعلی همیشه یک جلد و frames خالی دارند. همان کلید و jobs:read لازم است."
      }
    },
    "/stories/catalog": {
      "get": {
        "summary": "فهرست قصه‌های منتشرشده با منابع",
        "operationId": "storyCatalog",
        "description": "stories:write لازم است.",
        "responses": {
          "200": {
            "description": "ages و stories شامل id، title، description، age، adaptation و sources"
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stories/reference-images": {
      "post": {
        "summary": "بارگذاری عکس مرجع شخصیت قصه",
        "operationId": "uploadStoryReference",
        "description": "stories:write؛ عکس با همین کلید و فضای کاری قابل استفاده است. JPG/PNG/WebP حداکثر ۲ مگابایت. data فقط base64، بدون پیشوند data URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "data"
                ],
                "properties": {
                  "data": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "maxLength": 2796204
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "شناسه مرجع",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "عکس نامعتبر"
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "summary": "نرخ هر میلیون توکن ورودی و خروجی، گفتار و موزیک",
        "operationId": "getApiPricing",
        "responses": {
          "200": {
            "description": "نرخ‌های جاری از موتور واقعی صورتحساب؛ هر ردیف هزینهٔ مرجع برای مصرف مستقل همان واحد است. سفارش ترکیبی بر اساس مصرف و گردکردن تسویه می‌شود.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiPricing"
                }
              }
            }
          },
          "401": {
            "description": "کلید نامعتبر",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "دسترسی ناکافی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "محدودیت نرخ یا هم‌زمانی",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "ثانیه تا تلاش مجدد"
              }
            }
          },
          "503": {
            "description": "سرویس در دسترس نیست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pd_live_..."
      }
    },
    "schemas": {
      "TtsInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 12000
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "شناسهٔ صدا از GET /voices؛ در نبود personal_voice و voice پیش‌فرض Kore است. همراه personal_voice نفرستید."
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "pace": {
            "type": "string",
            "enum": [
              "slow",
              "normal",
              "fast"
            ],
            "default": "normal"
          },
          "personal_voice": {
            "$ref": "#/components/schemas/PersonalVoiceReference"
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        },
        "not": {
          "required": [
            "voice",
            "personal_voice"
          ]
        }
      },
      "PodcastInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "text": {
            "type": "string",
            "minLength": 0,
            "maxLength": 20000,
            "description": "موضوع تازه: ۳ تا ۲۰٬۰۰۰ نویسه. همراه parent_job_id: درخواست ادامه تا ۳۰۰۰ نویسه؛ در حالت continue می‌تواند خالی یا حذف شود، question و explain حداقل ۳ نویسه می‌خواهند."
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "شناسهٔ صدا از GET /voices؛ در تولید تازه پیش‌فرض Kore است. همراه personal_voice نفرستید. در ادامه، گوینده از والد می‌آید؛ برای تغییر از speakers استفاده کنید."
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "instructions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000
          },
          "duration": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "default": 4
          },
          "speakers": {
            "type": "array",
            "minItems": 1,
            "maxItems": 3,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "name"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 60
                },
                "voice": {
                  "type": "string"
                },
                "personal_voice": {
                  "$ref": "#/components/schemas/PersonalVoiceReference"
                }
              },
              "oneOf": [
                {
                  "required": [
                    "voice"
                  ]
                },
                {
                  "required": [
                    "personal_voice"
                  ]
                }
              ]
            },
            "description": "یک تا سه گوینده؛ هر عضو name و دقیقاً یکی از voice عمومی یا personal_voice با دو لینک فایل خودش را دارد. personal_voice سطح اصلی را هم‌زمان نفرستید."
          },
          "parent_job_id": {
            "type": "string",
            "format": "uuid",
            "description": "قسمت تکمیل‌شدهٔ همین کلید؛ متن قبلی ذخیره و قسمت مستقلی ساخته می‌شود. تنظیمات ارسال‌نشده از والد می‌آیند."
          },
          "continuation_mode": {
            "type": "string",
            "enum": [
              "continue",
              "question",
              "explain"
            ],
            "description": "فقط همراه parent_job_id؛ سؤال یا بخش موردنظر در text (حداکثر ۳۰۰۰ نویسه)."
          },
          "auto_continue": {
            "type": "boolean",
            "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
          },
          "personal_voice": {
            "$ref": "#/components/schemas/PersonalVoiceReference"
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        },
        "not": {
          "anyOf": [
            {
              "required": [
                "voice",
                "personal_voice"
              ]
            },
            {
              "required": [
                "speakers",
                "personal_voice"
              ]
            }
          ]
        },
        "description": "برای پادکست تازه text لازم است؛ برای ادامه، parent_job_id از همین کلید را بفرستید و text اختیاری است. ادامه به podcasts:write و jobs:read نیاز دارد؛ تنظیمات ارسال‌نشده از والد می‌آیند.",
        "oneOf": [
          {
            "required": [
              "text"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "parent_job_id"
                  ]
                },
                {
                  "required": [
                    "continuation_mode"
                  ]
                }
              ]
            },
            "properties": {
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 20000
              }
            }
          },
          {
            "required": [
              "parent_job_id"
            ],
            "properties": {
              "text": {
                "type": "string",
                "minLength": 0,
                "maxLength": 3000
              }
            },
            "oneOf": [
              {
                "properties": {
                  "continuation_mode": {
                    "type": "string",
                    "enum": [
                      "continue"
                    ]
                  }
                }
              },
              {
                "required": [
                  "continuation_mode",
                  "text"
                ],
                "properties": {
                  "continuation_mode": {
                    "type": "string",
                    "enum": [
                      "question",
                      "explain"
                    ]
                  },
                  "text": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3000
                  }
                }
              }
            ]
          }
        ]
      },
      "EstimateInput": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "text"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "tts"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 12000
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "شناسهٔ صدا از GET /voices؛ در نبود personal_voice و voice پیش‌فرض Kore است. همراه personal_voice نفرستید."
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "pace": {
                "type": "string",
                "enum": [
                  "slow",
                  "normal",
                  "fast"
                ],
                "default": "normal"
              },
              "personal_voice": {
                "$ref": "#/components/schemas/PersonalVoiceReference"
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            },
            "not": {
              "required": [
                "voice",
                "personal_voice"
              ]
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "podcast"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 0,
                "maxLength": 20000,
                "description": "موضوع تازه: ۳ تا ۲۰٬۰۰۰ نویسه. همراه parent_job_id: درخواست ادامه تا ۳۰۰۰ نویسه؛ در حالت continue می‌تواند خالی یا حذف شود، question و explain حداقل ۳ نویسه می‌خواهند."
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "شناسهٔ صدا از GET /voices؛ در تولید تازه پیش‌فرض Kore است. همراه personal_voice نفرستید. در ادامه، گوینده از والد می‌آید؛ برای تغییر از speakers استفاده کنید."
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "instructions": {
                "type": "string",
                "minLength": 0,
                "maxLength": 3000
              },
              "duration": {
                "type": "integer",
                "minimum": 1,
                "maximum": 15,
                "default": 4
              },
              "speakers": {
                "type": "array",
                "minItems": 1,
                "maxItems": 3,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "name"
                  ],
                  "properties": {
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 60
                    },
                    "voice": {
                      "type": "string"
                    },
                    "personal_voice": {
                      "$ref": "#/components/schemas/PersonalVoiceReference"
                    }
                  },
                  "oneOf": [
                    {
                      "required": [
                        "voice"
                      ]
                    },
                    {
                      "required": [
                        "personal_voice"
                      ]
                    }
                  ]
                },
                "description": "یک تا سه گوینده؛ هر عضو name و دقیقاً یکی از voice عمومی یا personal_voice با دو لینک فایل خودش را دارد. personal_voice سطح اصلی را هم‌زمان نفرستید."
              },
              "parent_job_id": {
                "type": "string",
                "format": "uuid",
                "description": "قسمت تکمیل‌شدهٔ همین کلید؛ متن قبلی ذخیره و قسمت مستقلی ساخته می‌شود. تنظیمات ارسال‌نشده از والد می‌آیند."
              },
              "continuation_mode": {
                "type": "string",
                "enum": [
                  "continue",
                  "question",
                  "explain"
                ],
                "description": "فقط همراه parent_job_id؛ سؤال یا بخش موردنظر در text (حداکثر ۳۰۰۰ نویسه)."
              },
              "auto_continue": {
                "type": "boolean",
                "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
              },
              "personal_voice": {
                "$ref": "#/components/schemas/PersonalVoiceReference"
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            },
            "not": {
              "anyOf": [
                {
                  "required": [
                    "voice",
                    "personal_voice"
                  ]
                },
                {
                  "required": [
                    "speakers",
                    "personal_voice"
                  ]
                }
              ]
            },
            "description": "برای پادکست تازه text لازم است؛ برای ادامه، parent_job_id از همین کلید را بفرستید و text اختیاری است. ادامه به podcasts:write و jobs:read نیاز دارد؛ تنظیمات ارسال‌نشده از والد می‌آیند.",
            "oneOf": [
              {
                "required": [
                  "text"
                ],
                "not": {
                  "anyOf": [
                    {
                      "required": [
                        "parent_job_id"
                      ]
                    },
                    {
                      "required": [
                        "continuation_mode"
                      ]
                    }
                  ]
                },
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 20000
                  }
                }
              },
              {
                "required": [
                  "parent_job_id"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 0,
                    "maxLength": 3000
                  }
                },
                "oneOf": [
                  {
                    "properties": {
                      "continuation_mode": {
                        "type": "string",
                        "enum": [
                          "continue"
                        ]
                      }
                    }
                  },
                  {
                    "required": [
                      "continuation_mode",
                      "text"
                    ],
                    "properties": {
                      "continuation_mode": {
                        "type": "string",
                        "enum": [
                          "question",
                          "explain"
                        ]
                      },
                      "text": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 3000
                      }
                    }
                  }
                ]
              }
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service",
              "text"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "dialogue"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 20000
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "Voice ID from GET /voices",
                "default": "Kore"
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "instructions": {
                "type": "string",
                "minLength": 0,
                "maxLength": 3000
              },
              "duration": {
                "type": "integer",
                "minimum": 1,
                "maximum": 15,
                "default": 4
              },
              "voice_two": {
                "type": "string",
                "description": "A different voice from voice; defaults to another available voice."
              },
              "speaker_one": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40
              },
              "speaker_two": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40
              },
              "mode": {
                "type": "string",
                "enum": [
                  "conversation",
                  "debate"
                ],
                "default": "conversation"
              },
              "auto_continue": {
                "type": "boolean",
                "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "source_podcast"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 20000
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "Voice ID from GET /voices",
                "default": "Kore"
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "instructions": {
                "type": "string",
                "minLength": 0,
                "maxLength": 3000
              },
              "duration": {
                "type": "integer",
                "minimum": 1,
                "maximum": 15,
                "default": 4
              },
              "source_text": {
                "type": "string",
                "minLength": 30,
                "maxLength": 100000
              },
              "source_name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "source_mode": {
                "type": "string",
                "enum": [
                  "full",
                  "focus",
                  "reading"
                ],
                "default": "full",
                "description": "reading برای خوانش وفادار متن مقاله تا ۱۲۰۰۰ نویسه، بدون بازنویسی. full و focus برای تولید پادکست از منبع."
              },
              "source_id": {
                "type": "string",
                "format": "uuid",
                "description": "ID from POST /sources using the same API key. Exactly one of source_id/source_text."
              },
              "auto_continue": {
                "type": "boolean",
                "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            },
            "oneOf": [
              {
                "required": [
                  "source_text"
                ]
              },
              {
                "required": [
                  "source_id"
                ]
              }
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service",
              "text"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "advertisement"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 20000
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "Voice ID from GET /voices",
                "default": "Kore"
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "instructions": {
                "type": "string",
                "minLength": 0,
                "maxLength": 3000
              },
              "duration_seconds": {
                "type": "integer",
                "minimum": 10,
                "maximum": 90,
                "default": 30
              },
              "brand_name": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "audience": {
                "type": "string",
                "minLength": 0,
                "maxLength": 300
              },
              "key_benefits": {
                "type": "string",
                "minLength": 0,
                "maxLength": 800
              },
              "offer": {
                "type": "string",
                "minLength": 0,
                "maxLength": 300
              },
              "call_to_action": {
                "type": "string",
                "minLength": 0,
                "maxLength": 240
              },
              "restrictions": {
                "type": "string",
                "minLength": 0,
                "maxLength": 600
              },
              "goal": {
                "type": "string",
                "enum": [
                  "sales",
                  "awareness",
                  "launch",
                  "lead",
                  "app",
                  "event"
                ]
              },
              "platform": {
                "type": "string",
                "enum": [
                  "instagram",
                  "radio",
                  "podcast",
                  "video",
                  "website",
                  "phone"
                ]
              },
              "auto_continue": {
                "type": "boolean",
                "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service",
              "text"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "article"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 20000
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "Voice ID from GET /voices",
                "default": "Kore"
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "instructions": {
                "type": "string",
                "minLength": 0,
                "maxLength": 3000
              },
              "keywords": {
                "type": "string",
                "minLength": 0,
                "maxLength": 500
              },
              "auto_continue": {
                "type": "boolean",
                "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service",
              "segments"
            ],
            "properties": {
              "service": {
                "type": "string",
                "enum": [
                  "composition"
                ]
              },
              "title": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120
              },
              "voice": {
                "type": "string",
                "description": "Voice ID from GET /voices",
                "default": "Kore"
              },
              "tone": {
                "type": "string",
                "enum": [
                  "conversational",
                  "expert",
                  "analytical",
                  "dialogue",
                  "energetic",
                  "friendly",
                  "formal",
                  "luxury",
                  "trustworthy",
                  "playful"
                ]
              },
              "segments": {
                "type": "array",
                "minItems": 1,
                "maxItems": 20,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "text"
                  ],
                  "properties": {
                    "text": {
                      "type": "string",
                      "minLength": 3,
                      "maxLength": 12000
                    },
                    "voice": {
                      "type": "string",
                      "description": "Voice ID from GET /voices",
                      "default": "Kore"
                    },
                    "tone": {
                      "type": "string",
                      "enum": [
                        "conversational",
                        "expert",
                        "analytical",
                        "dialogue",
                        "energetic",
                        "friendly",
                        "formal",
                        "luxury",
                        "trustworthy",
                        "playful"
                      ]
                    },
                    "pace": {
                      "type": "string",
                      "enum": [
                        "slow",
                        "normal",
                        "fast"
                      ],
                      "default": "normal"
                    }
                  }
                }
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "service",
              "title",
              "prompt"
            ],
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "prompt": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2200
              },
              "mode": {
                "type": "string",
                "enum": [
                  "instrumental",
                  "vocal"
                ],
                "default": "instrumental",
                "description": "instrumental موزیک بی‌کلام؛ vocal موزیک با آواز"
              },
              "lyrics": {
                "type": "string",
                "maxLength": 1600,
                "description": "در حالت سفارشی با آواز لازم است؛ برای بی‌کلام خالی بماند."
              },
              "model": {
                "type": "string",
                "enum": [
                  "podly-music-quick",
                  "podly-music-balanced",
                  "podly-music-creative"
                ]
              },
              "seconds": {
                "type": "integer",
                "minimum": 10,
                "maximum": 360,
                "default": 180,
                "description": "مدت هدف؛ مدت خروجی وابسته به مدل است. تعرفه هر فراخوانی است."
              },
              "creationMode": {
                "type": "string",
                "enum": [
                  "simple",
                  "custom"
                ]
              },
              "negativeTags": {
                "type": "string",
                "maxLength": 500
              },
              "vocalGender": {
                "type": "string",
                "enum": [
                  "m",
                  "f"
                ]
              },
              "styleWeight": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "weirdness": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "variety": {
                "type": "number",
                "minimum": 0,
                "maximum": 4
              },
              "autoDuration": {
                "type": "boolean"
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              },
              "service": {
                "type": "string",
                "enum": [
                  "music"
                ]
              },
              "singingVoiceId": {
                "type": "string",
                "format": "uuid",
                "description": "اختیاری و فقط در mode=vocal: شناسهٔ صدای خوانندهٔ آماده و فعالِ همان حساب در سایت. ثبت و تأیید این صدا API عمومی ندارد و به فعال‌بودن قابلیت در سایت وابسته است. با personal_voice گفتار متفاوت است؛ vocalGender در این حالت نادیده گرفته می‌شود."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "mode": {
                "type": "string",
                "enum": [
                  "auto",
                  "new",
                  "search",
                  "catalog",
                  "own"
                ],
                "default": "new",
                "description": "روش روایت: new ایدهٔ تازه، own متن کامل، search قصهٔ آشنا، catalog از فهرست و auto تشخیص خودکار"
              },
              "age": {
                "type": "string",
                "enum": [
                  "3-5",
                  "6-8",
                  "9-12",
                  "13-15"
                ],
                "default": "6-8"
              },
              "prompt": {
                "type": "string",
                "minLength": 3,
                "maxLength": 24000,
                "description": "new/search: تا ۳۰۰۰ نویسه؛ own: حداقل ۱۰۰؛ catalog بدون prompt"
              },
              "catalogId": {
                "type": "string",
                "pattern": "^[a-z0-9-]{2,80}$"
              },
              "duration": {
                "type": "string",
                "enum": [
                  "short",
                  "medium",
                  "long"
                ],
                "description": "اندازهٔ هدف قصه: short حدود ۳، medium حدود ۶ و long حدود ۱۰ دقیقه"
              },
              "creativity": {
                "type": "string",
                "enum": [
                  "faithful",
                  "expressive",
                  "free"
                ],
                "default": "faithful"
              },
              "children": {
                "type": "array",
                "maxItems": 5,
                "items": {
                  "$ref": "#/components/schemas/StoryChild"
                },
                "description": "حداکثر پنج کودک؛ مشخصات هر عضو در جدول زیر آمده است"
              },
              "referenceId": {
                "type": "string",
                "format": "uuid",
                "description": "شناسه عکس آپلودشده با همین کلید"
              },
              "imageCount": {
                "type": "integer",
                "deprecated": true,
                "default": 1,
                "description": "همیشه یک تصویر جلد ساخته می‌شود؛ این گزینهٔ قدیمی و مقدار آن نادیده گرفته می‌شوند."
              },
              "soundscape": {
                "type": "string",
                "enum": [
                  "auto",
                  "off"
                ],
                "default": "auto"
              },
              "auto_continue": {
                "type": "boolean",
                "default": true,
                "description": "false برای بازبینی ساختار روایت پیش از صوت"
              },
              "max_reserved_credits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
              },
              "service": {
                "type": "string",
                "enum": [
                  "children_story"
                ]
              }
            },
            "description": "ورودی همان موتور قصه سایت؛ برای حالت catalog، catalogId و برای بقیه prompt لازم است. کیف پول Kids استفاده نمی‌شود.",
            "oneOf": [
              {
                "required": [
                  "catalogId",
                  "mode"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "catalog"
                    ]
                  }
                }
              },
              {
                "required": [
                  "prompt"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "new",
                      "search"
                    ]
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3000
                  }
                }
              },
              {
                "required": [
                  "prompt",
                  "mode"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto"
                    ]
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 24000
                  }
                }
              },
              {
                "required": [
                  "prompt",
                  "mode"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "own"
                    ]
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 100,
                    "maxLength": 24000
                  }
                }
              }
            ],
            "required": [
              "service"
            ]
          }
        ],
        "description": "همان ورودی تولید به‌همراه service. پیش‌فرض service در صورت حذف tts است. ادامهٔ پادکست را با service=podcast و parent_job_id برآورد کنید. درخواست برآورد کار نمی‌سازد و اعتبار رزرو نمی‌کند."
      },
      "Job": {
        "type": "object",
        "required": [
          "id",
          "service",
          "status",
          "reserved_credits",
          "charged_credits",
          "audio_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "service": {
            "type": "string",
            "enum": [
              "tts",
              "podcast",
              "dialogue",
              "source_podcast",
              "advertisement",
              "article",
              "composition",
              "music",
              "children_story"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "completed",
              "failed",
              "cancelled",
              "awaiting_review"
            ]
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "reserved_credits": {
            "type": "number",
            "minimum": 0,
            "description": "سقف کل رزرو این کار؛ در ادامهٔ تأییدشدهٔ داستان ممکن است افزایش یابد."
          },
          "charged_credits": {
            "type": "number",
            "nullable": true,
            "description": "هزینهٔ نهایی پس از تسویه و تخفیف؛ پیش از تسویه ممکن است null یا هزینهٔ موقت مراحل انجام‌شده باشد."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "audio_url": {
            "type": "string",
            "nullable": true,
            "description": "مسیر محافظت‌شدهٔ صوت در completed؛ برای مقالهٔ متنی null است. قالب واقعی را از Content-Type بخوانید."
          },
          "error": {
            "type": "object",
            "nullable": true,
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "wallet_type": {
            "type": "string",
            "enum": [
              "api",
              "studio"
            ],
            "description": "مبدأ مالی کار: api برای کارهای API و studio برای سوابق قدیمی. در حساب دارای کیف پول مشترک، این فیلد به معنی موجودی جداگانه نیست."
          },
          "output_url": {
            "type": "string",
            "nullable": true,
            "description": "مسیر محافظت‌شدهٔ متن و اطلاعات خروجی در completed یا awaiting_review؛ نیازمند همان کلید و jobs:read."
          },
          "pricing": {
            "type": "object",
            "properties": {
              "site_credits": {
                "type": "number"
              },
              "discount_credits": {
                "type": "number"
              }
            },
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "DialogueInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 20000
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "Voice ID from GET /voices",
            "default": "Kore"
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "instructions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000
          },
          "duration": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "default": 4
          },
          "voice_two": {
            "type": "string",
            "description": "A different voice from voice; defaults to another available voice."
          },
          "speaker_one": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "speaker_two": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "mode": {
            "type": "string",
            "enum": [
              "conversation",
              "debate"
            ],
            "default": "conversation"
          },
          "auto_continue": {
            "type": "boolean",
            "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        }
      },
      "SourcePodcastInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 20000
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "Voice ID from GET /voices",
            "default": "Kore"
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "instructions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000
          },
          "duration": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "default": 4
          },
          "source_text": {
            "type": "string",
            "minLength": 30,
            "maxLength": 100000
          },
          "source_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "source_mode": {
            "type": "string",
            "enum": [
              "full",
              "focus",
              "reading"
            ],
            "default": "full",
            "description": "reading برای خوانش وفادار متن مقاله تا ۱۲۰۰۰ نویسه، بدون بازنویسی. full و focus برای تولید پادکست از منبع."
          },
          "source_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID from POST /sources using the same API key. Exactly one of source_id/source_text."
          },
          "auto_continue": {
            "type": "boolean",
            "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        },
        "oneOf": [
          {
            "required": [
              "source_text"
            ]
          },
          {
            "required": [
              "source_id"
            ]
          }
        ]
      },
      "AdvertisementInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 20000
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "Voice ID from GET /voices",
            "default": "Kore"
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "instructions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000
          },
          "duration_seconds": {
            "type": "integer",
            "minimum": 10,
            "maximum": 90,
            "default": 30
          },
          "brand_name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "audience": {
            "type": "string",
            "minLength": 0,
            "maxLength": 300
          },
          "key_benefits": {
            "type": "string",
            "minLength": 0,
            "maxLength": 800
          },
          "offer": {
            "type": "string",
            "minLength": 0,
            "maxLength": 300
          },
          "call_to_action": {
            "type": "string",
            "minLength": 0,
            "maxLength": 240
          },
          "restrictions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 600
          },
          "goal": {
            "type": "string",
            "enum": [
              "sales",
              "awareness",
              "launch",
              "lead",
              "app",
              "event"
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "instagram",
              "radio",
              "podcast",
              "video",
              "website",
              "phone"
            ]
          },
          "auto_continue": {
            "type": "boolean",
            "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        }
      },
      "ArticleInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 20000
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "Voice ID from GET /voices",
            "default": "Kore"
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "instructions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000
          },
          "keywords": {
            "type": "string",
            "minLength": 0,
            "maxLength": 500
          },
          "auto_continue": {
            "type": "boolean",
            "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        }
      },
      "CompositionInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "segments"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "Voice ID from GET /voices",
            "default": "Kore"
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "segments": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "text"
              ],
              "properties": {
                "text": {
                  "type": "string",
                  "minLength": 3,
                  "maxLength": 12000
                },
                "voice": {
                  "type": "string",
                  "description": "Voice ID from GET /voices",
                  "default": "Kore"
                },
                "tone": {
                  "type": "string",
                  "enum": [
                    "conversational",
                    "expert",
                    "analytical",
                    "dialogue",
                    "energetic",
                    "friendly",
                    "formal",
                    "luxury",
                    "trustworthy",
                    "playful"
                  ]
                },
                "pace": {
                  "type": "string",
                  "enum": [
                    "slow",
                    "normal",
                    "fast"
                  ],
                  "default": "normal"
                }
              }
            }
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        }
      },
      "PersonalVoiceReference": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source_audio_url",
          "consent_audio_url"
        ],
        "description": "دو فایل WAV در فضای سایت مصرف‌کننده باقی می‌مانند. آوا ساز لینک‌ها را برای تولید به مدل می‌فرستد و فایل‌های ورودی را دانلود یا ذخیره نمی‌کند. شرط هم‌زبانی اعمال نمی‌شود؛ از متن‌های GET /voices/recording-guide استفاده کنید.",
        "properties": {
          "source_audio_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 8192,
            "description": "لینک مستقیم HTTPS نمونهٔ صدای کاربر؛ WAV/24kHz/mono/PCM16، ۱۰ تا ۳۰ ثانیه، حداکثر ۱۰ MiB. بدون نیاز به کوکی یا هدر ورود؛ تا پایان پردازش معتبر بماند."
          },
          "consent_audio_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 8192,
            "description": "لینک مستقیم HTTPS ضبط رضایت همان گوینده؛ WAV، ۳ تا ۳۰ ثانیه، حداکثر ۱۰ MiB. متن‌های فعلی آوا ساز در recording-guide موجودند؛ پیش‌فرض نمونه فارسی و رضایت انگلیسی است."
          }
        }
      },
      "PersonalVoiceRecordingGuide": {
        "type": "object",
        "properties": {
          "source": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "min_seconds": {
                "type": "number"
              },
              "max_seconds": {
                "type": "number"
              }
            },
            "required": [
              "text",
              "language",
              "min_seconds",
              "max_seconds"
            ]
          },
          "consent": {
            "type": "object",
            "properties": {
              "default_language": {
                "type": "string"
              },
              "min_seconds": {
                "type": "number"
              },
              "max_seconds": {
                "type": "number"
              },
              "options": {
                "type": "object",
                "properties": {
                  "en": {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string"
                      },
                      "phonetic": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "text",
                      "phonetic"
                    ]
                  },
                  "fa": {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string"
                      },
                      "phonetic": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "text",
                      "phonetic"
                    ]
                  }
                },
                "required": [
                  "en",
                  "fa"
                ]
              }
            },
            "required": [
              "default_language",
              "min_seconds",
              "max_seconds",
              "options"
            ]
          },
          "audio": {
            "type": "object",
            "properties": {
              "format": {
                "type": "string"
              },
              "sample_rate": {
                "type": "number"
              },
              "channels": {
                "type": "number"
              },
              "bits_per_sample": {
                "type": "number"
              },
              "max_bytes": {
                "type": "number"
              }
            },
            "required": [
              "format",
              "sample_rate",
              "channels",
              "bits_per_sample",
              "max_bytes"
            ]
          },
          "language_matching_required": {
            "type": "boolean"
          },
          "storage": {
            "type": "string"
          }
        },
        "required": [
          "source",
          "consent",
          "audio",
          "language_matching_required",
          "storage"
        ],
        "example": {
          "source": {
            "text": "سلام! این نمونه رو با صدای معمولی خودم ضبط می‌کنم. امروز یه ایدهٔ تازه به ذهنم رسید و دوست دارم درباره‌ش حرف بزنم. شاید ازش یه قصه بسازم، شاید هم یه پیام کوتاه برای یه دوست. مهم اینه که حرفم رو راحت و روشن بگم؛ درست مثل وقتی که دارم با یکی از دوستام صحبت می‌کنم.",
            "language": "fa",
            "min_seconds": 10,
            "max_seconds": 30
          },
          "consent": {
            "default_language": "en",
            "min_seconds": 3,
            "max_seconds": 30,
            "options": {
              "en": {
                "text": "I am the owner of this voice and I consent to Google using this voice to create a synthetic voice model.",
                "phonetic": "آی اَم دی اُونِر آو دیس وُیس اَند آی کِنسِنت تو گوگِل یوزینگ دیس وُیس تو کری‌اِیت اِ سین‌ثِتیک وُیس مادِل."
              },
              "fa": {
                "text": "من مالک این صدا هستم و با ایجاد یک مدل مصنوعی از صدایم از طریق استفاده از گوگل کلاود موافقت کرده‌ام.",
                "phonetic": ""
              }
            }
          },
          "audio": {
            "format": "wav",
            "sample_rate": 24000,
            "channels": 1,
            "bits_per_sample": 16,
            "max_bytes": 10485760
          },
          "language_matching_required": false,
          "storage": "customer"
        }
      },
      "MusicInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "prompt"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2200
          },
          "mode": {
            "type": "string",
            "enum": [
              "instrumental",
              "vocal"
            ],
            "default": "instrumental",
            "description": "instrumental موزیک بی‌کلام؛ vocal موزیک با آواز"
          },
          "lyrics": {
            "type": "string",
            "maxLength": 1600,
            "description": "در حالت سفارشی با آواز لازم است؛ برای بی‌کلام خالی بماند."
          },
          "model": {
            "type": "string",
            "enum": [
              "podly-music-quick",
              "podly-music-balanced",
              "podly-music-creative"
            ]
          },
          "seconds": {
            "type": "integer",
            "minimum": 10,
            "maximum": 360,
            "default": 180,
            "description": "مدت هدف؛ مدت خروجی وابسته به مدل است. تعرفه هر فراخوانی است."
          },
          "creationMode": {
            "type": "string",
            "enum": [
              "simple",
              "custom"
            ]
          },
          "negativeTags": {
            "type": "string",
            "maxLength": 500
          },
          "vocalGender": {
            "type": "string",
            "enum": [
              "m",
              "f"
            ]
          },
          "styleWeight": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "weirdness": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "variety": {
            "type": "number",
            "minimum": 0,
            "maximum": 4
          },
          "autoDuration": {
            "type": "boolean"
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          },
          "singingVoiceId": {
            "type": "string",
            "format": "uuid",
            "description": "اختیاری و فقط در mode=vocal: شناسهٔ صدای خوانندهٔ آماده و فعالِ همان حساب در سایت. ثبت و تأیید این صدا API عمومی ندارد و به فعال‌بودن قابلیت در سایت وابسته است. با personal_voice گفتار متفاوت است؛ vocalGender در این حالت نادیده گرفته می‌شود."
          }
        }
      },
      "StoryChild": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 40
          },
          "pronunciation": {
            "type": "string",
            "maxLength": 60,
            "description": "همان نام با حرکت‌گذاری؛ بدون تغییر حروف"
          },
          "role": {
            "type": "string",
            "enum": [
              "address",
              "character"
            ],
            "default": "address"
          },
          "characterName": {
            "type": "string",
            "maxLength": 60
          },
          "referenceId": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "ChildrenStoryInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "mode": {
            "type": "string",
            "enum": [
              "auto",
              "new",
              "search",
              "catalog",
              "own"
            ],
            "default": "new",
            "description": "روش روایت: new ایدهٔ تازه، own متن کامل، search قصهٔ آشنا، catalog از فهرست و auto تشخیص خودکار"
          },
          "age": {
            "type": "string",
            "enum": [
              "3-5",
              "6-8",
              "9-12",
              "13-15"
            ],
            "default": "6-8"
          },
          "prompt": {
            "type": "string",
            "minLength": 3,
            "maxLength": 24000,
            "description": "new/search: تا ۳۰۰۰ نویسه؛ own: حداقل ۱۰۰؛ catalog بدون prompt"
          },
          "catalogId": {
            "type": "string",
            "pattern": "^[a-z0-9-]{2,80}$"
          },
          "duration": {
            "type": "string",
            "enum": [
              "short",
              "medium",
              "long"
            ],
            "description": "اندازهٔ هدف قصه: short حدود ۳، medium حدود ۶ و long حدود ۱۰ دقیقه"
          },
          "creativity": {
            "type": "string",
            "enum": [
              "faithful",
              "expressive",
              "free"
            ],
            "default": "faithful"
          },
          "children": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/StoryChild"
            },
            "description": "حداکثر پنج کودک؛ مشخصات هر عضو در جدول زیر آمده است"
          },
          "referenceId": {
            "type": "string",
            "format": "uuid",
            "description": "شناسه عکس آپلودشده با همین کلید"
          },
          "imageCount": {
            "type": "integer",
            "deprecated": true,
            "default": 1,
            "description": "همیشه یک تصویر جلد ساخته می‌شود؛ این گزینهٔ قدیمی و مقدار آن نادیده گرفته می‌شوند."
          },
          "soundscape": {
            "type": "string",
            "enum": [
              "auto",
              "off"
            ],
            "default": "auto"
          },
          "auto_continue": {
            "type": "boolean",
            "default": true,
            "description": "false برای بازبینی ساختار روایت پیش از صوت"
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        },
        "description": "ورودی همان موتور قصه سایت؛ برای حالت catalog، catalogId و برای بقیه prompt لازم است. کیف پول Kids استفاده نمی‌شود.",
        "oneOf": [
          {
            "required": [
              "catalogId",
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "catalog"
                ]
              }
            }
          },
          {
            "required": [
              "prompt"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "new",
                  "search"
                ]
              },
              "prompt": {
                "type": "string",
                "minLength": 3,
                "maxLength": 3000
              }
            }
          },
          {
            "required": [
              "prompt",
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "auto"
                ]
              },
              "prompt": {
                "type": "string",
                "minLength": 3,
                "maxLength": 24000
              }
            }
          },
          {
            "required": [
              "prompt",
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "own"
                ]
              },
              "prompt": {
                "type": "string",
                "minLength": 100,
                "maxLength": 24000
              }
            }
          }
        ]
      },
      "StoryAction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "approve",
              "resume"
            ]
          },
          "script": {
            "type": "object",
            "description": "ساختار story.script از output؛ cast و segments و title و visualBrief و pronunciations"
          },
          "match_index": {
            "type": "integer",
            "minimum": 0
          },
          "resolution": {
            "type": "string",
            "enum": [
              "inspired",
              "retry_lookup"
            ]
          },
          "image_scene": {
            "type": "string",
            "minLength": 15,
            "maxLength": 1500
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "برای continue الزامی؛ سقف کل رزرو مورد تأیید، نه مبلغ اضافه"
          }
        }
      },
      "ApiRate": {
        "type": "object",
        "required": [
          "id",
          "label",
          "unit",
          "quantity",
          "available"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "unit": {
            "type": "string",
            "enum": [
              "input_tokens",
              "output_tokens",
              "embedding_tokens",
              "characters",
              "audio_tokens",
              "utf8_bytes",
              "call",
              "image"
            ]
          },
          "quantity": {
            "type": "integer",
            "enum": [
              1,
              1000000
            ]
          },
          "available": {
            "type": "boolean"
          },
          "site_credits": {
            "type": "number",
            "minimum": 0
          },
          "api_credits": {
            "type": "number",
            "minimum": 0
          },
          "discount_credits": {
            "type": "number",
            "minimum": 0
          },
          "voice": {
            "type": "string"
          },
          "model": {
            "type": "string"
          }
        }
      },
      "ApiPricing": {
        "type": "object",
        "required": [
          "currency",
          "basis",
          "rates"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "enum": [
              "credits"
            ]
          },
          "basis": {
            "type": "string",
            "enum": [
              "isolated_unit_reference"
            ]
          },
          "credit_value_usd": {
            "type": "number"
          },
          "credit_value_toman": {
            "type": "number",
            "nullable": true
          },
          "rates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiRate"
            }
          },
          "policy": {
            "type": "object"
          },
          "reservation": {
            "type": "string"
          },
          "discount": {
            "type": "string"
          },
          "rounding": {
            "type": "string"
          }
        }
      },
      "PodcastContinueInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "text": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000,
            "description": "درخواست ادامه تا ۳۰۰۰ نویسه؛ در continue اختیاری و در question یا explain حداقل ۳ نویسه است."
          },
          "title": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120
          },
          "voice": {
            "type": "string",
            "description": "در ادامه، گوینده از والد به ارث می‌رسد؛ برای تغییر گوینده از speakers استفاده کنید."
          },
          "tone": {
            "type": "string",
            "enum": [
              "conversational",
              "expert",
              "analytical",
              "dialogue",
              "energetic",
              "friendly",
              "formal",
              "luxury",
              "trustworthy",
              "playful"
            ]
          },
          "instructions": {
            "type": "string",
            "minLength": 0,
            "maxLength": 3000
          },
          "duration": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "default": 4
          },
          "speakers": {
            "type": "array",
            "minItems": 1,
            "maxItems": 3,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "name"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 60
                },
                "voice": {
                  "type": "string"
                },
                "personal_voice": {
                  "$ref": "#/components/schemas/PersonalVoiceReference"
                }
              },
              "oneOf": [
                {
                  "required": [
                    "voice"
                  ]
                },
                {
                  "required": [
                    "personal_voice"
                  ]
                }
              ]
            },
            "description": "یک تا سه گوینده؛ هر عضو name و دقیقاً یکی از voice عمومی یا personal_voice با دو لینک فایل خودش را دارد. personal_voice سطح اصلی را هم‌زمان نفرستید."
          },
          "continuation_mode": {
            "type": "string",
            "enum": [
              "continue",
              "question",
              "explain"
            ],
            "description": "فقط همراه parent_job_id؛ سؤال یا بخش موردنظر در text (حداکثر ۳۰۰۰ نویسه)."
          },
          "auto_continue": {
            "type": "boolean",
            "description": "false برای بازبینی متن پیش از صوت. تبلیغ همیشه ابتدا منتظر بازبینی می‌ماند؛ برای مقاله کاربرد صوتی ندارد."
          },
          "personal_voice": {
            "$ref": "#/components/schemas/PersonalVoiceReference"
          },
          "max_reserved_credits": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "سقف رزرو اختیاری؛ باید دست‌کم برابر برآورد فعلی باشد. سقف بیشتر مجوز رزرو اضافه است، هزینه نهایی مصرف واقعی است و باقیمانده برمی‌گردد."
          }
        },
        "not": {
          "anyOf": [
            {
              "required": [
                "voice",
                "personal_voice"
              ]
            },
            {
              "required": [
                "speakers",
                "personal_voice"
              ]
            }
          ]
        },
        "description": "والد از شناسهٔ مسیر مشخص می‌شود. در حالت continue بدنهٔ خالی مجاز است؛ در question و explain، text بین ۳ تا ۳۰۰۰ نویسه لازم است. هر ادامه یک کار و رزرو تازه می‌سازد.",
        "oneOf": [
          {
            "properties": {
              "continuation_mode": {
                "type": "string",
                "enum": [
                  "continue"
                ]
              }
            }
          },
          {
            "required": [
              "continuation_mode",
              "text"
            ],
            "properties": {
              "continuation_mode": {
                "type": "string",
                "enum": [
                  "question",
                  "explain"
                ]
              },
              "text": {
                "type": "string",
                "minLength": 3,
                "maxLength": 3000
              }
            }
          }
        ]
      }
    }
  },
  "x-podly-services": [
    {
      "id": "tts",
      "path": "tts",
      "name": "تبدیل متن به صوت",
      "schema": "TtsInput",
      "scope": "tts:write"
    },
    {
      "id": "podcast",
      "path": "podcasts",
      "name": "پادکست",
      "schema": "PodcastInput",
      "scope": "podcasts:write"
    },
    {
      "id": "dialogue",
      "path": "dialogues",
      "name": "گفتگوی دو نفره",
      "schema": "DialogueInput",
      "scope": "dialogues:write"
    },
    {
      "id": "source_podcast",
      "path": "source-podcasts",
      "name": "پادکست از منبع",
      "schema": "SourcePodcastInput",
      "scope": "sources:write"
    },
    {
      "id": "advertisement",
      "path": "advertisements",
      "name": "صوت تبلیغاتی",
      "schema": "AdvertisementInput",
      "scope": "advertisements:write"
    },
    {
      "id": "article",
      "path": "articles",
      "name": "مقاله",
      "schema": "ArticleInput",
      "scope": "articles:write"
    },
    {
      "id": "music",
      "path": "music",
      "name": "ساخت موزیک",
      "schema": "MusicInput",
      "scope": "music:write"
    },
    {
      "id": "children_story",
      "path": "children-stories",
      "name": "داستان کودک",
      "schema": "ChildrenStoryInput",
      "scope": "stories:write"
    },
    {
      "id": "composition",
      "path": "compositions",
      "name": "صوت چندبخشی",
      "schema": "CompositionInput",
      "scope": "compositions:write"
    }
  ],
  "x-podly-examples": {
    "tts": {
      "text": "سلام! این اولین آزمایش API آوا ساز است.",
      "voice": "Kore",
      "pace": "normal"
    },
    "podcast": {
      "text": "سه راهکار ساده برای مدیریت زمان",
      "duration": 2,
      "voice": "Kore",
      "tone": "conversational"
    },
    "dialogue": {
      "text": "مزایا و چالش‌های دورکاری",
      "duration": 2,
      "voice": "Kore",
      "voice_two": "Puck",
      "speaker_one": "مجری",
      "speaker_two": "کارشناس",
      "mode": "conversation"
    },
    "source_podcast": {
      "text": "نکات اصلی منبع را توضیح بده.",
      "source_text": "کتاب‌خوانی روزانه می‌تواند تمرکز و دامنهٔ واژگان را تقویت کند. شروع با زمان کوتاه و انتخاب کتاب متناسب با علاقه، به ماندگاری این عادت کمک می‌کند.",
      "source_mode": "full",
      "duration": 2,
      "voice": "Kore"
    },
    "advertisement": {
      "text": "معرفی سرویس ساخت محتوای صوتی آوا ساز",
      "brand_name": "آوا ساز",
      "audience": "تولیدکنندگان محتوا",
      "duration_seconds": 15,
      "goal": "awareness",
      "platform": "podcast",
      "call_to_action": "برای ساخت اولین محتوا به آوا ساز سر بزنید.",
      "voice": "Kore"
    },
    "article": {
      "text": "راهنمای انتخاب میکروفن برای پادکست",
      "tone": "expert",
      "keywords": "میکروفن، ضبط صدا"
    },
    "composition": {
      "title": "برنامهٔ آموزشی",
      "segments": [
        {
          "text": "به برنامهٔ ما خوش آمدید.",
          "voice": "Kore",
          "pace": "normal"
        },
        {
          "text": "امروز دربارهٔ یادگیری صحبت می‌کنیم.",
          "voice": "Puck",
          "pace": "slow"
        }
      ]
    },
    "music": {
      "title": "موسیقی شروع برنامه",
      "prompt": "موسیقی بی‌کلام آرام با پیانو و سازهای زهی",
      "mode": "instrumental",
      "model": "podly-music-quick",
      "creationMode": "simple"
    },
    "children_story": {
      "title": "دوست کوچک باغ",
      "mode": "new",
      "prompt": "قصه‌ای دربارهٔ دوستی یک گنجشک و یک گل آفتابگردان بساز.",
      "age": "6-8",
      "duration": "short",
      "imageCount": 1,
      "soundscape": "auto",
      "auto_continue": true
    }
  }
}
