Ujuzi wa wakala

# Ujuzi wa DeepManim API

Tumia DeepManim API kutengeneza, kuboresha na kusimulia video za maelezo yenye uhuishaji kutokana na maombi ya maandishi.

## URL ya msingi

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

## Uthibitishaji

Maombi yote yanahitaji ufunguo wa API katika kichwa cha Authorization:

```
Authorization: Bearer dm_k_YOUR_API_KEY
```

## Mtiririko wa kazi

Mtiririko wa kawaida ni huu:

1. **Tengeneza** video kutokana na ombi la maandishi kwa `POST /generate`
2. **Fuatilia** kazi iliyorejeshwa kwa `GET /jobs/{job_id}` hadi `status` iwe `"completed"`
3. **Boresha** video kwa maagizo ya ufuatiliaji kupitia `POST /improve` (hiari, inaweza kurudiwa)
4. **Ongeza sauti** ya usimulizi kupitia `POST /audio` ukiridhika na picha
5. **Boresha usimulizi** kupitia `POST /improve-narration` ikihitajika

Maombi ya kutengeneza na kuboresha huanza salio 1.5 na hutegemea mpangilio. Maombi ya sauti na improve-narration hugharimu salio 1. Kusoma data ni bure.

## Vituo vya mwisho vya API

### Tengeneza video
Tengeneza video mpya kutokana na ombi la maandishi. Usimulizi wa sauti hujumuishwa kwa chaguo-msingi.

Mwili wa ombi:
```json
{
  "message": "Eleza jinsi mvuto unavyofanya kazi",
  "session_id": null,
  "preferred_locale": "sw"
}
```
- `message` (required): maandishi ya mada unayotaka kueleza
- `session_id` (optional): kitambulisho cha kipindi cha kuendelea na mazungumzo

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

### Boresha video
Boresha au badilisha video iliyopo. Sauti haijumuishwi—iongeze kupitia `/audio` baada ya kumaliza mabadiliko.

Mwili wa ombi:
```json
{
  "session_id": "def-456",
  "message": "Fanya mandharinyuma iwe nyeusi zaidi na upunguze kasi ya uhuishaji",
  "preferred_locale": "sw"
}
```

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

### Ongeza sauti
Ongeza sauti ya usimulizi kwenye video iliyopo.

Mwili wa ombi:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": false,
  "preferred_locale": "sw"
}
```

### Boresha usimulizi
Boresha usimulizi uliopo kwenye video.

Mwili wa ombi:
```json
{
  "session_id": "def-456",
  "message_id": "msg-123",
  "high_quality": true,
  "mode": "better_narration",
  "instruction": "Fanya maelezo yaeleweke zaidi kwa wanaoanza.",
  "preferred_locale": "sw"
}
```

### Kazi
Pata hali ya kazi na matokeo yake.

Hatua za kazi zinaonyesha jinsi uzalishaji unavyoendelea.

Jibu lililokamilika:
```json
{
  "job_id": "abc-123",
  "status": "completed",
  "phase": "done",
  "estimated_time_remaining_seconds": 0,
  "result": {
    "video_url": "https://...",
    "description": "Eleza jinsi mvuto unavyofanya kazi",
    "session_id": "def-456",
    "message_id": "msg-789",
    "duration_seconds": 24.6,
    "has_audio": true,
    "follow_up": "Fanya maelezo yaeleweke zaidi kwa wanaoanza."
  }
}
```

Hali zinazowezekana ni `pending`, `running`, `completed` na `failed`.

### Ghairi kazi

### Vipindi

### Kipindi kimoja

### Futa kipindi

### Kazi za kipindi
Orodhesha kazi za kipindi; unaweza kutumia kichujio cha `?status=`.

### Ujumbe

### Salio na bei
Kila wito wa API unaounda kazi hukata salio kwenye akaunti yako.

### Akaunti yangu
Pata taarifa za mtumiaji aliyeingia.

## Majibu ya hitilafu

- Ufunguo wa API haupo au si sahihi
- Salio halitoshi
- Rasilimali haikupatikana
- Ombi si sahihi

## Ufuatiliaji

Ulizia hali ya kazi kwa vipindi hadi kazi ikamilike au ishindwe.

## Mfano kamili

```python
import requests, time

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

# Tengeneza video
r = requests.post(f"{BASE}/generate", headers=headers, json={
    "message": "Eleza jinsi mvuto unavyofanya kazi",
    "preferred_locale": "sw"
})
job_id = r.json()["job_id"]
session_id = r.json()["session_id"]

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

# Pata matokeo
video_url = job["result"]["video_url"]
message_id = job["result"]["message_id"]

# Boresha picha
r = requests.post(f"{BASE}/improve", headers=headers, json={
    "session_id": session_id,
    "message": "Fanya mandharinyuma iwe nyeusi zaidi na upunguze kasi ya uhuishaji",
    "preferred_locale": "sw"
})
# Subiri uboreshaji

# Ongeza sauti
r = requests.post(f"{BASE}/audio", headers=headers, json={
    "session_id": session_id,
    "message_id": message_id,
    "high_quality": False,
    "preferred_locale": "sw"
})
# Subiri sauti

# Boresha usimulizi
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": "Fanya maelezo yaeleweke zaidi kwa wanaoanza.",
  "preferred_locale": "sw"
})
# Subiri uboreshaji wa usimulizi
```