Geliştiriciler için ClientPoster API

Son güncelleme: 17 Ekim 2026

ClientPoster, sosyal medya ajansları için yapay zekâ video ve içerik stüdyosudur: 30 dakikaya kadar çok sahneli videolar, sahne sahne düzenleme, marka sesine uygun gönderi metni ve görseller. Bu API, ajansınızın ClientPoster'da yaptığı işleri başka sistemlerden ve yapay zekâ asistanlarından yapmanızı sağlar: müşterilerinizi ve marka rehberlerini yönetin, onlar için gönderi metni, görsel, görsel serisi, doküman ve video üretin, videonun sahnelerini düzeltin, üretilen içeriği müşterinizin onayına gönderin.

X müşterisi için LinkedIn'e 60 saniyelik, 6 sahneli, yatay bir ürün tanıtım videosu hazırla; önce bedeli söyle, onaylarsam üret.

1. Başlarken

Bir API anahtarı oluşturun: ClientPoster'a giriş yapın, menüde Hesap bölümündeki API Anahtarları sayfasını açın. Anahtarı ajans sahibi ya da yöneticisi oluşturabilir; API erişimi ücretli paketlerde açıktır. Anahtar yalnız bir kez gösterilir — parola gibi saklayın.

Bütün isteklerin temel adresi: https://api.clientposter.com/api/v1

Örneklerde anahtar CP_API_KEY ortam değişkeninden okunur (bash ya da zsh; Windows'ta Git Bash ya da WSL). İlk istek anahtarın kime ait olduğunu döndürür:

curl -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/profil"

2. Kimlik ve izinler

Her istekte anahtarı Authorization başlığında Bearer olarak gönderin. Anahtar onu oluşturan kişi adına çalışır: o kişi ekipten çıkarılır ya da askıya alınırsa anahtar da çalışmaz; yetkisi, oluşturulurken seçilen izinlerle kişinin o anki rolünün kesişimidir.

Her işlem tek bir izin ister; hangisini istediği API tanımında da yazar (x-clientposter-permission):

3. Hatalar ve hız sınırı

Hatalar RFC 7807 biçiminde (application/problem+json) döner: değişmeyen bir hata kodu (kod) ve destek için bir iz kimliği (traceId) taşır; alan doğrulama hatalarında errors nesnesi alanları tek tek listeler. Hata metni Accept-Language başlığına göre Türkçe ya da İngilizcedir.

• 400 — talep geçersiz; errors nesnesine bakın.
• 401 — anahtar yok, tanınmıyor, geri çekilmiş ya da süresi dolmuş.
• 403 — bu işlem API anahtarına açık değil, anahtarın bu izni yok ya da paketinizde API erişimi yok.
• 404 — kayıt bulunamadı ya da başka bir ajansa ait.
• 409 — aynı talep anahtarıyla başlatılan üretim hâlâ sürüyor.
• 429 — hız sınırı aşıldı; Retry-After başlığındaki saniye kadar bekleyin.

Hız sınırı: anahtar başına dakikada 120 istek.

4. Örnek akış: gönderi üretip onaya gönderme

Adımlar sırayla çalıştırılabilir. Büyük harfli yer tutucuları (CLIENT_ID, CONTENT_ID, MEDIA_ID) önceki adımın yanıtındaki kimliklerle değiştirin.

Müşterinizi bulun

Müşterilerinizi ve kimliklerini (id) listeler.

curl -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/musteriler"

Gerekirse müşteri ekleyin

Yeni bir müşteri oluşturur (customers izni); dil ve ton 5. bölümdeki değerlerden biri olmalı.

curl -X POST -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad": "Example Cafe",
    "sektor": "Cafe and restaurant",
    "dil": "en",
    "ton": "friendly"
  }' \
  "https://api.clientposter.com/api/v1/musteriler"

Kredi bakiyenizi ve bedelleri görün

