ה-API של Recast

ה-API של Recast יוצר מחדש סרטון שנותח, עם הליהוק שלכם. מקבלים אומדן מחיר להרצה, קונים את התוכנית שלה, מרנדרים אותה סצנה אחר סצנה, ובהרצה אינטראקטיבית בוחרים בדרך את הליהוק, את תמונות הסטילס של הסצנות ואת המוזיקה. אפשר גם לכתוב סרט כתסריט JSON ולייבא אותו, כך שהרצת Recast לא צריכה סרטון מקור בכלל. Recast הוא המנוע שמאחורי recast.nodaro.ai.

Recast רץ רק ב-Nodaro Cloud; בהתקנות באירוח עצמי הנתיבים מחזירים 404. בהתקנה באירוח עצמי, פרקו סרטון לסצנות עם רכיב ניתוח וידאו, וצרו מחדש את הסצנות שלו עם רכיב יצירת וידאו בתוך תהליך. הנתיבים מקבלים אסימון Bearer. ראו את דף ה-API אימות.

נקודות קצה

אומדן מחיר ויצירת הרצה

הרצה מתחילה ממשימת ניתוח: סרטון שרכיב ניתוח וידאו ניתח, או תסריט שיובא. קודם קבלו אומדן מחיר. הנתיב POST /v1/recast/estimate מקבל את ההגדרות שאיתן תיצרו את ההרצה ומחזיר { totalCredits, breakdown }.

אחר כך הנתיב POST /v1/recast יוצר את ההרצה וקונה את התוכנית שלה. הנתיב מחזיר { recastId }. גוף הבקשה צריך לכלול את workflowId, המזהה של תהליך שבבעלותכם שההרצה משויכת אליו. בלי השדה, הנתיב מחזיר 400 workflow_id_required; עם מזהה לא מוכר או של מישהו אחר, 404 workflow_not_found.

curl -X POST https://app.nodaro.ai/v1/recast/estimate \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "analysisJobId": "6c1e8a3f-9b2d-4f5a-8e7c-3d1b9a5f2e6c", "resolution": "720p", "interactive": true }'

curl -X POST https://app.nodaro.ai/v1/recast \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "8d3f5b7a-1c9e-4a2d-b6f8-4e2a7c9d1b3f",
    "analysisJobId": "6c1e8a3f-9b2d-4f5a-8e7c-3d1b9a5f2e6c",
    "resolution": "720p",
    "interactive": true,
    "clientCapabilities": ["sheet-gate"]
  }'

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const quote = await client.recast.estimate({ analysisJobId, resolution: '720p', interactive: true })
console.log(quote.totalCredits, quote.breakdown)

const { recastId } = await client.recast.create({
  workflowId,
  analysisJobId,
  resolution: '720p',
  interactive: true,
  clientCapabilities: ['sheet-gate'],
})

nodaro recast estimate --analysis-job <jobId> --resolution 720p --json
nodaro recast create --workflow <workflowId> --analysis-job <jobId> --resolution 720p --json

כדי להשתמש שוב באותן הגדרות רינדור, שמרו אותן כערכה מסוג recast-render. ראו בדף ה-API ערכות.

מעקב אחרי הרצה

הנתיב GET /v1/recast/:id מחזיר { status, interactive?, capabilities?, audio? }. הסטטוס עובר דרך planning, planned ו-generating, ואז completed או failed. הרצה בסטטוס planned ממתינה ל-POST /v1/recast/:id/start, שמתחיל את הרינדור ומחזיר { gvpJobId? }. נתיב ההתחלה הוא אידמפוטנטי ולא עולה שום דבר נוסף, כי האומדן של התוכנית כבר כלל את הרינדור.

curl https://app.nodaro.ai/v1/recast/2e9b4d6f-8a1c-4e3b-9f5d-7c2a4e6b8d1f \
  -H "Authorization: Bearer $NODARO_API_KEY"

curl -X POST https://app.nodaro.ai/v1/recast/2e9b4d6f-8a1c-4e3b-9f5d-7c2a4e6b8d1f/start \
  -H "Authorization: Bearer $NODARO_API_KEY"

const run = await client.recast.get(recastId)
if (run.status === 'planned') await client.recast.start(recastId)

nodaro recast status <recastId> --json
nodaro recast start <recastId>

מענה לנקודות בחירה אינטראקטיביות

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

נקודת בחירה נפתחת רק בסוגים שבקשת היצירה שלכם הצהירה עליהם ב-clientCapabilities, למשל sheet-gate. בכל נקודת בחירה אחרת ההכרעה אוטומטית, כך שלקוח אף פעם לא מקבל שאלה שהוא לא יכול לענות עליה.

עונים עם POST /v1/recast/:id/select. הבחירה חינמית.

await client.recast.resolveGate(recastId, { gate: 'cast', picks })
await client.recast.resolveGate(recastId, { gate: 'music', section: 0, musicPick: 1, finishAuto: true })

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

החלפת הפסקול או שינוי המיקס

אחרי שטייק מסתיים, אפשר להחליף את המוזיקה שלו או לשנות את האיזון בין הרצועות שלו, בלי לרנדר שוב את הסרטון. האפשרות הזו עובדת רק כשבסטטוס מופיע capabilities.audioLayers: 1 ולטייק יש מניפסט audio:

interface RecastAudioManifestV1 {
  version: 1
  revision: string
  mode: 'bed' | 'replace'
  present: { music?: true; video?: true }
  layers: { music?: { url: string }; video?: { url: string } }
  bakedEffectiveGain: { music?: number; video?: number }
  pendingRescore?: {
    jobId: string
    requestId: string
    state: 'pending' | 'running'
    expectedAudioRevision: string
    requestedEffectiveGain: { music?: number; video?: number }
  }
}

