עיון בתמיכה ובעזרה

תיעוד למפתחים

מפתחות API

ניהול אישורים לטווח ארוך שה־backend שלכם משתמש בהם לדבר עם המערכת. הרשאות לכל מפתח, מגבלות קצב, החלפה ויומן ביקורת — תיעוד מלא יגיע עם ה־REST API הציבורי.

פתיחה באפליקציהREST API

איך זה עובד

כל endpoint ציבורי מצפה לאסימון Bearer בכותרת Authorization. כל מפתח אטום, מוגדר עם הרשאות מפורשות, ומקושר לחשבון שלך.

  • הסוד המלא (ak_live_…) מוצג פעם אחת בלבד — ברגע היצירה. כדאי להעתיק מיד למנהל סודות.
  • רק SHA-256 של הסוד נשמר אצלנו, כך שגם dump של מסד הנתונים לא יחשוף את הסוד.
  • אבד מפתח? אפשר לבטל אותו מהדשבורד וליצור חדש — כמה שניות, ללא פגיעה בשאר המפתחות.
  • הדשבורד מציג כל מפתח עם קידומת מוסתרת, הרשאות, תפוגה ושדה last_used_at — קל לעקוב במבט אחד.

הרשאות

כל מפתח נושא רשימה מפורשת של פעולות מותרות. כדאי לבחור את הסט הצר ביותר שמספיק לעבודה — אם המפתח דולף, הוא יכול לעשות רק את מה שההרשאות מאפשרות.

  • profile:read — קריאת פרטי החשבון, היתרה וסיכום שימוש של 30 הימים האחרונים.
  • transcribe:read — שליפת רשימת תמלולים והורדת תמלול בודד.
  • transcribe:write — יצירת משימות תמלול חדשות מ-URL או מהעלאת קובץ.
  • subtitles:read — שליפת רשימת משימות כתוביות והורדת קובצי SRT.
  • subtitles:write — יצירת משימות כתוביות והפעלת צריבה מחדש (חינם) לאחר עריכה.
  • keys:manage — ניהול מפתחות API דרך ה-API עצמו (סבב מפתחות פרוגרמטי).

מפתח לא מסוגל להרים את ההרשאות שלו לבד. הרשאות אדמין נדחות בשקט במפתחות משתמש, גם אם הרשומה טוענת שהן קיימות.

תוקף וביטול

לכל מפתח יש חיים מוגבלים. מעקב אחר תפוגה הוא חלק מהיגיינה תקינה — סוד ארוך חיים שאיש לא זוכר עליו הוא הסוג הגרוע ביותר.

  • מפתחות משתמש חייבים לפוג תוך 365 ימים מהיום. הבורר בדשבורד אוכף את המגבלה בצד הלקוח והשרת בודק שוב בעת השליחה.
  • ביטול מפתח מיידי. הבקשה הבאה מקבלת 401 עם הודעת INVALID_API_KEY מתורגמת.
  • מפתח שבוטל ימשיך להופיע ברשימה עם חותמת revoked_at, כך שמסלול הביקורת נשמר.
  • השדות last_used_at ו-last_used_ip מתעדכנים אחרי כל קריאה מוצלחת — שימושי לזיהוי מפתח שכבר לא בשימוש וכדאי להחליף.
  • מחיקה רכה של החשבון מבטלת אוטומטית את כל המפתחות המקושרים אליו; אין יתומים נשארים.

רשימת היתרים של IP

רשימת היתרים אופציונלית לכל מפתח מגבילה את האסימון לשרת מסוים או לטווח CIDR. שילוב טוב במיוחד עם מפתחות בסביבת deploy שמיקומה ידוע ויציב.

  • בקשות מכל כתובת אחרת נדחות בשלב האימות לפני שה-handler מתחיל לרוץ — חוסך CPU ולא מגיע לנתונים.
  • אפשר להגדיר כתובות IPv4 בודדות וגם בלוקי CIDR (לדוגמה 10.0.0.0/8) — מותר לערבב.
  • רשימה ריקה משמעותה "כל כתובת מותרת" — להשאיר ריק אלא אם ידוע מאיפה מגיעה הקריאה.
  • אי-התאמה מחזירה 403 עם קוד השגיאה IP_NOT_ALLOWED והודעה מתורגמת.
  • שימושי למפתחות שמוטמעים בסביבת deploy סטטית שקשה להחליף — קיבוע ה-IP מצמצם את ההיקף אם הקובץ דולף.

שליחת מפתח ה-API בכל בקשה

כל ה-endpoints דורשים אסימון Bearer בכותרת Authorization. בקשות אנונימיות או cookie-auth מוחזרות עם 401.
import os
import httpx

API_KEY = os.environ["AICALL_API_KEY"]

# Use a long-lived client so the API key + base URL aren't repeated
# at every call site.
client = httpx.Client(
    base_url="https://aicall.co.il/api/v1",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)

# Now every request inherits auth automatically.
me = client.get("/me").json()
print(me["email"])
אפשר לרענן מפתחות בכל עת ב-/dashboard/developers/api-keys — המפתח הישן ממשיך לעבוד 24 שעות לאחר ביטול כדי לאפשר deploy בלי downtime.

מסכים קשורים באפליקציה

מפתחות API

יצירה, החלפה וביטול של מפתחות פרוגרמטיים.

תיעוד API

הפניה ל־endpoints הציבוריים הקרובים.

Webhooks

ערוץ שרת־לשרת שכבר זמין.

שאלות נוספות?

נשמח לעזור — ניתן לפנות בדוא״ל לכל שאלת אונבורדינג או אינטגרציה.