Ajan becerisi

# DeepManim API becerisi

Metin istemlerinden animasyonlu açıklayıcı videolar üretmek, iyileştirmek ve anlatım eklemek için DeepManim API'sini kullanabilirsiniz.

## Temel URL

```
https://api.deepmanim.com/api/v1
```

## Kimlik doğrulama

Tüm isteklerde Authorization üst bilgisinde bir API anahtarı gerekir:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## İş akışı

Tipik iş akışı şöyledir:

1. `POST /generate` ile bir metin isteminden video **oluşturun**
2. `status` değeri `"completed"` olana kadar dönen işi `GET /jobs/{job_id}` ile **sorgulayın**
3. (İsteğe bağlı ve tekrarlanabilir) `POST /improve` ile ek talimatlar vererek videoyu **iyileştirin**
4. Görsellerden memnun kaldığınızda `POST /audio` ile sesli anlatım **ekleyin**
5. Gerekirse `POST /improve-narration` ile anlatımı **iyileştirin**

Üretim ve iyileştirme çağrıları 1,5 krediden başlar ve ön ayara göre değişir. Ses ve improve-narration çağrıları 1 kredi tutar. Verileri okumak ücretsizdir.

## Uç noktalar

### POST /generate
Metin isteminden yeni bir video üretir. Sesli anlatım varsayılan olarak dâhildir.

İstek gövdesi:
```json
{
  "message": "Yerçekimini açıkla",
  "session_id": null,
  "preferred_locale": "tr"
}
```
- `message` (required): Neyin canlandırılacağını açıklayan istem.
- `session_id` (optional): Bir konuşmayı sürdürmek için mevcut bir oturum kimliği gönderin.

Yanıt:
```json
{
  "job_id": "abc-123",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /improve
Mevcut videoyu iyileştirir veya değiştirir. Ses içermez — tüm değişikliklerden sonra /audio üzerinden ayrıca ekleyin.

İstek gövdesi:
```json
{
  "session_id": "def-456",
  "message": "Daha fazla renk ekle ve animasyonu yavaşlat",
  "preferred_locale": "tr"
}
```

Yanıt:
```json
{
  "job_id": "ghi-789",
  "session_id": "def-456",
  "status": "pending"
}
```

### POST /audio
Mevcut videoya sesli anlatım ekler.

İstek gövdesi:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "tr"
}
```

### POST /improve-narration
Videodaki mevcut anlatımı iyileştirir.

İstek gövdesi:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Açıklamayı yeni başlayanlar için daha sezgisel hâle getir.",
  "preferred_locale": "tr"
}
```

### GET /jobs/{job_id}
İş durumunu sorgular. `phase` alanı ilerlemeyi gösterir: `brainstorming` → `crafting_vision` → `assembling_pieces` → `polishing` → `done`

Tamamlandığında yanıt:

Tamamlandığında yanıt:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Yerçekimini açıkla",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Açıklamayı yeni başlayanlar için daha sezgisel hâle getir."
  }
}
```

Olası `status` değerleri: `pending`, `running`, `completed`, `failed`.

### POST /jobs/{job_id}/cancel — Çalışan veya bekleyen bir işi iptal eder.

### GET /sessions — Tüm oturumlarınızı listeler.

### GET /sessions/{session_id} — Tam mesaj geçmişiyle bir oturum alır.

### DELETE /sessions/{session_id} — Bir oturumu ve tüm mesajlarını siler.

### GET /sessions/{session_id}/jobs
Bir oturumun işlerini listeler. İsteğe bağlı sorgu parametresi: `?status=completed`

### GET /messages/{message_id} — Kimliğe göre tek bir mesaj alır.

### GET /credits
Kredi bakiyesini alır: `balance`, `total_used`, `total_purchased`, `plan`.

### GET /me
Mevcut kullanıcı bilgilerini alır: `id`, `email`, `display_name`.

## Hata kodları

- `401` — Eksik veya geçersiz API anahtarı
- `402` — Yetersiz kredi
- `404` — Kaynak bulunamadı
- `400` — Geçersiz istek

## Sorgulama stratejisi

İşler genellikle 60–120 saniye sürer. `GET /jobs/{job_id}` uç noktasını 3–5 saniyede bir sorgulayın. Sıklığı ayarlamak için `estimated_time_remaining_seconds` alanını kullanın. `status` değeri `completed` veya `failed` olduğunda sorgulamayı durdurun.

## Örnek: Tam iş akışı

```python
import requests, time

API_KEY = "dm_k_YOUR_KEY"
BASE = "https://api.deepmanim.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Oluştur
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Yerçekimini açıkla",
    "preferred_locale": "tr"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

# 2. Tamamlanana kadar sorgula
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=headers).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(4)

# 3. Sonucu al
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# 4. İsteğe bağlı iyileştir
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Daha fazla renk ekle ve animasyonu yavaşlat",
    "preferred_locale": "tr"
})
# Yeni job_id değerini aynı şekilde sorgula…

# 5. İyileştirmelerden sonra ses ekle
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "tr"
})
# Yeni job_id değerini sorgula…

# 6. Anlatımın öğreticiliğini isteğe bağlı iyileştir
r = requests.post(f"{BASE}/improve-narration", headers=headers, json={
  "session_id": session_id,
  "message_id": message_id,
  "high_quality": True,
  "mode": "better_narration",
  "instruction": "Açıklamayı yeni başlayanlar için daha sezgisel hâle getir.",
  "preferred_locale": "tr"
})
# Yeni job_id değerini sorgula…
```