Makale Oluşturma

Tekil makale oluşturma işlemi, API'nin en temel özelliklerinden biridir. Bu endpoint ile belirli bir başlık, yazım tonu ve makale boyutunda makale üretebilirsiniz.

📋 Endpoint Bilgileri

• URL: /api/v1/makaleler/makale-olustur
• Method: POST
• Content-Type: application/json
• Authentication: Bearer Token gerekli

📝 Request

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Body Parameters

Parametre	Tip	Zorunlu	Açıklama
baslik	string	✅	Makale başlığı (10-255 karakter)
yazimTonu	integer	✅	Yazım tonu ID'si (1-5)
makaleBoyutu	integer	✅	Makale boyutu ID'si (1-4)

Request Example

{
  "baslik": "JavaScript ile Modern Web Geliştirme Rehberi",
  "yazimTonu": 1,
  "makaleBoyutu": 2
}

✅ Response

Başarılı Yanıt (200 OK)

{
  "success": true,
  "message": "Makale oluşturma işlemi başlatıldı",
  "data": {
    "requestId": "req_123456789",
    "estimatedTime": "2-3 dakika",
    "cost": 25.0
  }
}

Response Fields

Alan	Tip	Açıklama
success	boolean	İşlem durumu
message	string	Durum mesajı
data.requestId	string	İşlem takip ID'si
data.estimatedTime	string	Tahmini tamamlanma süresi
data.cost	number	İşlem maliyeti (TL)

💻 Kod Örnekleri

JavaScript/Node.js

