Dokumentáció: Kreditek és korlátok
Fejlesztői dokumentáció
Kreditek, hibák és korlátok
Mennyibe kerül egy API-hívás, hogyan kérj árajánlatot költés előtt, milyen hibakódokat kaphatsz, és mik a sebességkorlátok.
Kreditek és árak
Az API, az MCP és a CLI ugyanabból a kreditegyenlegből von le, ugyanazon az áron, mint a web – nincs külön API-ár vagy felár. A csomagokat és a kreditcsomagokat az Árak oldalon találod.
- Az API a pénzt egész millikreditben adja meg: 1 kredit = 1000 mc. A CLI kreditben írja ki.
- Az aktuális árakat mindig a szervertől kérdezd:
fotoai models,GET /api/v1/models(teljes ártábla) vagy az MCPlist_modelseszköze („-tól” ár). Ne írj árat a kódodba. - Generáláskor a szerver lefoglalja az árat; sikeres eredménynél levonja, hibánál, elutasításnál és lemondásnál felszabadítja. Kreditet csak sikeres generálás visz.
Árajánlat költés előtt
Minden felületen kérhetsz árat anélkül, hogy költenél: POST /api/v1/quote, az MCP quote eszköze, vagy a CLI --dry-run kapcsolója és a fotoai quote parancs.
fotoai image "portré egy kávézóban" -a 3:4 --dry-run
fotoai quote video "lassú séta" -m <modell-id>AI-ügynököknek
Egy ügynök ugyanúgy költ, mint a felhasználó. Mindig kérj előbb árat, mutasd meg a felhasználónak, és csak a jóváhagyása után generálj. Soha ne generálj ciklusban, és ne ismételj meg automatikusan egy generálást a felhasználó engedélye nélkül.
A REST API-ban a quote_id (vagy max_millicredits) felső korlát: ha a tényleges ár ennél magasabb lenne, a szerver 409 PRICE_CHANGED-dzsel elutasítja a kérést, és nem foglal le semmit. A CLI mindig így küldi a generálást.
Ki használhatja
| Hozzáférés | Csomag | Ellenőrzés |
|---|---|---|
| Személyes API-kulcs, MCP, CLI | Pro | Kulcs létrehozásakor és minden kérésnél – a Pro lejártával a kulcs azonnal leáll. |
| OAuth-partneralkalmazás (Posty) | Bármely csomag, a regisztrációs kreditekkel is | A kredit dönti el, mi generálható; a modellek csomagkorlátai ugyanúgy érvényesek, mint a weben. |
Hibakódok
A hibák formája { "error": { "code": "…", "message": "…", "details": { … } } }. A code a szerződés, a message magyar, embereknek szól. Az OAuth-végpontok (/oauth/token, /oauth/revoke) az RFC 6749 szerinti { "error": "invalid_grant" } formát adják.
| Kód | HTTP | Mit jelent |
|---|---|---|
VALIDATION | 400 | Hibás kérés: details.issues vagy details.param / reason. |
UNAUTHENTICATED | 401 | Hiányzó, ismeretlen, lejárt vagy visszavont token / kulcs. |
PAYWALL | 402 | Csomagkorlát: details.requiredTier (modell, felbontás, hossz), vagy a kulcshoz Pro kell (details.requiredPerk: "mcp"). Mindig van details.plans_url. |
INSUFFICIENT_CREDITS | 402 | Nincs elég kredit: details.required, details.available, details.topup_url. |
FORBIDDEN | 403 | Hiányzó scope, session_only útvonal, tartozás (DEBT) vagy túl sok biztonsági elutasítás (POLICY). |
NOT_FOUND | 404 | Nem létezik – vagy más felhasználóé. |
PRICE_CHANGED | 409 | Az ár a jóváhagyott korlát fölé ment, vagy változott a katalógus: kérj új árajánlatot. |
RATE_LIMITED | 429 | Sebességkorlát: Retry-After, details.scope, details.resetAt. |
CONCURRENCY_LIMIT | 429 | A csomagod párhuzamos helyei foglaltak: Retry-After: 15, várj és próbáld újra. |
DAILY_CAP | 429 | Napi keret: Retry-After 00:00 UTC-ig. |
SERVICE_PAUSED | 503 | A szolgáltatás átmenetileg szünetel. |
MODEL_UNAVAILABLE | 503 | A modell ki van kapcsolva vagy szolgáltatói hibák miatt szünetel. |
PROVIDER_ERROR | 503 | A szolgáltató hibázott az indításkor; nem vontunk le kreditet. |
Egy már elfogadott, később elbukó feladat nem HTTP-hiba: az állapota failed vagy rejected lesz error.code-dal (például PROVIDER_ERROR, REJECTED_SAFETY), és a lefoglalt kredit felszabadul.
Sebességkorlátok
| Korlát | Érték | Hatókör |
|---|---|---|
| Kérések (API-kulcs, MCP, CLI) | 60 / perc | kulcsonként |
| Kérések (OAuth-partner, v1) | 240 / perc | engedélyenként |
| Generálás indítása (kulcs / engedély) | 30 / 10 perc | kulcsonként vagy engedélyenként; a csomagfuttatás egynek számít |
| Generálás (minden csatorna együtt) | 20 / 10 perc | felhasználónként – ez a meghatározó |
| Generálás IP-címenként | 40 / 10 perc | OAuth-partnerekre nem vonatkozik |
| Párhuzamos feladatok | Free 1 kép / 1 videó · Alap 2 / 1 · Plusz 4 / 2 · Pro 8 / 4 | felhasználónként; a csomagfuttatás egy helyet foglal |
| Feltöltés | 120 / 10 perc | felhasználónként, a webbel közösen |
A 429 válasz mindig tartalmaz Retry-After fejlécet: annyi másodperc múlva próbáld újra. A gyakorlatban egy sorozatot a csomagod párhuzamos helyei lassítanak (CONCURRENCY_LIMIT) – ilyenkor tedd sorba a kéréseket.