Müşterilerinizi, kredi bakiyenizi ve her içerik tipinin kredi bedelini tek yanıtta döndürür; kredi harcamaz.

curl -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/icerik/sihirbaz"

Tek bir içeriğin bedelini sorun

Bir içerik tipinin belirli sayıda platform için kredi bedeli (burada metin, bir platform). Üretimde düşülen bedelle aynı formülden hesaplanır ve kredi harcamaz.

curl -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/icerik/bedel/text/1"

Referans görsel yükleyin (isteğe bağlı)

Ürün, logo, mekân ya da kişi görselini görsel veya video üretiminde kullanmak için önce yükleyin (generate izni, kredi harcamaz). Gövde multipart/form-data: talep parçasında JSON (hakBeyani görselleri kullanma hakkınız olduğunu onaylar), her dosya dosyalar adlı ayrı bir parçada. Yanıttaki her görselin id değerini üretim talebinin referanslar alanına rolüyle (product, logo, place, person) yazın ve referansHakBeyani alanını true gönderin.

curl -X POST -H "Authorization: Bearer $CP_API_KEY" \
  -F 'talep={"hakBeyani":true};type=application/json' \
  -F "dosyalar=@product.jpg" \
  "https://api.clientposter.com/api/v1/icerik/referans"

İçeriği üretin

Kredi harcar (generate izni). Yanıt üretilen metni, varyantları ve içerik kimliğini (icerikId) taşır; metin ve tek görsel aynı istekte üretilir.

curl -X POST -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "talepAnahtari": "autumn-menu-0001",
    "musteriId": "CLIENT_ID",
    "amac": "awareness",
    "platformlar": [
      "linkedin"
    ],
    "tip": "text",
    "dil": "en",
    "ton": "friendly",
    "uzunluk": "short",
    "brief": "Announce our new autumn menu with warm drinks and fresh pastries. Invite people to visit this week."
  }' \
  "https://api.clientposter.com/api/v1/icerik/uret"

Her yeni üretim için benzersiz bir talepAnahtari gönderin (ör. bir UUID). Aynı anahtarla tekrarlanan istek ikinci kez kredi düşmez: ilk üretim bittiyse aynı sonucu döndürür, sürüyorsa 409 verir.

Uzun işleri izleyin

Görsel serisi ve video arka planda üretilir. İçeriğin ayrıntısını birkaç saniyede bir okuyun; iş bitince hazır dosyalar medyalar listesinde görünür.

curl -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/icerik/CONTENT_ID/detay"

Dosyayı indirin

Medya kimliğiyle dosyayı indirir; yanıt kısa ömürlü imzalı bir adrese yönlendirebilir (-L bunu izler). Windows'ta Git Bash ile gelen eski curl (8.8.0) bu adresi açamayıp 43 hatası verebilir; Windows'un kendi curl'ünü ya da güncel bir curl kullanın.

curl -L -o media.bin -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/medya/MEDIA_ID/icerik"

Müşterinizin onayına gönderin

Müşterinize onay bağlantısı e-postayla gider (approvals izni); müşteri kararını yalnız bu bağlantıdaki sayfadan verir. Geçerlilik 1–30 gün.

curl -X POST -H "Authorization: Bearer $CP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "icerikId": "CONTENT_ID",
    "aliciEposta": "client@example.com",
    "aliciAd": "Alex Morgan",
    "ajansNotu": "Please review the post for this week.",
    "gecerlilikGun": 7
  }' \
  "https://api.clientposter.com/api/v1/onay/talep"

Onay durumunu izleyin

Onay talebinin durumunu ve müşterinin kararını döndürür.

curl -H "Authorization: Bearer $CP_API_KEY" \
  "https://api.clientposter.com/api/v1/onay/ozet/CONTENT_ID"

5. Alanların geçerli değerleri

Bu alanlar serbest metin değildir; yalnız aşağıdaki değerleri kabul eder. Liste ürünün doğruladığı kümenin kendisidir ve API tanımında da enum olarak yazar. Seçilen içerik tipi, seçilen her platformda desteklenmelidir.

