דלג לתוכן הראשי
Kolimina - עברית שנשמעת נכון

הבעות וניקוד

הבעות בתוך הטקסט - סימוני האתר בעברית ותגיות באנגלית כמו [whispers] - מה נדחה, ואיך הניקוד שלכם נשמר.

כדי לשלב הבעות בטקסט שולחים "input_format": "kolimina_markup_v1". אפשר לשלב שני סוגים: סימוני ההבעה של האתר, תווית בעברית בסוגריים עגולים כמו (לחישה) או (נרגש), ותגיות באנגלית בסוגריים מרובעים כמו [whispers], [laughs] או [excited]. את שתי הרשימות מחזיר GET /voices/{voice_id}/capabilities, בשדות expressions ו-expression_tags. תגית אחת יכולה לשלב עד שלוש תכונות, מופרדות בפסיקים: [whispering, playful]. אותיות גדולות ורווחים לא משנים.

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

כל דבר אחר בסוגריים מרובעים נדחה לפני שמשהו מחויב: הוראה לא מוכרת כמו [pirate voice] מקבלת 422 unsupported_expression, ותחביר שבור (] חסר, [], סוגריים מקוננים או שבירת שורה בתוך התגית) מקבל 422 invalid_expression_syntax. סוגריים מרובעים אף פעם לא נקראים כטקסט, אז הערה רגילה בסוגריים כותבים בסוגריים עגולים. בפורמט plain (ברירת המחדל) כל הבעה נדחית עם 422 markup_requires_markup_format.

מילים שניקדתם בעצמכם נעולות לפני כל תיקון אוטומטי, עם הבעה לידן או בלי: התהליך לעולם לא משכתב אותן.

cURL
curl -s -X POST "https://kolimina.com/api/public/v1/narrations" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: expressions-1" \
  -d '{"voice_id": "voice_…", "input_format": "kolimina_markup_v1", "sentences": [{"client_sentence_id": "opening", "text": "[excited] איזה יופי שהצטרפתם אלינו!"}, {"client_sentence_id": "aside", "text": "[whispers] ועכשיו נגלה לכם סוד קטן. (צוחק)"}]}'

תיקון משפט שיש בו הבעה

בתיקון שולחים את כל הטקסט החדש של המשפט, כולל ההבעות, באותו input_format. רק המשפט הזה נוצר מחדש, באותו קול ובאותו סגנון של הקריינות, והקובץ המלא נבנה מחדש מהקבצים של שאר המשפטים, שלא משתנים. שינוי בהבעה הוא שינוי במשפט: המשפט תמיד נוצר מחדש, ולא נלקח מהקלטה קודמת.

cURL
curl -s -X PATCH "https://kolimina.com/api/public/v1/narrations/nar_…/sentences/sent_…" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fix-aside-1" \
  -d '{"base_revision": 1, "input_format": "kolimina_markup_v1", "text": "[whispering, playful] ועכשיו נגלה לכם סוד גדול."}'

תגיות שאינן נתמכות וכשלים

תגית שנדחתה מופיעה בשמה בהודעת השגיאה, ושום דבר לא נוצר או מחויב.

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

cURL
curl -s -X POST "https://kolimina.com/api/public/v1/narrations" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: expressions-2" \
  -d '{"voice_id": "voice_…", "input_format": "kolimina_markup_v1", "text": "[pirate voice] אהוי, חברים!"}'
422 Unprocessable Entity
{"error": {"code": "unsupported_expression", "message": "\"[pirate voice]\" is not a supported expression. …", "field": "text", "request_id": "req_…"}}
GET /jobs/job_… - failed
{"job_id": "job_…", "status": "failed", "error": {"code": "expressions_unavailable", "message": "A sentence's expressions could not be voiced right now; …"}}

מה הלאה