kapp.ai

Génération par IA : texte enrichi, traduction, correction, modération, sons, contenu structuré et images.

Service partagé appli + widget, mais toutes les méthodes ne sont pas ouvertes à tous les contextes : voir la colonne « Accès ». Un refus de contexte répond en 403.

Quand l'utiliser (vs alternative)

• enrich() / translate() / proofread() : transformer un texte avant de l'afficher ou le lire en TTS.
• moderate() : filtrer une saisie de viewer avant de la diffuser.
• sound() : générer un effet sonore depuis une description.
• generate() : obtenir un contenu structuré dans une appli.

Méthodes

Méthode	Retour	Accès et scope d'appli
enrich(text: string)	Promise<string> : texte réécrit	Appli et widget, sans scope
translate(text, language)	Promise<string>	Appli et widget ; appli : ai:trad
proofread(text, additional_instructions = null)	Promise<{ text: string }>	Appli et widget ; appli : ai:proofread
moderate(message: string)	Promise<boolean> : true si le message est problématique	Appli et widget ; appli : ai:moderate
sound(prompt, duration = null, prompt_influence = null, traduce = true, options = {})	Promise<string> : URL du son	Appli et widget ; appli : ai:sound
generate(prompt, format = null)	Promise<Record<string, any>>	Applis uniquement ; scope ai:generator
draw(prompt, image_urls = null, options = {})	Promise<string | null> : URL de l'image	Appli et widget ; appli : ai:draw

Toutes ces méthodes sont async. Un widget ne déclare pas de scopes ; il reste soumis aux contrôles de contexte ci-dessus. Les quotas horaires du channel s'appliquent : prévoir l'échec.

enrich() reformule le texte avec le ton et le style du bot. Les consignes de réécriture se placent entre accolades {…} et sont séparées du texte envoyé au modèle. Le résultat est le texte produit par le modèle.

Le scope ai:draw est exigé dès le contrat de manifeste 4, attribué par le serveur aux nouvelles versions d'appli. Les versions antérieures restent exemptées ; déclarer le scope dans infos.json.scopes lors de la prochaine nouvelle version, y compris pour une appli officielle. Les widgets ne déclarent pas de scopes applicatifs. La réserve IA et les limites de requêtes du channel s'appliquent dans tous les cas.

draw() génère une image sans référence ou modifie/compose des images à partir des URL fournies. Transmettre les URL complètes, y compris https://, sans les préfixer. La génération et l'édition partagent le même modèle d'image ; leur résultat reste une URL de média. L'ancien point d'entrée officiel advanced-image utilise ce même moteur.

Sauvegarde optionnelle des images et sons

draw() et sound() acceptent un dernier argument GeneratedMediaOptions : save vaut false par défaut. L'URL permet toujours d'afficher ou de lire le résultat pendant sept jours, mais aucun fichier n'apparaît dans les médias du channel.

Avec {save: true, title: 'Décor spatial'}, le backend enregistre directement un seul média généré pour sept jours. Le titre est obligatoire ; le nom final est slug-app — titre. Le slug provient de l'appli authentifiée, jamais d'un paramètre client. Pour un widget, le préfixe est widget-ID. L'identifiant de stockage reste indépendant du nom.

Le titre est nettoyé des espaces périphériques et doit être non vide, sans séparateur de chemin ni caractère de contrôle. Le nom complet, préfixe compris, est limité à 255 caractères. Un titre invalide ou absent avec save: true est refusé en 422 avant génération. Les types incorrects sont refusés en 400. Une appli doit disposer de file:write pour sauvegarder, selon les règles habituelles de son manifeste ; ce scope n'est pas requis avec save: false.

Pour demander une sauvegarde sans image de référence : kapp.ai.draw(prompt, null, {save: true, title}). Pour un son : kapp.ai.sound(prompt, duration, prompt_influence, traduce, {save: true, title}). Les anciennes signatures restent valides.

Ne pas réuploader ce résultat pour le sauvegarder une seconde fois. medias.upload() reste disponible, avec son comportement inchangé, pour les uploads explicites. Le même contrat de sauvegarde existe pour textToSpeech.speech() et generate().

Les routes /ai/leonardo/leonardo/v1, /ai/leonardo/generation/v1, /ai/generator/v1 et /ai/advanced-generator/v1 sont retirées : elles répondent 410 avec error: "ai_endpoint_retired", sans lancer de génération. Le client HTTP du SDK rejette la Promise avec cette erreur. Utiliser draw() pour les images et generate() (route /ai/generator/v2) pour le contenu JSON.

Exemple (V2)

// Corps d'exécution d'un widget ou script métier d'une appli, après démarrage du SDK.
const base = 'Merci pour le follow !';
let message = base;
try {
    message = await kapp.ai.enrich(base);
} catch (error) {
    console.warn('Enrichissement indisponible, texte d’origine conservé', error?.status);
}
await kapp.announces.screenNotification(message, { duration: 5 });

Pièges

• draw() peut renvoyer null si aucune URL n'est fournie. Les refus de permission (403), réserve épuisée (429) et erreurs réseau/serveur rejettent la Promise : prévoir try/catch et un visuel de repli.
• La génération est lente (plusieurs secondes) : await obligatoire, et garder un texte ou un visuel de repli.
• sound() renvoie une URL : pour l'entendre, await kapp.medias.playAudio(url, volume).
• Une absence de scope dans une appli répond en 403 : voir permissions.