Dare a un assistente IA o a uno script l’accesso a un servizio a pagamento solleva due domande legittime: cosa gli impedisce di spendere senza chiedere, e cosa succede se la chiave finisce nelle mani sbagliate? La CLI e il server MCP di Yeşilçam Studios rispondono a entrambe con la stessa impostazione. Ogni operazione che spende token restituisce prima un prezzo e non addebita nulla, e ogni chiave API ha dei limiti su ciò che può fare. Questa guida spiega entrambe le cose, così puoi decidere quanta libertà dare al tuo assistente. L’installazione è spiegata nella guida all’installazione.

Perché ogni strumento a pagamento restituisce prima un preventivo?

Gli strumenti che spendono token non addebitano mai nulla alla prima chiamata. Restituiscono un preventivo contrassegnato con quote_only_nothing_charged, con le singole voci, il totale, il saldo attuale e l’indicazione se puoi permettertelo. L’assistente ha l’istruzione di mostrarti il prezzo e chiederti conferma. Solo quando sei d’accordo richiama lo stesso strumento con confirm=true, e solo allora il lavoro parte e i token vengono scalati.

In pratica la conversazione va così: chiedi un’immagine in bozza, l’assistente ti risponde con il prezzo e il saldo, tu dici di sì e lui crea l’immagine. Se dici di no, non hai speso niente.

Gli utilizzi gratuiti mensili inclusi in un piano a pagamento compaiono nel preventivo come 0 token e chiedono comunque l’approvazione, perché consumano una parte della quota.

Come funzionano le approvazioni nel terminale?

Se esegui un comando a pagamento senza opzioni aggiuntive, la CLI stampa il preventivo e chiede Spend about … tokens? [y/N]. Rispondi y per procedere. Per gli script hai tre opzioni:

  • --yes approva il prezzo del preventivo senza chiedere.
  • --max-tokens <n> rifiuta il lavoro se il preventivo supera n, anche con --yes. Usalo come limite di sicurezza in ogni script.
  • --quote mostra solo il prezzo ed esce.

Quando non c’è un terminale interattivo, o quando usi --json, un comando a pagamento senza --yes stampa il preventivo, non addebita nulla ed esce con il codice 3. Così uno script distingue "preventivo mostrato, non approvato" da un lavoro concluso. Il codice di uscita 2 significa che non hai effettuato l’accesso.

yesilcam video create "ocean waves at sunset" --tier draft --duration 5 --quote
yesilcam image "a lighthouse at dusk, 35mm film" --tier draft --aspect 16:9 --max-tokens 50000 --yes --out lighthouse.png

L’assistente ha lo stesso limite: chiedigli di restare sotto un certo numero di token e passerà max_tokens, così lo strumento rifiuta tutto ciò che costa di più.

Come funzionano prezzi e rimborsi?

I prezzi sono gli stessi dell’app, con il tuo piano applicato, e i lavori non riusciti vengono rimborsati automaticamente. yesilcam account pricing elenca i prezzi in token di ogni operazione e yesilcam account price ti dà il prezzo esatto di una singola operazione per il tuo piano. Due funzioni hanno regole di spesa proprie:

  • I video lunghi vengono addebitati capitolo per capitolo durante la produzione. Se finisci i token, la produzione si mette in pausa e la riprendi con longvideo resume.
  • Le automazioni vengono salvate con un tetto mensile. Approvare un’automazione autorizza una spesa fino a quel tetto, che non viene mai superato.

Sola lettura o Lettura e creazione?

Quando crei una chiave da Account → Sviluppatore scegli il suo accesso. Una chiave in Sola lettura vede account, saldo, prezzi, libreria e stato dei tuoi lavori, e può scaricare i risultati. Non può creare, modificare, eliminare né spendere nulla. Una chiave con Lettura e creazione può anche avviare lavori e spendere token, sempre passando per il preventivo e l’approvazione.

Il server MCP ha un interruttore separato: se lo avvii con --read-only, carica solo gli strumenti di lettura anche se la chiave potrebbe fare di più. Usa una chiave in sola lettura per script di report e dashboard, e una chiave di creazione solo dove deve davvero essere prodotto qualcosa.

Cosa non può mai fare una chiave API?

Alcune azioni restano nell’app web, qualunque sia l’accesso della chiave:

  • eliminare l’account o cambiarne password o email;
  • pagare, acquistare token o piani, o attivare le ricariche automatiche per le automazioni;
  • creare o revocare chiavi API;
  • collegare account social.

Quindi una chiave finita nelle mani sbagliate può al massimo spendere i token già presenti nel tuo saldo, passando dagli stessi preventivi, e non può né bloccarti fuori né comprarne altri.

Come vengono conservate le chiavi e come ne revoco una?

Sul tuo computer la chiave è salvata in ~/.config/yesilcam/config.json, leggibile solo dal tuo utente, e non viene mai stampata. Da parte nostra conserviamo solo un’impronta sicura della chiave, non la chiave stessa: per questo viene mostrata una sola volta. Ogni chiave può scadere dopo 30 giorni, 90 giorni o 1 anno, oppure mai. Se pensi che una chiave sia stata esposta, revocala da Account → Sviluppatore e creane una nuova. yesilcam logout rimuove la chiave solo da un computer; la chiave in sé resta valida finché non scade o non viene revocata.

E la privacy e la sicurezza?

  • I tuoi contenuti sono privati. I link ai tuoi file sono firmati e scadono dopo qualche ora; scaricando tramite gli strumenti vengono rinnovati. Un link pubblico o un post su The Wall passano da una richiesta di condivisione, che può richiedere un’approvazione.
  • Persone e personaggi. I personaggi sono sempre adulti e non si possono usare personaggi pubblici reali. La tua foto o il tuo video si usano solo con il tuo consenso esplicito (photo_consent, video_consent) e dopo un controllo di sicurezza.
  • Piani. Alcune funzioni richiedono Basic o Pro, per esempio i livelli cinema, Story to Film e Flow (Pro), i video oltre 30 secondi (Basic) o oltre 60 secondi (Pro) e le automazioni (Basic). Gli strumenti te lo dicono in parole semplici.

Buone abitudini con un assistente

  • Digli il tuo budget all’inizio: "Chiedimi prima di qualsiasi cosa sopra i 100.000 token."
  • Esplora al livello bozza, poi produci a un livello superiore solo quello che tieni.
  • Chiedi il saldo all’inizio e alla fine di una sessione.
  • Dai a ogni computer o server una chiave sua, con la validità più breve che funzioni, così puoi revocarne una senza toccare le altre.

Domande frequenti

L’assistente può approvare un preventivo da solo? Gli strumenti sono costruiti in modo che debba richiamarli con l’approvazione, e il server gli dà l’istruzione di chiederti prima. Per tutto ciò che costa token mantieni una risposta umana nel giro, e usa una chiave in sola lettura dove non si deve spendere niente.

Perché un utilizzo gratuito mensile chiede comunque l’approvazione? Perché consuma una parte della quota del tuo piano. Il preventivo mostra 0 token così sai che dal saldo non viene scalato nulla.

Una chiave può comprare token quando il saldo finisce? No. L’acquisto di token, piani e ricariche automatiche è possibile solo nell’app web.