{ "openapi": "3.0.3", "info": { "title": "Podly Developer API", "version": "1.0.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": "integer" } } } } } }, "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" } } } } } } }, "/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" } } } } } } } } }, "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}": { "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": "دانلود فایل WAV با کلید ایجادکننده", "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" } } } }, "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" } } } } } } }, "/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": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ] }, "credit_limit": { "type": "integer", "nullable": true }, "remaining_credits": { "type": "integer", "nullable": true }, "wallet_balance": { "type": "number", "minimum": 0, "description": "Available API wallet credits, separate from studio credits and key budget." } } } } } }, "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": "Completed output", "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" } } } } } } }, "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." } } }, "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": "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" } } }, "PodcastInput": { "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 } } }, "EstimateInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "service", "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": "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" } } }, { "type": "object", "additionalProperties": false, "required": [ "service", "text" ], "properties": { "service": { "type": "string", "enum": [ "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 } } }, { "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": "Voice ID from GET /voices", "default": "Kore" }, "speaker_one": { "type": "string", "minLength": 1, "maxLength": 40 }, "speaker_two": { "type": "string", "minLength": 1, "maxLength": 40 }, "mode": { "type": "string", "enum": [ "conversation", "debate" ], "default": "conversation" } } }, { "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" ], "default": "full" }, "source_id": { "type": "string", "format": "uuid", "description": "ID from POST /sources using the same API key. Exactly one of source_id/source_text." } }, "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" ] } } }, { "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 } } }, { "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" } } } } } } ] }, "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" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled", "awaiting_review" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "reserved_credits": { "type": "integer" }, "charged_credits": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "audio_url": { "type": "string", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "wallet_type": { "type": "string", "enum": [ "api", "studio" ], "description": "API wallet for new jobs; studio for jobs created before wallet separation." }, "output_url": { "type": "string", "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" } } }, "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" ], "default": "full" }, "source_id": { "type": "string", "format": "uuid", "description": "ID from POST /sources using the same API key. Exactly one of source_id/source_text." } }, "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" ] } } }, "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 } } }, "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" } } } } } } } } }