Tutorial API 2slides - Guida Completa alla Generazione di Presentazioni con AI

Benvenuti nella guida completa per l'API 2slides! Questo tutorial vi illustrerà tutto ciò che dovete sapere per integrare la generazione di presentazioni basate su AI nelle vostre applicazioni.

Panoramica

L'API 2slides vi permette di generare presentazioni professionali in modo programmatico utilizzando l'AI. Con il supporto per molteplici tipi di presentazioni, inclusi timeline, roadmap, mappe mentali e altro ancora, potete creare slide straordinarie da un semplice input testuale.

Caratteristiche Principali

• Generazione basata su AI: Crea automaticamente presentazioni professionali da testo
• Diversi Tipi di Template: Supporto per timeline, roadmap, mappe mentali, pitch deck, infografiche e altro ancora
• Supporto Multilingua: Genera contenuti in più lingue
• Ricca Libreria di Template: Accesso a centinaia di template progettati professionalmente
• Template Personalizzati: Carica e usa i tuoi template di slide personalizzati
• Ricerca template: Cerca template tramite nome, parole chiave e tag
• Opzioni di Download: Ottieni presentazioni in formato PowerPoint (.pptx)
• Monitoraggio dello Stato in Tempo Reale: Monitora l'avanzamento della generazione con gli endpoint di stato del job

Tipi di Presentazione in Evidenza

Tutti i template di presentazione sono disponibili qui: 2slides Templates. In particolare, ci sono alcuni tipi di presentazione in evidenza che funzionano molto bene per scopi e scenari specifici.

1. Slide per Timeline - Perfette per timeline di progetti ed eventi storici
2. Slide per Roadmap - Ideali per roadmap di prodotti e pianificazione di progetti
3. Slide per Mappe Mentali - Ottime per la mappatura di concetti e la struttura della conoscenza

Per Iniziare

URL di Base

Tutte le richieste API devono essere effettuate a:

https://2slides.com

Prerequisiti

1. Configurazione dell'Account: Crea un account su 2slides.com
2. Chiave API: Genera una chiave API dalla tua pagina di gestione API
3. Crediti: Assicurati di avere crediti sufficienti per la generazione di slide (10 crediti per pagina di slide)

Avvio Rapido

1. Ottieni la tua chiave API dalla pagina di gestione API
2. Cerca un tema usando l'endpoint di ricerca temi, o sfoglia i template per ottenere l'ID del tema della slide
3. Genera slide con il tuo contenuto e l'ID del tema selezionato; questo supporta sia chiamate sincrone con slide di risultato restituite, sia chiamate asincrone con ID del job restituito. Se usi una chiamata sincrona, i passaggi 4 e 5 non sono necessari.
4. Controlla lo stato del job fino al completamento; l'URL di download delle slide generate verrà fornito.
5. Scarica la tua presentazione usando l'URL di download fornito.

Autenticazione

Tutti gli endpoint API richiedono l'autenticazione tramite una chiave API. Puoi gestire le tue chiavi API tramite l'interfaccia di gestione API.

Formato della Chiave API

Le chiavi API seguono questo formato:

sk-2slides-{stringa-esadecimale-di-64-caratteri}

Metodi di Autenticazione

Header di Autorizzazione

Authorization: Bearer sk-2slides-la-tua-chiave-api-qui

Gestione delle Chiavi API

• Numero Massimo di Chiavi: Ogni utente può creare fino a 10 chiavi API
• Denominazione delle Chiavi: Dai alle tue chiavi nomi descrittivi per una facile identificazione
• Sicurezza: Mantieni le tue chiavi API al sicuro e non condividerle mai pubblicamente
• Rotazione: Ruota regolarmente le tue chiavi API per una maggiore sicurezza

⚠️ Avviso di Sicurezza Importante: La piattaforma 2slides NON memorizza le tue chiavi API in testo semplice per motivi di sicurezza. Una volta generate, devi copiare e archiviare in modo sicuro la tua chiave API immediatamente. Se perdi la tua chiave API, dovrai generarne una nuova poiché l'originale non può essere recuperata.

Endpoint API

1. Genera Slide (Fast PPT)

Genera slide (Fast PPT) da input testuale utilizzando un tema specifico.

Endpoint:

Headers:

Authorization: Bearer sk-2slides-la-tua-chiave-api-qui
Content-Type: application/json

Corpo della Richiesta:

{
  "userInput": "Il tuo contenuto di presentazione qui...",
  "themeId": "uuid-del-tema-qui",
  "responseLanguage": "Auto"
}

Parametri:

• userInput
  (obbligatorio): Il contenuto per cui vuoi generare le slide