async function createArticle(accessToken, baslik, yazimTonu, makaleBoyutu) {
  try {
    const response = await fetch(
      "https://integration.seoauthor.ai/api/v1/makaleler/makale-olustur",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          baslik,
          yazimTonu,
          makaleBoyutu,
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Makale oluşturma hatası: ${error.message}`);
    }

    const data = await response.json();
    console.log("Makale oluşturma başlatıldı:", data);

    return data;
  } catch (error) {
    console.error("Hata:", error);
    throw error;
  }
}

// Kullanım örneği
createArticle(
  "your-access-token",
  "React Hook'lar ile Modern Uygulama Geliştirme",
  3, // Eğitici ton
  2 // Orta boyut
)
  .then((result) => {
    console.log("İşlem ID:", result.data.requestId);
  })
  .catch((error) => {
    console.error("Makale oluşturulamadı:", error);
  });

Python

import requests
import json

def create_article(access_token, baslik, yazim_tonu, makale_boyutu):
    url = "https://integration.seoauthor.ai/api/v1/makaleler/makale-olustur"

    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }

    data = {
        "baslik": baslik,
        "yazimTonu": yazim_tonu,
        "makaleBoyutu": makale_boyutu
    }

    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()

        result = response.json()
        print(f"Makale oluşturma başlatıldı: {result['data']['requestId']}")

        return result
    except requests.exceptions.HTTPError as e:
        if response.status_code == 400:
            error_data = response.json()
            print(f"Geçersiz parametreler: {error_data['message']}")
        elif response.status_code == 401:
            print("Kimlik doğrulama hatası. Token'ınızı kontrol edin.")
        elif response.status_code == 403:
            print("Yetersiz bakiye veya izin.")
        raise
    except requests.exceptions.RequestException as e:
        print(f"Bağlantı hatası: {e}")
        raise

# Kullanım örneği
try:
    result = create_article(
        "your-access-token",
        "Python ile Veri Analizi Teknikleri",
        1,  # Profesyonel ton
        3   # Uzun boyut
    )
    print(f"Tahmini süre: {result['data']['estimatedTime']}")
    print(f"Maliyet: {result['data']['cost']} TL")
except Exception as e:
    print(f"Hata: {e}")

PHP

<?php
function createArticle($accessToken, $baslik, $yazimTonu, $makaleBoyutu) {
    $url = 'https://integration.seoauthor.ai/api/v1/makaleler/makale-olustur';

    $data = [
        'baslik' => $baslik,
        'yazimTonu' => $yazimTonu,
        'makaleBoyutu' => $makaleBoyutu
    ];

    $options = [
        'http' => [
            'header' => [
                "Authorization: Bearer $accessToken",
                "Content-Type: application/json"
            ],
            'method' => 'POST',
            'content' => json_encode($data)
        ]
    ];

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    if ($result === FALSE) {
        throw new Exception('HTTP request failed');
    }

    // HTTP status code kontrolü
    $status_line = $http_response_header[0];
    preg_match('{HTTP\/\S*\s(\d{3})}', $status_line, $match);
    $status_code = $match[1];

    if ($status_code >= 400) {
        $error_data = json_decode($result, true);
        throw new Exception("API Error ($status_code): " . $error_data['message']);
    }

    return json_decode($result, true);
}

// Kullanım örneği
try {
    $result = createArticle(
        "your-access-token",
        "PHP ile Modern Web Uygulamaları",
        2,  // Samimi ton
        2   // Orta boyut
    );

    echo "Makale oluşturma başlatıldı!\n";
    echo "İşlem ID: " . $result['data']['requestId'] . "\n";
    echo "Tahmini süre: " . $result['data']['estimatedTime'] . "\n";
    echo "Maliyet: " . $result['data']['cost'] . " TL\n";
} catch (Exception $e) {
    echo "Hata: " . $e->getMessage() . "\n";
}
?>

cURL

curl -X POST https://integration.seoauthor.ai/api/v1/makaleler/makale-olustur \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "baslik": "Modern DevOps Uygulamaları ve Araçları",
    "yazimTonu": 1,
    "makaleBoyutu": 3
  }'

📊 Yazım Tonu Seçenekleri

ID	Ton	Açıklama	Önerilen Kullanım
1	Profesyonel	Formal ve teknik dil	Kurumsal içerik, teknik makaleler
2	Samimi	Dostane ve yakın dil	Blog postları, kişisel içerik
3	Eğitici	Öğretici ve açıklayıcı	Rehberler, tutorial'lar
4	İkna Edici	Satış odaklı ve motive edici	Pazarlama içeriği, ürün tanıtımı
5	Yaratıcı	Artistik ve özgün	Kreatif yazılar, storytelling

📏 Makale Boyutu Seçenekleri

ID	Boyut	Kelime Sayısı	Okuma Süresi	Maliyet
1	Kısa	300-500	2-3 dakika	15 TL
2	Orta	800-1200	4-6 dakika	25 TL
3	Uzun	1500-2000	7-10 dakika	35 TL
4	Çok Uzun	2500+	12+ dakika	50 TL

⚠️ Hata Durumları

400 Bad Request

{
  "error": "ValidationError",
  "message": "Baslik 10 karakterden kısa olamaz",
  "statusCode": 400,
  "details": {
    "field": "baslik",
    "minLength": 10,
    "currentLength": 5
  }
}

403 Forbidden - Yetersiz Bakiye

{
  "error": "InsufficientBalance",
  "message": "Yetersiz bakiye. Makale oluşturmak için 25 TL gerekli.",
  "statusCode": 403,
  "code": "INSUFFICIENT_BALANCE",
  "requiredAmount": 25.0,
  "currentBalance": 10.5
}

💡 En İyi Uygulamalar

1. Başlık Optimizasyonu

// SEO-friendly başlık kontrol fonksiyonu
function optimizeTitle(title) {
  // Çok uzun başlıkları kısalt
  if (title.length > 60) {
    title = title.substring(0, 57) + "...";
  }

  // Başka optimizasyonlar...
  return title;
}

2. Maliyet Kontrolü

async function createArticleWithBalanceCheck(title, tone, size) {
  // Önce maliyet hesapla
  const estimatedCost = calculateCost(size);

  // Bakiye kontrol et
  const balance = await getCurrentBalance();

  if (balance.amount < estimatedCost) {
    throw new Error(
      `Yetersiz bakiye. Gerekli: ${estimatedCost} TL, Mevcut: ${balance.amount} TL`
    );
  }

  // Makale oluştur
  return createArticle(title, tone, size);
}

function calculateCost(size) {
  const costs = { 1: 15, 2: 25, 3: 35, 4: 50 };
  return costs[size] || 25;
}

3. Progress Tracking

class ArticleProgress {
  constructor(requestId) {
    this.requestId = requestId;
    this.status = "pending";
  }

  async checkStatus() {
    // Makale durumunu kontrol et
    const articles = await getMyArticles({
      requestId: this.requestId,
      pageSize: 1,
    });

    if (articles.length > 0) {
      this.status = articles[0].status;
      return this.status;
    }

    return "not_found";
  }

  async waitForCompletion(maxWaitTime = 300000) {
    // 5 dakika
    const startTime = Date.now();

    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.checkStatus();

      if (status === "completed") {
        return true;
      } else if (status === "failed") {
        throw new Error("Makale oluşturma başarısız");
      }

      // 10 saniye bekle
      await new Promise((resolve) => setTimeout(resolve, 10000));
    }

    throw new Error("Timeout: Makale oluşturma çok uzun sürdü");
  }
}

// Kullanım
const result = await createArticle(title, tone, size);
const progress = new ArticleProgress(result.data.requestId);

try {
  await progress.waitForCompletion();
  console.log("Makale hazır!");
} catch (error) {
  console.error("Makale oluşturulamadı:", error);
}

🔄 İşlem Takibi

Makale oluşturma işlemi asenkron olarak çalışır. İşlem durumunu takip etmek için:

1. Request ID'yi saklayın
2. Makalelerim endpoint'ini kullanarak durumu kontrol edin
3. Periyodik olarak status güncellemesi yapın

// Makale durumu kontrol fonksiyonu
async function checkArticleStatus(requestId) {
  const articles = await getMyArticles({
    pageSize: 50,
    durumId: null, // Tüm durumlar
  });

  const article = articles.find((a) => a.requestId === requestId);

  if (article) {
    return {
      status: article.status,
      progress: article.progress || 0,
      content: article.content,
      createdAt: article.createdAt,
    };
  }

  return null;
}

Performans İpucu

Toplu makale oluşturma ihtiyacınız varsa, tek tek makale oluşturmak yerine Toplu Makale Oluşturma endpoint'ini kullanın.

Maliyet Uyarısı

Her makale oluşturma işlemi hesabınızdan düşer. İşlem başlamadan önce mevcut bakiyenizi kontrol etmeyi unutmayın.

İşlem Süresi

Makale boyutuna göre oluşturma süresi değişir. Kısa makaleler 1-2 dakika, uzun makaleler 5-10 dakika sürebilir.