amac

platformlar

tip

dil

ton

uzunluk

videoCozunurlugu

gorselCozunurlugu

kullanimYerleri

gorselBosAlan

gorselBicimi

videoBicimi

fonMuzigi

videoLogoKonumu

karakterler[].cinsiyet

karakterler[].yas

6. Teknik sınırlar

Sayılar ürünün doğrulayıcısının kullandığı değerlerdir; sınırın dışındaki istek 400 ile reddedilir ve errors nesnesi hangi alanın aşıldığını söyler.

7. Video sahneleri

Uzun videoda her sahne ayrı bir klip olarak üretilir ve yapay zekâ öteki sahnelerin istemini görmez; ortak bilgiler bu yüzden her sahnenin isteminde yeniden yazılır. Bir sahnenin istemi şu sırayla kurulur:

1. Başlık: videonun kaçıncı sahnesi olduğu, süreklilik cümlesi, klibin süresi ve tek çekim.
2. Müşterinin marka rehberinden marka bilgisi: marka adı, sektör, hedef kitle, üretim notları ve videoda yer almaması gerekenler (yasaklı kelimeler).
3. O sahneye giden referans görseller, sırayla ve rolleriyle (ürün, logo, mekân, karakter).
4. Sahnede görünen karakterler: yaş ve cinsiyet, görünüş, kişilik ve ses; ayrı kliplerde aynı yüz ve ses için her sahnede kelimesi kelimesine aynı.
5. Sahnenin mekânı seçildiyse mekânın tarifi ve fotoğrafı.
6. SAHNE: ve talebin brief alanı (genel açıklama). Doluysa her sahnede yazılır; uzun videoda her sahnenin tarifi yazılıysa boş bırakılabilir.
7. BU SAHNE: ve sahnenin tarifi (sahneler[].tarif); boşsa videonun genel açıklamasına uygun bir an istenir.
8. DEGISENLER: videonun başından bu sahneye kadar yazılan değişiklikler, sahne numaralarıyla ve sırayla.
9. KADRAJ: yalnız tam ekran görsel sağa ya da sola yerleştirildiyse; karenin o yarısı boş kalır, kişi öbür yarıda durup görseli işaret eder.
10. EK NOT: talebin ekNot alanı (her sahnede).
11. Ses: sözler konuşanın adıyla ve söylenme sırasıyla; söz yoksa kimsenin konuşmadığı açıkça yazılır.
12. En sonda fon müziği, fizik kuralı ve genel kurallar: okunabilir yazı, logo ve filigran yok; referanstakiler dışında gerçek kişilerin tanınabilir yüzü yok.

İstem 16000 karakteri aşarsa şu sırayla kısaltılır: üretim notları, hedef kitle, en eski değişiklikler, brief. Sahne tarifi, sözler, karakter ve mekân bilgileri, ek not ve kurallar hiç kesilmez.

Sahne alanları

Görseller ve sınırlar

Talebin referanslar listesinde videonun bütününde en çok 3 ürün ya da logo görseli olabilir; sahne düzeyindeki referanslar bu sayıya ayrıca eklenmez. Karakter görselleri (karakter başına bir, en çok 5 karakter), mekân fotoğrafları (mekân başına bir) ve tam ekran görseller bu sınıra sayılmaz. Bir sahnede yapay zekâya en çok 5 görsel gider: sahnede görünen karakterlerin görselleri, mekân fotoğrafı ve o sahnenin ürün ve logo görselleri. Görseller yapay zekâya tutarlılık için gider, ilk kare olarak konmaz; bir sahnenin ilk karesini doğrudan belirlemek desteklenmiyor.

Karakterler ve anlatıcı