• themeId
  (obbligatorio): ID del tema da utilizzare per la generazione delle slide. Può essere:
  • Temi pubblici dalla galleria di template
  • I tuoi temi personalizzati caricati (accessibili tramite il tuo account)
• responseLanguage
  (opzionale): Lingua per le slide generate. Usa "Auto" per il rilevamento automatico
• mode
  (opzionale): Chiamata sincrona (sync) o asincrona (async), "sync" è il valore predefinito

Lingue Disponibili:

• Auto
  - Rilevamento automatico della lingua dall'input (predefinito)
• English
  - English
• Simplified Chinese
  - 简体中文
• Traditional Chinese
  - 繁體中文
• Spanish
  - Español
• Arabic
  - العربية
• Portuguese
  - Português
• Indonesian
  - Bahasa Indonesia
• Japanese
  - 日本語
• Russian
  - Русский
• Hindi
  - हिंदी
• French
  - Français
• German
  - Deutsch
• Vietnamese
  - Tiếng Việt
• Turkish
  - Türkçe
• Polish
  - Polski
• Italian
  - Italiano
• Korean
  - 한국어

Risposta in modalità async:

{
  "success": true,
  "data": {
    "jobId": "uuid-del-job-qui",
    "status": "processing",
    "message": "Generazione slide avviata. Usa il jobId per controllare lo stato.",
    "credits": {
      "current": 150,
      "required": 30
    }
  }
}

Risposta in modalità sync:

{
  "success": true,
  "data": {
    "jobId": "1pFqIww3JjquQ1T3Ysmw1",
    "status": "success",
    "message": "Slide generate con successo",
    "downloadUrl": "https://url-prefirmato-qui",
    "createdAt": 1760347015388,
    "updatedAt": 1760347048261,
    "duration": 32694,
    "slidePageCount": 9
  }
}

2. Controlla lo Stato del Job (Fast PPT)

Controlla lo stato di un job di generazione slide (Fast PPT) e ottieni i risultati al completamento.

Endpoint:

Headers:

Authorization: Bearer sk-2slides-la-tua-chiave-api-qui

Esempi di Risposta:

In Elaborazione:

{
  "success": true,
  "data": {
    "jobId": "uuid-del-job-qui",
    "status": "processing",
    "message": "Generazione slide in corso",
    "createdAt": 1703123456789,
    "updatedAt": 1703123460000
  }
}

Successo:

{
  "success": true,
  "data": {
    "jobId": "uuid-del-job-qui",
    "status": "success",
    "message": "Slide generate con successo",
    "downloadUrl": "https://url-prefirmato-qui",
    "createdAt": 1703123456789,
    "updatedAt": 1703123500000,
    "duration": 33211,
    "slidePageCount": 3
  }
}

Fallito:

{
  "success": true,
  "data": {
    "jobId": "uuid-del-job-qui",
    "status": "failed",
    "message": "Generazione slide fallita",
    "errorMessage": "Crediti insufficienti per la generazione",
    "createdAt": 1703123456789,
    "updatedAt": 1703123460000
  }
}

3. Crea Slide Come Questa (Nano Banana Pro)

Genera slide (Nano Banana Pro) da un'immagine di riferimento. Questo endpoint utilizza la modalità sincrona e genera automaticamente un PDF quando tutte le slide sono completate.

Endpoint:

Headers:

Authorization: Bearer sk-2slides-la-tua-chiave-api-qui
Content-Type: application/json

Corpo della Richiesta:

{
  "userInput": "Il tuo contenuto di presentazione qui...",
  "referenceImageUrl": "https://example.com/immagine-di-riferimento.jpg",
  "responseLanguage": "Auto",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "page": 1
}

Parametri:

• userInput
  (obbligatorio): Il contenuto per cui vuoi generare le slide
• referenceImageUrl
  (obbligatorio): URL dell'immagine di riferimento da cui seguire lo stile di design. Supporta:
  • URL HTTP/HTTPS
  • URL di dati Base64 (data:image/...)
• responseLanguage
  (opzionale): Lingua per le slide generate. Usa "Auto" per il rilevamento automatico (predefinito: "Auto")
• aspectRatio
  (opzionale): Rapporto d'aspetto per le slide. Formato: "larghezza:altezza" (predefinito: "16:9")
• resolution
  (opzionale): Risoluzione per le immagini delle slide. Opzioni: "1K", "2K", "4K" (predefinito: "2K")
• page
  (opzionale): Numero di slide da generare. Usa 0 per il rilevamento automatico. Specifica un numero (>=1, max: 100) per forzare quel numero di slide. Predefinito: 1.
