first commit
This commit is contained in:
194
docs/API.md
Normal file
194
docs/API.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# BackPRO - Integracje API
|
||||
|
||||
## 1. OpenAI API (Generowanie artykułów)
|
||||
|
||||
### Endpoint
|
||||
`POST https://api.openai.com/v1/chat/completions`
|
||||
|
||||
### Konfiguracja
|
||||
- **Model:** konfigurowalny w ustawieniach (domyślnie `gpt-4o`)
|
||||
- **Klucz API:** przechowywany w tabeli `settings`
|
||||
|
||||
### Struktura zapytania
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-4o",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "Jesteś doświadczonym copywriterem SEO. Pisz artykuły w języku polskim, optymalizowane pod SEO. Artykuł powinien mieć {min_words}-{max_words} słów, zawierać nagłówki H2 i H3, być angażujący i merytoryczny. Formatuj treść w HTML (bez tagów <html>, <body>, <head>). Zwróć odpowiedź w formacie JSON: {\"title\": \"tytuł\", \"content\": \"treść HTML\"}"
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Napisz artykuł na temat: {topic_name}\nWytyczne: {topic_description}\n\nWAŻNE - NIE pisz o następujących tematach, bo artykuły o nich już istnieją na stronie:\n{lista_istniejących_tytułów}"
|
||||
}
|
||||
],
|
||||
"temperature": 0.8,
|
||||
"max_tokens": 4000,
|
||||
"response_format": { "type": "json_object" }
|
||||
}
|
||||
```
|
||||
|
||||
### Obsługa odpowiedzi
|
||||
1. Parsowanie JSON z odpowiedzi
|
||||
2. Walidacja - czy zawiera `title` i `content`
|
||||
3. Sanityzacja HTML treści
|
||||
4. Zapis do tabeli `articles`
|
||||
|
||||
### Obsługa błędów
|
||||
- Rate limiting (429) → retry z exponential backoff
|
||||
- Timeout → zapis status=failed z error_message
|
||||
- Nieprawidłowy JSON → próba ekstrakcji treści z raw response
|
||||
|
||||
### Klasa: `OpenAIService`
|
||||
```php
|
||||
class OpenAIService {
|
||||
public function generateArticle(
|
||||
string $topicName,
|
||||
string $topicDescription,
|
||||
array $existingTitles
|
||||
): array // ['title' => '', 'content' => '']
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. WordPress REST API (Publikacja)
|
||||
|
||||
### Wymagania po stronie WordPressa
|
||||
- WordPress 4.7+ (REST API wbudowane)
|
||||
- Utworzony użytkownik z rolą **Author** lub **Editor**
|
||||
- Wygenerowane **Application Password** (WP 5.6+: Użytkownicy → Profil → Application Passwords)
|
||||
|
||||
### Autentykacja
|
||||
HTTP Basic Auth z Application Password:
|
||||
```
|
||||
Authorization: Basic base64(username:application_password)
|
||||
```
|
||||
|
||||
### Używane endpointy
|
||||
|
||||
#### Test połączenia
|
||||
```
|
||||
GET {site_url}/wp-json/wp/v2/posts?per_page=1
|
||||
```
|
||||
|
||||
#### Pobieranie kategorii
|
||||
```
|
||||
GET {site_url}/wp-json/wp/v2/categories?per_page=100
|
||||
```
|
||||
|
||||
#### Upload obrazka (media)
|
||||
```
|
||||
POST {site_url}/wp-json/wp/v2/media
|
||||
Content-Type: image/jpeg
|
||||
Content-Disposition: attachment; filename="article-image.jpg"
|
||||
Body: [binary image data]
|
||||
```
|
||||
Zwraca `id` mediów do użycia jako `featured_media`.
|
||||
|
||||
#### Tworzenie posta
|
||||
```json
|
||||
POST {site_url}/wp-json/wp/v2/posts
|
||||
{
|
||||
"title": "Tytuł artykułu",
|
||||
"content": "<p>Treść HTML...</p>",
|
||||
"status": "publish",
|
||||
"categories": [15],
|
||||
"featured_media": 42
|
||||
}
|
||||
```
|
||||
|
||||
### Klasa: `WordPressService`
|
||||
```php
|
||||
class WordPressService {
|
||||
public function testConnection(Site $site): bool
|
||||
public function getCategories(Site $site): array
|
||||
public function uploadMedia(Site $site, string $imageData, string $filename): int
|
||||
public function createPost(
|
||||
Site $site,
|
||||
string $title,
|
||||
string $content,
|
||||
?int $categoryId = null,
|
||||
?int $mediaId = null
|
||||
): int // zwraca wp_post_id
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Freepik API (Obrazki)
|
||||
|
||||
### AI Image Generation
|
||||
`POST https://api.freepik.com/v1/ai/text-to-image`
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Professional blog header image about {topic}: {article_title}",
|
||||
"negative_prompt": "text, watermark, logo",
|
||||
"image": {
|
||||
"size": "landscape_16_9"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Headers:**
|
||||
```
|
||||
x-freepik-api-key: {api_key}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Alternatywy (fallback)
|
||||
|
||||
#### Unsplash API (darmowe stocki)
|
||||
```
|
||||
GET https://api.unsplash.com/search/photos?query={topic_keywords}&orientation=landscape
|
||||
Authorization: Client-ID {access_key}
|
||||
```
|
||||
|
||||
#### Pexels API (darmowe stocki)
|
||||
```
|
||||
GET https://api.pexels.com/v1/search?query={topic_keywords}&orientation=landscape&per_page=1
|
||||
Authorization: {api_key}
|
||||
```
|
||||
|
||||
### Klasa: `ImageService`
|
||||
```php
|
||||
class ImageService {
|
||||
public function generate(string $articleTitle, string $topicName): array
|
||||
// Zwraca ['data' => binary, 'filename' => 'image.jpg', 'mime' => 'image/jpeg']
|
||||
|
||||
// Wewnętrznie wybiera provider na podstawie ustawienia 'image_provider':
|
||||
private function generateFreepik(string $prompt): array
|
||||
private function searchUnsplash(string $query): array
|
||||
private function searchPexels(string $query): array
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Konfiguracja API w panelu
|
||||
|
||||
Ustawienia przechowywane w tabeli `settings`:
|
||||
|
||||
| Klucz | Opis | Przykład |
|
||||
|-------|------|---------|
|
||||
| openai_api_key | Klucz API OpenAI | sk-proj-... |
|
||||
| openai_model | Model do artykułów | gpt-4o |
|
||||
| freepik_api_key | Klucz API Freepik | fpk-... |
|
||||
| unsplash_api_key | Klucz API Unsplash (opcjonalnie) | ... |
|
||||
| pexels_api_key | Klucz API Pexels (opcjonalnie) | ... |
|
||||
| image_provider | Aktywny provider obrazków | freepik / unsplash / pexels |
|
||||
| article_min_words | Min. słów w artykule | 800 |
|
||||
| article_max_words | Max. słów w artykule | 1200 |
|
||||
|
||||
## 5. Limity i koszty (orientacyjne)
|
||||
|
||||
| API | Limit | Koszt |
|
||||
|-----|-------|-------|
|
||||
| OpenAI GPT-4o | Brak limitu (pay-per-use) | ~$0.01-0.03 / artykuł |
|
||||
| OpenAI GPT-4o-mini | Brak limitu | ~$0.001-0.003 / artykuł |
|
||||
| Freepik AI | Zależy od planu | Od darmowego (ograniczony) |
|
||||
| Unsplash | 50 req/h (demo) | Darmowe |
|
||||
| Pexels | 200 req/h | Darmowe |
|
||||
Reference in New Issue
Block a user