curl ile Metin Okuma API'si: Eksiksiz Komut Satırı Kılavuzu

curl, bir TTS API'sini test etmenin ve toplu ses üretimini betiklemenin en hızlı yoludur. SDK yok, bağımlılık yok — sadece HTTP.

Temel İstek

curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba, dünya.", "voice": "en-US-1", "format": "mp3"}' \
  --output output.mp3

Kritik detay: --output output.mp3, ikili ses yanıtını bir dosyaya kaydeder. Onsuz, ikili veriler stdout'a yazdırılır ve terminalinizi bozar.

İstek Anatomisi

curl -X POST \                              # HTTP yöntemi
  https://api.speekoapp.com/v1/tts \       # Uç nokta
  -H "X-API-Key: $SPEEKO_API_KEY" \        # Kimlik doğrulama
  -H "Content-Type: application/json" \    # Sunucuya JSON gönderdiğimizi söyle
  -d '{ ... }' \                           # İstek gövdesi
  --output speech.mp3                      # İkili yanıtı kaydet

Tüm Mevcut Parametreler

curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Senaryonuz buraya gelir.",
    "voice": "en-US-1",
    "format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

Çıktı Formatı Örnekleri

# MP3 (varsayılan, çoğu kullanım için en iyisi)
curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba", "voice": "en-US-1", "format": "mp3"}' \
  --output out.mp3

# WAV (kayıpsız, ses düzenleme için)
curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba", "voice": "en-US-1", "format": "wav"}' \
  --output out.wav

# OGG (daha küçük dosya boyutu)
curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba", "voice": "en-US-1", "format": "ogg"}' \
  --output out.ogg

Kaydetmeden Önce Yanıtı Doğrulama

Bir hata mesajıyla iyi bir dosyayı üzerine yazmaktan kaçınmak için kaydetmeden önce HTTP durum kodunu kontrol edin:

# HTTP hatası varsa başarısız ol — hata yanıtlarını ses dosyasına kaydetme
curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba", "voice": "en-US-1", "format": "mp3"}' \
  --fail \
  --output speech.mp3

echo "Çıkış kodu: $?"  # 0 = başarı, 22 = HTTP hatası

--fail bayrağı, curl'ün HTTP hatalarında (4xx, 5xx) hata yanıt gövdesini çıktı dosyasına kaydetmek yerine 22 çıkış koduyla çıkmasını sağlar.

Yanıt Başlıklarını Göster

curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba", "voice": "en-US-1", "format": "mp3"}' \
  --output speech.mp3 \
  --dump-header /dev/stderr

Hata ayıklama için kullanışlıdır: Content-Type, Content-Length ve herhangi bir hız sınırı başlığını gösterir.

Sesi Hemen Oynat (macOS)

curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba, bu bir testtir.", "voice": "en-US-1", "format": "mp3"}' \
  --silent \
  --output - | afplay -

--output -, stdout'a yönlendirir, afplay -, stdin'den okur ve hemen oynatır. Linux eşdeğeri: | mpg123 -.

Bash ile Toplu İşleme

Bir döngüde birden çok senaryo için ses üretin:

#!/bin/bash
set -euo pipefail

API_KEY="${SPEEKO_API_KEY:?SPEEKO_API_KEY ayarlanmadı}"
OUTPUT_DIR="./audio_output"
mkdir -p "$OUTPUT_DIR"

declare -A SCRIPTS=(
  ["intro"]="Eğitime hoş geldiniz."
  ["step-1"]="Birinci adım: terminalinizi açın."
  ["step-2"]="İkinci adım: yükleme komutunu çalıştırın."
  ["outro"]="Hepsi bu kadar. İyi şanslar!"
)

for id in "${!SCRIPTS[@]}"; do
  output_file="$OUTPUT_DIR/${id}.mp3"

  if [[ -f "$output_file" ]]; then
    echo "$id atlanıyor (zaten mevcut)"
    continue
  fi

  echo "Üretiliyor: $id"

  curl -s -X POST https://api.speekoapp.com/v1/tts \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"text\": \"${SCRIPTS[$id]}\", \"voice\": \"en-US-1\", \"format\": \"mp3\"}" \
    --fail \
    --output "$output_file"

  echo "Kaydedildi: $output_file"
  sleep 0.2  # Hız sınırı nezaketi
done

echo "Bitti. $(ls "$OUTPUT_DIR"/*.mp3 | wc -l) dosya üretildi."

İstek Gövdesi için JSON Dosyası Kullanma

Daha uzun metin veya karmaşık JSON için bir dosya kullanın:

# request.json oluştur
cat > request.json << 'EOF'
{
  "text": "Bu, bir curl komutunda satır içi yazmanın garip olacağı daha uzun bir senaryodur.",
  "voice": "en-US-1",
  "format": "mp3",
  "speed": 0.95
}
EOF

# Gönder
curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json \
  --fail \
  --output output.mp3

@ öneki, curl'e bir dosyadan okumasını söyler.

curl aracılığıyla SSML

curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "<speak>Lütfen devam etmek için <emphasis level=\"strong\">1</emphasis>'e basın. <break time=\"500ms\"/> Bu menüyü tekrar duymak için 2'ye basın.</speak>",
    "voice": "en-US-1",
    "format": "mp3"
  }' \
  --output ivr_menu.mp3

Kaçışa dikkat edin: JSON dizeleri içindeki çift tırnaklar \" olarak kaçmalıdır.

Yaygın Hataları Giderme

401 Yetkisiz

{"error": "Geçersiz API anahtarı"}

Kontrol edin: $SPEEKO_API_KEY ayarlanmış, başlık X-API-Key (Authorization değil).

413 İstek Varlığı Çok Büyük Metin, istek başına sınırı aşıyor. Parçalara ayırın.

429 Çok Fazla İstek Hız sınırı aşıldı. İstekler arasında sleep ekleyin veya üstel geri çekilme uygulayın.

Bozuk çıktı dosyası --output filename.mp3'ü unuttunuz. İkili veriler stdout'a gitti ve terminalinizi bozdu. Bozuk dosyayı silin, --output ile yeniden çalıştırın.

Boş çıktı dosyası Sıfır olmayan çıkış koduyla birleştiğinde: ağ hatası veya API hatası. Hatayı net bir şekilde ortaya çıkarmak için --fail ekleyin.

Yanıt Başlıklarını İnceleme

API yanıtı, hata ayıklama ve önbelleğe alma için yararlı olan başlıklar içerir:

curl -s -I -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Test.", "voice": "en-US-1", "format": "mp3"}'

-I, yanıt başlıklarını gösterir. Content-Length (dosya boyutu), X-RateLimit-Remaining (pencerede kalan istekler) ve X-Request-Id (hata raporlarında bunu sağlayıcıya ekleyin) için bakın.

Başlarken

API anahtarınızı ayarlayın ve ilk isteğinizi çalıştırın:

export SPEEKO_API_KEY=sk-speeko-anahtarınız-buraya

curl -X POST https://api.speekoapp.com/v1/tts \
  -H "X-API-Key: $SPEEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Çalışıyor.", "voice": "en-US-1", "format": "mp3"}' \
  --output test.mp3 && echo "Başarılı"

speekoapp.com/register adresinden ücretsiz bir API anahtarı alın — 5$ kredi, kart gerekmez.

İlgili: TTS API MP3 Çıktısı, API Entegrasyonuna Başlarken.