• contentDetail
  (opzionale): Livello di dettaglio del contenuto per le slide. Opzioni: "concise" (breve, focalizzato sulle parole chiave) o "standard" (completo, dettagliato). Predefinito: "concise".

Risposta:

{
  "success": true,
  "data": {
    "jobId": "uuid-del-job-qui",
    "status": "success",
    "message": "5 slide generate con successo",
    "downloadUrl": "https://url-prefirmato-al-pdf.pdf",
    "jobUrl": "https://2slides.com/workspace?jobId=uuid-del-job-qui",
    "createdAt": 1703123456789,
    "updatedAt": 1703123500000,
    "slidePageCount": 5,
    "successCount": 5,
    "failedCount": 0
  }
}

Valori di Stato:

• success
  : Tutte le slide generate con successo, PDF disponibile
• partial
  : Alcune slide non sono state generate
• failed
  : Tutte le slide non sono state generate

Nota: Questo endpoint funziona in modalità sincrona e attenderà che tutte le slide siano generate prima di restituire una risposta.

4. Cerca Temi (Fast PPT)

Cerca i temi di slide disponibili (Fast PPT) per parola chiave. Questo include sia i temi pubblici che i tuoi temi personalizzati caricati.

Endpoint:

Headers:

Authorization: Bearer sk-2slides-la-tua-chiave-api-qui

Parametri di Query:

• query
  (obbligatorio): Parola chiave da cercare nel nome, nella descrizione e nei tag del tema
• limit
  (opzionale): Numero massimo di risultati (1-100, predefinito 20)

Esempio di Richiesta:

GET /api/v1/themes/search?query=timeline&limit=10

Risposta:

{
  "success": true,
  "data": {
    "total": 25,
    "themes": [
      {
        "id": "uuid-del-tema-1",
        "name": "Modern Timeline",
        "description": "Template di timeline pulito e moderno per presentazioni di progetti",
        "tags": "timeline, modern, project, clean",
        "themeURL": "https://2slides.com/templates/st-1759917935785-nx0z6ae54"
      },
      {
        "id": "uuid-del-tema-2",
        "name": "Business Roadmap",
        "description": "Template di roadmap professionale per la pianificazione aziendale",
        "tags": "roadmap, business, planning, professional",
        "themeURL": "https://2slides.com/templates/st-1755509077270-sftfm616s"
      }
    ]
  }
}

Rate Limiting

L'API implementa il rate limiting per garantire un utilizzo equo e la stabilità del sistema. Diversi endpoint hanno limiti di frequenza diversi:

Header di Rate Limit

Quando i limiti di frequenza vengono superati, l'API restituisce una risposta

con questi header:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 6
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1703123600
Retry-After: 45

Gestione dei Rate Limit

È necessario gestire attentamente il limite di frequenza delle chiamate API; ecco un esempio in Javascript.

async function makeApiRequest(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeApiRequest(url, options); // Retry
    }
    
    return response;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Sistema di Crediti

2slides utilizza un sistema basato su crediti per la generazione di slide. Ogni pagina di slide costa 10 crediti.

Regole sui Crediti

• Nuovi Utenti: Ricevono 880 crediti gratuiti al momento della registrazione
• Costo: 10 crediti per pagina di slide (Fast PPT), 100 crediti per pagina di slide Nano Banana Pro 1K/2K, 200 crediti per pagina di slide Nano Banana Pro 4K
• Minimo: Gli utenti necessitano di almeno 10 crediti per avviare la generazione
• Addebito: I crediti vengono addebitati solo dopo una generazione riuscita
• Rimborsi: I crediti vengono rimborsati se la generazione fallisce

Controllo dei Crediti

Puoi controllare il tuo saldo crediti tramite la dashboard dell'account o esaminando le informazioni sui crediti nelle risposte API.

Acquisto di Crediti

Crediti aggiuntivi possono essere acquistati tramite la pagina dei prezzi utilizzando vari metodi di pagamento.

Esempi

Esempio di Workflow Completo

Ecco un esempio completo di generazione di slide utilizzando l'API 2slides in Javascript e Python:

const API_KEY = 'sk-2slides-la-tua-chiave-api-qui';
const BASE_URL = 'https://2slides.com';