Karakterler talebin karakterler listesinde tanımlanır; sıra numaraları 1'den başlar (ilk karakter 1), mekânlar da öyle. Yalnız sesi duyulan anlatıcı (spiker) için yalnizSes true: ekranda görünmez, görseli olamaz, sahnenin karakterler listesine yazılamaz ama sozler satırlarında konuşur. sozleriAiYazsin true anlatıcının sözlerini sahne sahne yapay zekâya yazdırır (yalnız sesi olan karakterde, videoda en çok bir tane; o karaktere elle söz yazılamaz). Kişi görseli bir karaktere bağlanır: referanslar listesinde person rolü ve karakter alanı (karakter başına bir görsel). Konuşmada geçen özel adların okunuşu müşterinin marka rehberindeki okunuş ipuçlarından gelir (satır başına yazılış: okunuş, ör. ClientPoster: Klayınt Poster; sihirbaz ucunda okunusIpuclari); bu video için markaSecimi.okunusMetni ile verilebilir. Konuşmalı bir videodan önce müşterinin okunuş ipucuna bakın, boşsa marka adı için sorun. Türkçe içerikte okunuş video modeline giden sözün yerine yazılır; kayıttaki söz, alt yazı ve gönderi metni yazılışı korur. Öteki dillerde okunuş istemde ayrı bir satır olarak gider.

Video imzası ve indirim

Üretim talebinde videoImzasi true gönderilirse videonun sol üst köşesine marka renklerinde ClientPoster imzası eklenir ve ücretli pakette videonun kredi bedeli yüzde 10 düşer; imza videoya gömülür, sonradan kaldırılamaz. Ücretsiz pakette imza her zaman eklenir ve indirim yoktur. İndirimli bedeli bedel ucunda imza=true ile önceden görebilirsiniz. İmza metni içerik dilinde yazılır (tr, en, de, fr, es, it, nl); öteki dillerde İngilizcedir.

8. Videoyu düzenleme

Teslim edilmiş video sahne sahne düzenlenebilir; video değiştiren her işlemden sonra video yeniden birleştirilir. Ücretli işlemler talepAnahtari alanıyla tekrar güvenlidir: aynı anahtarla gelen ikinci istek ikinci kez kredi düşmez.

Düzenleme uçlarında sira sahnenin sırasıdır ve 0'dan başlar (ilk sahne 0); üretim talebindeki karakter ve mekân numaraları ise 1'den başlar. Düzenleme uçlarında talepAnahtari bir UUID'dir; üretim talebinde ise 80 karaktere kadar herhangi bir metin olabilir.

Otomatik kırpma: uzun videoda konuşma olan ve fon müziği olmayan sahnelerde montaj klibin başındaki ve sonundaki sessizliği kırpar; konuşmadan önce 0,3 sn, sonra 0,6 sn pay bırakır, cümle içindeki duraklara dokunmaz, kalan 1 saniyeden kısa olacaksa kırpmaz. Kısa videoda, konuşmasız sahnede ve fon müzikli videoda kırpma yapılmaz. Üretim talebinde bunu kapatan bir alan yoktur; aralığı kendiniz belirlemek için elle kırpmayı kullanın. Her sahne ayrı bir klip olarak üretilir ve montajda birleştirilir; sahne sınırında ses kısa bir geçişle (açılıp kapanarak) birleşir.

Videoyu değiştiren işlemler (kırpma, düzeltme, önceki sürüm, yeniden üretme, birleştirme) arka planda çalışır: yanıt hemen döner, yeni video hazır olunca içeriğin ayrıntısında görünür (içeriğin detay ucunu yoklayın). Aynı anda tek düzenleme yürür: biri sürerken gelen yeni düzenleme 409 alır. Müşteri onayındaki içerik düzenlenemez.

9. Makine okunur API tanımı

Bütün işlemler, alanlar, yanıtlar ve izinler OpenAPI 3.1 biçiminde şu adreste: https://api.clientposter.com/openapi/v1.json

Bir yapay zekâ asistanıyla çalışıyorsanız ona bu adresi verin; anahtarınızı yalnız asistanın gizli ayarlarına girin, sohbete yazmayın.