API genel bakışı
Kendi uygulamanızdan Speechdash'ı çağırabilir ve yetkilendiren API anahtarlarını oluşturabilirsiniz.
Speechdash API, kendi uygulamanızdan belgeler oluşturmanıza ve uygulama içindeki seslerle aynı sesleri üretebilmenize olanak tanır. API üzerinden oluşturduğunuz her şey, kütüphanenizde de görünecektir. Uygulamada tamamlanan ses ve video metinleri de kütüphane belgeleri olarak görünür (source transcription ve transcript_id ile). /transcripts REST kaynağı yoktur: belge uç noktalarını kullanın. API, metin işleme işlemlerini başlatmaz.
Temel URL:
https://api.speechdash.com/v1Sağlık kontrolü (API anahtarı yok): GET https://api.speechdash.com/health
Makine okunabilir sözleşme, https://api.speechdash.com/v1/openapi.json adresinden yayınlanmıştır, böylece diliğiniz için bir istemci oluşturabilirsiniz.
Uç Noktalar
| Yöntem | Yol | Amaç |
|---|---|---|
GET | /health | Hizmet sağlığı ( /v1 altında değil) |
GET | /v1/openapi.json | OpenAPI 3.1 belgesi |
GET | /v1/me | Hesap, plan ve cüzdan |
GET | /v1/documents | Kütüphane belgelerini ve tamamlanan metinleri listele |
POST | /v1/documents | Metin belgesi oluştur (source=api) |
GET | /v1/documents/{document_id} | Bir belgeyi ve metnini oku |
PUT | /v1/documents/{document_id} | Başlık, metin, dil, is_archived veya visibility güncelle |
DELETE | /v1/documents/{document_id} | Bir belgenin silinmesi |
POST | /v1/documents/{document_id}/translate | Yeni çevrilmiş sürüm (MP3 ihraç ile aynı krediler) |
GET | /v1/documents/{document_id}/export | pdf, docx, txt, csv, srt veya vtt indir |
POST | /v1/audio/speech | En fazla 5.000 karakter üretsin (JSON + ses) |
POST | /v1/audio/stream | WAV akışı, en fazla 20.000 karakter |
POST | /v1/audio/stream/with-timestamps | Her cümle için ses ve işaretler ile SSE |
GET | /v1/voices | Ses kataloğu |
GET | /v1/voices/{voice_id} | Bir ses ön ayarı |
Etkileşimli OpenAPI sayfaları: Hesap, Belgeler, Ses, Sesler.
MCP Sunucusu (AI Asistanları için)
Cursor, Claude Masaüstü veya başka bir MCP istemcisini kullanıyorsanız, HTTP çağrılarını yapmak yerine resmi Speechdash MCP sunucusunu ekleyebilirsiniz. Aynı anahtarlar ve faturalama ile bu rehberde açıklanan API anahtarları tarafından desteklenen araçlar olarak kütüphanenizi (tamamlanan metinleri de dahil), çeviri, ihraç, sesler, hesap özeti ve akışsız ses sentezi sunar. Akışlı ses sentezi REST'te kalır.
MCP sunucusunun tam araç listesi ve kurulumu için MCP sunucusuna bakın (stdio veya Streamable HTTP). Ayrıca, makine okunabilir belgeler içeren AI sistemleri için pazarlama sitesindeki Ajanslar hub'una da bakabilirsiniz. Kullanıcılar, bu Yardım Merkezi'ndeki API anahtarları ve MCP sayfasından başlayabilir.
Bir API anahtarı oluşturun
Ayarlar → API'yi açın.
Yeni anahtarı tıklayın ve kullanım yerini belirtmek için bir adı verin, örneğin Üretim sunucusu.
Anahtarı hemen kopyalayın. Sadece ön ek saklanır, bu nedenle bir kez gösterilir ve daha asla gösterilmez.
Bir anahtar hesabınıza etki eder. Anahtarı sunucunuzda saklayın, asla bir tarayıcıda, mobil uygulamada veya bir kamuya açık depoda saklamayın. Bir anahtar sızarsa, Ayarlar → API'den iptal edin ve yeni birini oluşturun.
10 aktif anahtar tutabilir, her zaman yeniden adlandırabilirsiniz ve her birinin son kullanım zamanını görebilirsiniz. Bir anahtarı iptal etmeniz, o anahtardan gelen istekleri hemen durdurur.
Bir isteği yetkilendirin
Anahtarı bir yetkilendirme tokeni olarak gönderin:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"Geçersiz bir anahtar olmadan yapılan istekler 401 koduyla unauthorized yanıtı verir.
GET /me, hesabınızın id'sini, e-posta adresinizi, planınızı ve cüzdan bakiyenizi (wallet_cents ve display_credits) yanıtlar, ayrıca kullanılan API anahtarının metadata'sını içerir. Bu, kurulumdan sonra bir anahtarı doğrulamanız için kullanılabilir (örneğin Zapier'de).
POST /documents ve POST /audio/speech, opsiyonel bir Idempotency-Key başlığı kabul eder. Aynı anahtar ve aynı gövde ile aynı anahtarı tekrar denediğinizde, ilk başarılı yanıtı 24 saat boyunca tekrar oynatır, böylece bir ağ arızası ikinci bir belge oluşturmaz veya sesi iki kez faturalandırmaz. Bir ses yanıtı saklanamayacak kadar büyükse, aynı anahtar ile tekrar denendiğinde 409 yanıtı verir (ilk isteğin zaten faturalandığı) ve yeniden üretilmez (orijinal isteğin zaten faturalandığı). /audio/speech için bir istemci koparsa 204 yanıtı verir, üretilen herhangi bir sesi hesaplar ve anahtarı serbest bırakır, böylece bir tekrar denemesi yeniden üretebilir. Akışlı ses uç noktaları başlığı reddeder.
Krediler
Ses sentezi, uygulamanın aynı cüzdanından krediler kullanır: 0.5 kredi (1 cüzdan centi) başlatılan her 30 saniyelik üretilen ses için. Her istekte, üretim başlamadan önce bir tahmini tutar (plus küçük bir marj) tutulur, ardından üretilen sesin gerçek tutarıyla hesaplanır. Kalan tutar iade edilir; her hesaplanan isteğin Ayarlar → Kredi kullanımı altında API ses sentezi olarak görünür. API yanıtlarındaki billed_credits alanı cüzdan centi'dir (2 cent = 1 gösterim kredisi). Bir akış ortada kesilirse, zaten teslim edilen cümleler hala faturalandırılır.
Hesabınızın tutarı tutar tutulmasını karşılamıyorsa, API, herhangi bir şey üretecek önce 402 yanıtı verir ve payment_required kodunu içerir.
Belgeler oluşturmak krediler harcamaz, ancak planınızın günlük belge sınırına (Ücretsiz: 3 günlük; Unlimited: günlük sınır yok) sayılır ve yükleme süresi sınırlarına katılır. Dosya ihraç etme krediler harcamaz.
Fatura vs. Uygulama içi Bulut Oynatma
Uygulama içi Bulut tekrar oynatma, belgeye özel cümle önbelleğini yeniden kullanır: sunucuda zaten üretilmiş bir cümleyi tekrar oynatmak 0 gösterim kredisi maliyet edebilir. REST ve MCP ses uç noktaları her zaman taze ses üretir ve üretilme sırasında başlatılan her 30 saniyelik üretilen ses için aynı oranda faturalandırır. API veya MCP sentezi için tekrar oynatma önbelleği yoktur.
Sınırlar
| Sınır | Değer |
|---|---|
/documents istekleri | 120 dakikada, hesap başına |
/audio/* istekleri | 60 dakikada, hesap başına |
| Paralel ses istekleri | 3, hesap başına |
POST /audio/speech input | 5.000 karakter |
POST /audio/stream input | 20.000 karakter |
| Belge metni | 500.000 karakter |
| Aktif API anahtarları | 10 |
Rate limitler, anahtar başına değil, hesap başına sayılır, bu nedenle ek anahtarlar, kotalarınızı artırmaz. Her yanıt X-Request-ID içerir ve /documents ile /audio/* de X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset döndürür. Destek ekibine başvurduğunuzda X-Request-ID'yi alıntılayın.
Ses istekleri de bir paralelizm sınırına sahiptir: dördüncü eşzamanlı isteğin yanıtı 429 olurken, üçü hala çalışıyor olabilir, böylece bir entegrasyon sentezi tek başına monopolize etmez. 429 ve 503 yanıtlarını Retry-After başlığının ardından tekrar deneyin.
İçerik, ses sınırlarından daha uzun ise, POST /v1/documents ile bir belge oluşturun ve uygulamadan sesini ihraç edin.
Belgeler: paylaş, çevir, ihraç et
Serileştirilmiş belgeler visibility ve share_url (özel olduğunda null) içerir. PUT /v1/documents/{id} visibility kabul eder, /share/document/{id} adresinde okunabilir ancak yayınlanmamış bir sayfa oluşturur ve is_archived arşivlemek veya geri almak için kullanılır. Paylaşılan sayfalar metin tabanlıdır. Onlar ücretli sesleri oynatmaz.
POST /v1/documents/{id}/translate, yeni bir çevrilmiş sürüm oluşturur. MP3 ihraç ile aynı kredi cüzdanını faturalandırır (başlatılan her 30 saniyelik tahmini ses için 0.5 kredi) ve cüzdan yetersiz olduğunda 402 yanıtı verir. Çeviri yapılandırılmamış veya çalışmıyorsa 503 yanıtı verir.
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt, mevcut sürümü bir ek olarak indirir. timestamps=1 ekleyerek PDF, DOCX, TXT ve CSV'de bölüm zamanlarını içermesini sağlayabilirsiniz. SRT ve VTT, bir metin işleme veya tamamlanmış cümle zamanlamaları gerektirir. GET /v1/documents/{id} üzerindeki depolanan text, metin işleme zaman damgalarını içerir. Bunları gizlemek, bir uygulama okuyucusu ayarıdır.