async function generateSlides() {
  try {
    // Step 1: Search for a theme
    const themeResponse = await fetch(
      `${BASE_URL}/api/v1/themes/search?query=timeline&limit=5`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    const themeData = await themeResponse.json();
    const themeId = themeData.data.themes[0].id;
    
    // Step 2: Generate slides
    const generateResponse = await fetch(
      `${BASE_URL}/api/v1/slides/generate`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userInput: "Create a timeline for our product development: Q1 - Research and planning, Q2 - MVP development, Q3 - Beta testing, Q4 - Public launch",
          themeId: themeId,
          responseLanguage: "English",
          mode: "async"
        })
      }
    );
    
    const generateData = await generateResponse.json();
    const jobId = generateData.data.jobId;
    
    // Step 3: Poll for completion
    let jobStatus;
    do {
      await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
      
      const statusResponse = await fetch(
        `${BASE_URL}/api/v1/jobs/${jobId}`,
        {
          headers: {
            'Authorization': `Bearer ${API_KEY}`
          }
        }
      );
      
      jobStatus = await statusResponse.json();
      console.log(`Status: ${jobStatus.data.status}`);
      
    } while (jobStatus.data.status === 'processing' || jobStatus.data.status === 'pending');
    
    // Step 4: Handle result
    if (jobStatus.data.status === 'success') {
      console.log('Slides generated successfully!');
      console.log('Download URL:', jobStatus.data.downloadUrl);
      console.log('Pages generated:', jobStatus.data.slidePageCount);
      
      // Download the file
      const downloadResponse = await fetch(jobStatus.data.downloadUrl);
      const blob = await downloadResponse.blob();
      
      // Create download link
      const url = window.URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = 'presentation.pptx';
      a.click();
      window.URL.revokeObjectURL(url);
      
    } else {
      console.error('Generation failed:', jobStatus.data.errorMessage);
    }
    
  } catch (error) {
    console.error('Error:', error);
  }
}

// Run the example
generateSlides();

Esempio Python

import requests
import time
import json

API_KEY = 'sk-2slides-la-tua-chiave-api-qui'
BASE_URL = 'https://2slides.com'

def generate_slides():
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    try:
        # Step 1: Search for a theme
        theme_response = requests.get(
            f'{BASE_URL}/api/v1/themes/search',
            params={'query': 'roadmap', 'limit': 5},
            headers=headers
        )
        theme_data = theme_response.json()
        theme_id = theme_data['data']['themes'][0]['id']
        
        # Step 2: Generate slides
        generate_payload = {
            'userInput': 'Create a product roadmap for our mobile app: Phase 1 - Core features, Phase 2 - Advanced features, Phase 3 - AI integration',
            'themeId': theme_id,
            'responseLanguage': 'English',
            'mode': 'async'
        }
        
        generate_response = requests.post(
            f'{BASE_URL}/api/v1/slides/generate',
            headers=headers,
            json=generate_payload
        )
        generate_data = generate_response.json()
        job_id = generate_data['data']['jobId']
        
        # Step 3: Poll for completion
        while True:
            time.sleep(2)  # Wait 2 seconds
            
            status_response = requests.get(
                f'{BASE_URL}/api/v1/jobs/{job_id}',
                headers=headers
            )
            status_data = status_response.json()
            status = status_data['data']['status']
            
            print(f'Status: {status}')
            
            if status in ['success', 'failed']:
                break
        
        # Step 4: Handle result
        if status == 'success':
            print('Slides generated successfully!')
            print(f'Download URL: {status_data["data"]["downloadUrl"]}')
            print(f'Pages generated: {status_data["data"]["slidePageCount"]}')
            
            # Download the file
            download_response = requests.get(status_data['data']['downloadUrl'])
            with open('presentation.pptx', 'wb') as f:
                f.write(download_response.content)
            print('File downloaded as presentation.pptx')
            
        else:
            print(f'Generation failed: {status_data["data"]["errorMessage"]}')
            
    except Exception as error:
        print(f'Error: {error}')

# Run the example
generate_slides()

Esempi cURL

Cerca temi:

curl -X GET "https://2slides.com/api/v1/themes/search?query=timeline&limit=5" \
  -H "Authorization: Bearer sk-2slides-la-tua-chiave-api-qui" \
  -H "Content-Type: application/json"

Genera slide:

curl -X POST "https://2slides.com/api/v1/slides/generate" \
  -H "Authorization: Bearer sk-2slides-la-tua-chiave-api-qui" \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "Crea una timeline per le tappe fondamentali del nostro progetto",
    "themeId": "uuid-del-tema-qui",
    "responseLanguage": "English",
    "mode": "async"
  }'

Controlla lo stato del job:

curl -X GET "https://2slides.com/api/v1/jobs/uuid-del-job-qui" \
  -H "Authorization: Bearer sk-2slides-la-tua-chiave-api-qui"

Gestione degli Errori

L'API utilizza codici di stato HTTP standard e restituisce informazioni dettagliate sugli errori in formato JSON.

Risposte di Errore Comuni

