Makaleden Konuşmaya (ATS)

Tam bir makaleyi seslendirilmiş bir kayda ve metin dökümüne dönüştürün; bunlar geri çağırma (callback) URL’nize asenkron olarak iletilecektir.

Article to Speech (ATS) uç noktası, bir makalenin metnini alır ve MP3 formatında bir seslendirme ile buna senkronize edilmiş bir döküm (.srt) dosyası oluşturur. Oluşturma işlemi asenkron olarak gerçekleşir: istek anında 202 Accepted yanıtıyla döner ve tamamlanan dosyalar, belirttiğiniz callbackURL adresine iletilir. Bu, ATS WordPress eklentisine güç veren hizmetin aynısıdır.

Kimlik Doğrulama

Şirketinizin API anahtarını Authorization başlığına Bearer token olarak ekleyin.

Authorization: Bearer your_api_key

İstek Gövdesi

Ham makale metnini ve isteği tanımlayan bir postData nesnesini içeren bir JSON gövdesi gönderin.

postData Nesnesi

Örnek Talep

curl -X POST "https://api.moknah.io/process-text" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
    "postData": {
        "name": "AI is evolving fast",
        "articleId": "post-123",
        "voiceId": "12",
        "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
        "preprocessType": "0",
        "regenerate": false
    }
  }'

import requests

response = requests.post(
    "https://api.moknah.io/process-text",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
        "postData": {
            "name": "AI is evolving fast",
            "articleId": "post-123",
            "voiceId": "12",
            "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
            "preprocessType": "0",
            "regenerate": False
        }
    }
)

# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)

const response = await fetch(
    'https://api.moknah.io/process-text',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
            postData: {
                name: 'AI is evolving fast',
                articleId: 'post-123',
                voiceId: '12',
                callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
                preprocessType: '0',
                regenerate: false
            }
        })
    }
);

// 202 Accepted — result arrives at your callbackURL

Anında Müdahale

İstek kabul edilirse, uç nokta derhal yanıt verir:

Processing started. Results will be sent to the callback URL.

Geri Çağırma Yükü

Oluşturma işlemi tamamlandığında, Moknah, callbackURL adresinize şu JSON gövdesiyle bir POST isteği gönderir:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}

İmzanın Doğrulanması

İmza, API anahtarınızın SHA-256 hex özeti (digest) ile anahtarlanmış; articleId|audioFile|srtFile dizisinin HMAC-SHA256 (hex) değeridir. Geri çağrının (callback) Moknah’tan geldiğini ve üzerinde değişiklik yapılmadığını doğrulamak için bu değeri kendi tarafınızda yeniden hesaplayıp karşılaştırın.

import crypto from 'crypto';

const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');

const isValid = expected === signature;

import hashlib, hmac

key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()

is_valid = hmac.compare_digest(expected, signature)

İdempotentlik ve Yeniden Oluşturma

• İstekler, şirket bazında articleId’ye göre tanımlanır. Yeni bir articleId, yeni bir üretim sürecini başlatır.
• Halihazırda bir makale oluşturuluyorsa, yinelenen istekler 409 ALREADY_PROCESSING hatasıyla reddedilir.
• Bir makale halihazırda oluşturulmuşsa ve `regenerate` parametresi `false` olarak ayarlanmışsa, mevcut ses dosyası yeniden oluşturulmadan (ve yeniden ücretlendirme yapılmadan) `callbackURL` adresinize tekrar iletilir.
• Mevcut bir articleId için sıfırdan bir oluşturma işlemini zorunlu kılmak üzere regenerate değerini true olarak ayarlayın.
• Önceki bir deneme başarısız olduysa, ilgili articleId için saklanan sonuç boş olabilir. Daha sonra regenerate parametresi false olarak yapılan bir istek bu boş sonucu tekrar döndürebilir; bu nedenle durumu düzeltmek için isteği regenerate parametresi true olacak şekilde yeniden gönderin (veya yeni bir articleId kullanın).

Eşzamanlılık ve iş hacmi

Her bir makale, cümlelerinin tüm hesabınız genelinde paylaşılan bir eşzamanlılık sınırına tabi olan metin-ses dönüştürme sağlayıcısı nezdinde paralel olarak oluşturulmasıyla seslendirilir. Aynı anda çok sayıda makale gönderilmesi bu sınırı aşabilir ve tekil cümlelerin —dolayısıyla makalelerin tamamının— işlenememesine yol açabilir.

• Çok bölümlü bir sayfayı hazırlarken, tüm bölümleri aynı anda göndermek yerine, bir seferde yalnızca birkaçını (yaklaşık üç tane) işleme alın.
• Başarısız olan makaleleri, `regenerate` parametresini `true` olarak ayarlayarak yeniden deneyin; halihazırda oluşturulmuş makaleler önbelleğe alınmıştır ve yeniden gönderilmeleri gerekmez.
• /process-text uç noktası da istemci başına hız sınırına tabidir; sınırı aşan ani yoğunluklar ”429 Too Many Requests” (Çok Fazla İstek) hatasıyla sonuçlanır; bu nedenle isteklerinizi zamana yaymalı veya toplu halde göndermelisiniz.

Faturalandırma

Karakter maliyeti, text karakter sayısı ile ön işleme faktörünün (varsayılan olarak 1; preprocessType değeri 2 olduğunda ise 2) çarpılmasıyla hesaplanır. Krediler yalnızca üretim işlemi fiilen gerçekleştiğinde düşülür. Daha önce üretilmiş bir makalenin yeniden iletilmesi ücretsizdir; üretim veya iletim işleminin başarısız olması durumunda ise düşülen krediler otomatik olarak iade edilir.

Hatalar