• השדה present מפרט את רצועות האודיו שיש בטייק: music, ובמצב bed גם video, האודיו המקורי של הסרטון.
• השדה layers מפרט רק את הרצועות שיש להן קובץ תצוגה מקדימה שהדפדפן יכול לנגן. רצועה שחסרה ב-layers עדיין יכולה להופיע בקובץ להורדה.
• השדה bakedEffectiveGain הוא העוצמה של כל רצועה בקובץ הנוכחי, באחוזים.
• השדה resultUrl שבסטטוס הוא כתובת ה-URL היחידה של הסרטון שתקבלו.

אומדן מחיר, ואז החלה

האומדן וההחלה מקבלים את אותה פעולה. שלחו לכל היותר החלפת מוזיקה אחת, או audioUrl או רשומה אחת או יותר ב-sections, כל אחת עם brief, ובנוסף את ה-mix המלא שאתם רוצים. גם מיקס לבד הוא בקשה תקינה.

{
  "expectedAudioRevision": "server-revision",
  "sections": [{ "index": 0, "brief": "Sparse analogue pulse" }],
  "mix": {
    "music": { "gain": 60, "muted": false },
    "video": { "gain": 85, "muted": false }
  }
}

1. אומדן מחיר. הנתיב POST /v1/recast/:id/estimate-rescore חינמי ומחזיר { credits, audioRevision, noOp }. הוא מחזיר את המחיר גם כשהיתרה שלכם נמוכה מדי.
2. החלה. הנתיב POST /v1/recast/:id/rescore מקבל את אותו גוף בקשה, ובנוסף requestId (UUID) ואת אותו expectedAudioRevision. הוא מחזיר { recastId, jobId }, או { recastId, noOp: true, audioRevision } כששום דבר לא משתנה. על פעולה שלא משנה כלום לא משוריינים קרדיטים, והיא לא יוצרת משימה.
3. מעקב. בדקו את הסטטוס מדי כמה שניות. השדה audio.pendingRescore מציג את הפעולה, נשאר גם אחרי טעינה מחדש, ונעלם כשהגרסה החדשה מתפרסמת או כשהפעולה נכשלת. בדקו שוב את הסטטוס לפני הפעולה הבאה.

ערכי gain הם אחוזים מ-0 עד 200; רצועה מושתקת נחשבת ל-0. ציינו רק רצועות שמופיעות ב-present, או מוזיקה שהבקשה הזו מוסיפה. לטייק במצב replace אין רצועת video, ואסור שהתוצאה תשאיר את כל הרצועות שקטות. השתמשו שוב ב-requestId רק כדי לנסות שוב את אותה בקשה בדיוק.

עם החלפת מוזיקה, שלחו את ה-mix המלא. אפשר להשמיט אותו רק כשהתוצאה תואמת לרמות הקבועות הרגילות: מוזיקה 35 ווידאו 100 במצב bed, או מוזיקה 100 במצב replace. בכל רמה נוכחית אחרת, הבקשה נדחית עם 409 legacy_mix_mismatch.

curl -X POST https://app.nodaro.ai/v1/recast/2e9b4d6f-8a1c-4e3b-9f5d-7c2a4e6b8d1f/rescore \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "4f6a8c1e-3b5d-4e7f-9a2c-6d8b1f3e5a7c",
    "expectedAudioRevision": "server-revision",
    "mix": { "music": { "gain": 60, "muted": false }, "video": { "gain": 85, "muted": false } }
  }'

const status = await client.recast.get(recastId)
const revision = status.audio?.revision
if (status.capabilities?.audioLayers === 1 && revision) {
  const operation = {
    expectedAudioRevision: revision,
    mix: { music: { gain: 60, muted: false }, video: { gain: 85, muted: false } },
  }
  const quote = await client.recast.estimateRescore(recastId, operation)
  if (!quote.noOp) {
    await client.recast.rescore(recastId, { ...operation, requestId: crypto.randomUUID() })
  }
}

ייבוא תסריט כסרט

אפשר לכתוב סרט כמסמך JSON, לרוב בעזרת מודל שפה, ולהריץ עליו Recast בלי סרטון מקור. שלושת הנתיבים חינמיים.

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

המסמך מורכב מהחלקים האלה:

מסמך שחורג ממגבלת ההרצה נדחה, ואף פעם לא נחתך. אל תכתבו sceneNumber, slotRefs או visualResolved: השרת גוזר אותם ומתעלם מהערכים שלכם. זו גם הסיבה שניתוח שהעתקתם מהעורך עם הכפתור העתקת ה-JSON מיובא כמו שהוא.

curl https://app.nodaro.ai/v1/video-analysis/authoring-skill \
  -H "Authorization: Bearer $NODARO_API_KEY" > recast-authoring.md

curl -X POST https://app.nodaro.ai/v1/video-analysis/import \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"script\": $(cat script.json), \"rightsAttested\": true }"

const guide = await client.recast.authoringSkill()
const check = await client.recast.validateScript(script)
if (check.valid) {
  const { jobId } = await client.recast.importScript(script, { rightsAttested: true })
}

nodaro recast skill > recast-authoring.md
nodaro recast validate --file script.json
nodaro recast import --file script.json --rights-attested --json

שימוש דרך MCP

עוזרי AI מריצים את אותו מחזור עבודה עם הכלים get_recast_authoring_skill, validate_recast_script, import_recast_script, start_recast, get_recast_status ו-resolve_recast_gate. הכלי start_recast מציג קודם את המחיר, ומוציא קרדיטים רק כשקוראים לו שוב כדי לאשר. ראו את הדף Recast דרך MCP.

שגיאות