400 Bad Request:

{
  "success": false,
  "error": "userInput è obbligatorio e deve essere una stringa non vuota"
}

401 Unauthorized:

{
  "success": false,
  "error": "Autenticazione richiesta"
}

403 Forbidden:

{
  "success": false,
  "error": "Accesso negato"
}

404 Not Found:

{
  "success": false,
  "error": "Tema non trovato"
}

429 Too Many Requests:

{
  "success": false,
  "error": "Limite di frequenza superato"
}

500 Internal Server Error:

{
  "success": false,
  "error": "Errore interno del server"
}

Migliori Pratiche per la Gestione degli Errori

async function handleApiRequest(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (!response.ok) {
      switch (response.status) {
        case 400:
          throw new Error(`Bad Request: ${data.error}`);
        case 401:
          throw new Error('Authentication failed. Please check your API key.');
        case 403:
          throw new Error('Access denied. You may not have permission for this resource.');
        case 404:
          throw new Error('Resource not found.');
        case 429:
          throw new Error('Rate limit exceeded. Please try again later.');
        case 500:
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(`API Error: ${data.error || 'Unknown error'}`);
      }
    }
    
    return data;
  } catch (error) {
    if (error.name === 'TypeError' && error.message.includes('fetch')) {
      throw new Error('Network error. Please check your internet connection.');
    }
    throw error;
  }
}

Migliori Pratiche

1. Sicurezza della Chiave API

• Non esporre mai le chiavi API nel codice lato client o in repository pubblici
• Usa variabili d'ambiente per archiviare le chiavi API in modo sicuro
• Ruota regolarmente le chiavi per una maggiore sicurezza
• Monitora l'utilizzo delle chiavi tramite la dashboard di gestione API
• Archivia le chiavi in modo sicuro: Ricorda che 2slides non memorizza le tue chiavi API, quindi devi mantenerle al sicuro
• Effettua il backup delle tue chiavi: Archivia le chiavi API in un gestore di password sicuro o in uno spazio di archiviazione crittografato

2. Uso Efficiente dell'API

• Memorizza nella cache i risultati della ricerca dei temi per evitare richieste ripetute
• Implementa intervalli di polling appropriati per i controlli dello stato del job (2-5 secondi)
• Gestisci i rate limit con grazia con un backoff esponenziale
• Raggruppa le operazioni quando possibile per ridurre le chiamate API

3. Gestione degli Errori

• Controlla sempre i codici di stato della risposta
• Implementa una logica di retry per i fallimenti transitori
• Registra gli errori in modo appropriato per il debug
• Fornisci messaggi di errore user-friendly

4. Ottimizzazione delle Prestazioni

• Usa intervalli di polling appropriati per evitare richieste non necessarie
• Implementa timeout delle richieste per prevenire richieste bloccate
• Memorizza nella cache i dati usati frequentemente come le informazioni sui temi
• Monitora l'utilizzo dei tuoi crediti per evitare addebiti inattesi

5. Linee Guida per i Contenuti

• Fornisci input chiari e strutturati per una migliore generazione di slide
• Usa temi appropriati per il tuo tipo di contenuto
• Specifica la lingua quando necessario per contenuti internazionali
• Mantieni il contenuto conciso per un layout ottimale delle slide

Supporto e Risorse

Documentazione e Risorse

• Documentazione API - Documentazione API interattiva e playground
• Galleria di Template - Sfoglia i template di slide disponibili
• Informazioni sui Prezzi - Pacchetti di crediti e prezzi
• Blog - Ultimi aggiornamenti e consigli

Ottenere Aiuto

• API Playground: Testa le tue chiamate API direttamente nel browser su 2slides.com/api
• Dashboard dell'Account: Gestisci l'utilizzo dei tuoi crediti su 2slides.com/account
• Supporto: Contatta il supporto tramite il sito web principale

Community e Aggiornamenti

• Aggiornamenti delle Funzionalità: Rimani aggiornato sulle nuove funzionalità e miglioramenti
• Libreria di Template: Aggiunte regolari di nuovi template professionali
• Miglioramenti API: Miglioramenti continui alle prestazioni e alle funzionalità dell'API

---

Conclusione

L'API 2slides offre un modo potente e flessibile per generare presentazioni professionali in modo programmatico. Con il suo set completo di funzionalità, la robusta gestione degli errori e l'ampia libreria di template, puoi integrare la generazione di slide basate su AI in qualsiasi applicazione o workflow.

Inizia a creare presentazioni straordinarie oggi stesso con l'API 2slides! Visita 2slides.com/api per ottenere la tua chiave API e iniziare a creare.