Tutorial da API 2slides - Guia Completo para Geração de Apresentações com IA

Bem-vindo ao guia completo da API 2slides! Este tutorial irá guiá-lo por tudo o que precisa saber para integrar a geração de apresentações com IA nas suas aplicações.

Visão Geral

A API 2slides permite gerar apresentações profissionais programaticamente usando IA. Com suporte para múltiplos tipos de apresentação, incluindo cronogramas, roadmaps, mapas mentais e muito mais, pode criar slides impressionantes a partir de uma simples entrada de texto.

Principais Recursos

• Geração com IA: Crie apresentações profissionais automaticamente a partir de texto
• Múltiplos Tipos de Modelos: Suporte para cronogramas, roadmaps, mapas mentais, pitch decks, infográficos e muito mais
• Suporte Multilíngue: Gere conteúdo em vários idiomas
• Biblioteca Rica de Modelos: Acesso a centenas de modelos profissionalmente desenhados
• Modelos Personalizados: Carregue e use os seus próprios modelos de slides personalizados
• Pesquisar modelos: Pesquise modelos por nome, palavras-chave e tags
• Opções de Download: Obtenha apresentações no formato PowerPoint (.pptx)
• Monitorização de Status em Tempo Real: Monitorize o progresso da geração com endpoints de status de trabalho

Tipos de Apresentação em Destaque

Todos os modelos de apresentação estão disponíveis aqui: 2slides Templates. Especificamente, existem alguns tipos de apresentação em destaque que funcionam muito bem para propósitos e cenários específicos.

1. Slides de Cronograma - Perfeitos para cronogramas de projetos e eventos históricos
2. Slides de Roadmap - Ideais para roadmaps de produtos e planeamento de projetos
3. Slides de Mapa Mental - Ótimos para mapeamento de conceitos e estrutura de conhecimento

Primeiros Passos

URL Base

Todos os pedidos da API devem ser feitos para:

https://2slides.com

Pré-requisitos

1. Configuração da Conta: Crie uma conta em 2slides.com
2. Chave da API: Gere uma chave da API na sua página de gestão da API
3. Créditos: Certifique-se de que tem créditos suficientes para a geração de slides (10 créditos por página de slide)

Início Rápido

1. Obtenha a sua chave da API na página de gestão da API
2. Procure um tema usando o endpoint de pesquisa de temas, ou navegue pelos modelos para obter o ID do tema do slide
3. Gere slides com o seu conteúdo e o ID do tema selecionado. Isto suporta tanto chamadas síncronas com slides de resultado devolvidos, quanto chamadas assíncronas com um ID de trabalho devolvido. Se usar chamadas síncronas, os passos 4 e 5 não são necessários.
4. Verifique o status do trabalho até à conclusão; o URL de download dos slides gerados será fornecido.
5. Faça o download da sua apresentação usando o URL de download fornecido.

Autenticação

Todos os endpoints da API exigem autenticação usando uma chave da API. Pode gerir as suas chaves da API através da interface de gestão da API.

Formato da Chave da API

As chaves da API seguem este formato:

sk-2slides-{64-character-hex-string}

Métodos de Autenticação

Cabeçalho de Autorização

Authorization: Bearer sk-2slides-your-api-key-here

Gestão de Chaves da API

• Máximo de Chaves: Cada utilizador pode criar até 10 chaves da API
• Nomenclatura das Chaves: Dê nomes descritivos às suas chaves para fácil identificação
• Segurança: Mantenha as suas chaves da API seguras e nunca as partilhe publicamente
• Rotação: Rode as suas chaves da API regularmente para maior segurança

⚠️ Aviso de Segurança Importante: A plataforma 2slides NÃO armazena as suas chaves da API em texto simples por razões de segurança. Uma vez gerada, deve copiar e armazenar a sua chave da API de forma segura imediatamente. Se perder a sua chave da API, terá de gerar uma nova, pois a original não pode ser recuperada.

Endpoints da API

1. Gerar Slides (Fast PPT)

Gere slides (Fast PPT) a partir de uma entrada de texto usando um tema específico.

Endpoint:

Cabeçalhos:

Authorization: Bearer sk-2slides-your-api-key-here
Content-Type: application/json

Corpo do Pedido:

{
  "userInput": "Your presentation content here...",
  "themeId": "theme-uuid-here",
  "responseLanguage": "Auto"
}

Parâmetros:

• userInput
  (obrigatório): O conteúdo para o qual deseja gerar slides
• themeId
  (obrigatório): ID do tema a usar para a geração de slides. Pode ser:
  • Temas públicos da galeria de modelos
  • Os seus próprios temas personalizados carregados (acessíveis através da sua conta)
• responseLanguage
  (opcional): Idioma para os slides gerados. Use "Auto" para deteção automática
• mode
  (opcional): Chamada síncrona (sync) ou assíncrona (async), "sync" é o padrão

Idiomas Disponíveis:

• Auto
  - Deteção automática do idioma a partir da entrada (padrão)
• English
  - Inglês
• Simplified Chinese
  - 简体中文
• Traditional Chinese
  - 繁體中文
• Spanish
  - Espanhol
• Arabic
  - Árabe
• Portuguese
  - Português
• Indonesian
  - Indonésio
• Japanese
  - Japonês
• Russian
  - Russo
• Hindi
  - Hindi
• French
  - Francês
• German
  - Alemão
• Vietnamese
  - Vietnamita
• Turkish
  - Turco
• Polish
  - Polaco
• Italian
  - Italiano
• Korean
  - Coreano

Resposta em modo assíncrono:

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "processing",
    "message": "Slides generation started. Use the jobId to check status.",
    "credits": {
      "current": 150,
      "required": 30
    }
  }
}

Resposta em modo síncrono:

{
  "success": true,
  "data": {
    "jobId": "1pFqIww3JjquQ1T3Ysmw1",
    "status": "success",
    "message": "Slides generated successfully",
    "downloadUrl": "https://presigned-url-here",
    "createdAt": 1760347015388,
    "updatedAt": 1760347048261,
    "duration": 32694,
    "slidePageCount": 9
  }
}

2. Verificar Status do Trabalho (Fast PPT)

Verifique o status de um trabalho de geração de slides (Fast PPT) e obtenha os resultados quando concluído.

Endpoint:

Cabeçalhos:

Authorization: Bearer sk-2slides-your-api-key-here

Exemplos de Resposta:

Em Processamento:

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "processing",
    "message": "Slides generation in progress",
    "createdAt": 1703123456789,
    "updatedAt": 1703123460000
  }
}

Sucesso:

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "success",
    "message": "Slides generated successfully",
    "downloadUrl": "https://presigned-url-here",
    "createdAt": 1703123456789,
    "updatedAt": 1703123500000,
    "duration": 33211,
    "slidePageCount": 3
  }
}

Falha:

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "failed",
    "message": "Slides generation failed",
    "errorMessage": "Insufficient credits for generation",
    "createdAt": 1703123456789,
    "updatedAt": 1703123460000
  }
}

3. Criar Slides Como Este (Nano Banana Pro)

Gere slides (Nano Banana Pro) a partir de uma imagem de referência. Este endpoint usa o modo síncrono e gera automaticamente um PDF quando todos os slides são concluídos.

Endpoint:

Cabeçalhos:

Authorization: Bearer sk-2slides-your-api-key-here
Content-Type: application/json

Corpo do Pedido:

{
  "userInput": "Your presentation content here...",
  "referenceImageUrl": "https://example.com/reference-image.jpg",
  "responseLanguage": "Auto",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "page": 1
}

Parâmetros:

• userInput
  (obrigatório): O conteúdo para o qual deseja gerar slides
• referenceImageUrl
  (obrigatório): URL da imagem de referência para seguir o estilo de design. Suporta:
  • URLs HTTP/HTTPS
  • URLs de dados Base64 (data:image/...)
• responseLanguage
  (opcional): Idioma para os slides gerados. Use "Auto" para deteção automática (padrão: "Auto")
• aspectRatio
  (opcional): Proporção para os slides. Formato: "largura:altura" (padrão: "16:9")
• resolution
  (opcional): Resolução para imagens de slides. Opções: "1K", "2K", "4K" (padrão: "2K")
• page
  (opcional): Número de slides a gerar. Use 0 para deteção automática. Especifique um número (>=1, máx: 100) para forçar essa quantidade de slides. Padrão: 1.
• contentDetail
  (opcional): Nível de detalhe do conteúdo para os slides. Opções: "concise" (breve, focado em palavras-chave) ou "standard" (abrangente, detalhado). Padrão: "concise".

Resposta:

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "success",
    "message": "Successfully generated 5 slides",
    "downloadUrl": "https://presigned-url-to-pdf.pdf",
    "jobUrl": "https://2slides.com/workspace?jobId=job-uuid-here",
    "createdAt": 1703123456789,
    "updatedAt": 1703123500000,
    "slidePageCount": 5,
    "successCount": 5,
    "failedCount": 0
  }
}

Valores de Status:

• success
  : Todos os slides gerados com sucesso, PDF disponível
• partial
  : Alguns slides falharam na geração
• failed
  : Todos os slides falharam na geração

Nota: Este endpoint funciona em modo síncrono e aguardará que todos os slides sejam gerados antes de retornar.

4. Pesquisar Temas (Fast PPT)

Pesquise temas de slides disponíveis (Fast PPT) por palavra-chave. Isto inclui tanto temas públicos quanto os seus próprios temas personalizados carregados.

Endpoint:

Cabeçalhos:

Authorization: Bearer sk-2slides-your-api-key-here

Parâmetros de Consulta:

• query
  (obrigatório): Palavra-chave para pesquisar no nome do tema, descrição e tags
• limit
  (opcional): Número máximo de resultados (1-100, padrão 20)

Exemplo de Pedido:

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

Resposta:

{
  "success": true,
  "data": {
    "total": 25,
    "themes": [
      {
        "id": "theme-uuid-1",
        "name": "Modern Timeline",
        "description": "Clean and modern timeline template for project presentations",
        "tags": "timeline, modern, project, clean",
        "themeURL": "https://2slides.com/templates/st-1759917935785-nx0z6ae54"
      },
      {
        "id": "theme-uuid-2",
        "name": "Business Roadmap",
        "description": "Professional roadmap template for business planning",
        "tags": "roadmap, business, planning, professional",
        "themeURL": "https://2slides.com/templates/st-1755509077270-sftfm616s"
      }
    ]
  }
}

Limitação de Taxa

A API implementa limitação de taxa para garantir o uso justo e a estabilidade do sistema. Diferentes endpoints têm diferentes limites de taxa:

Cabeçalhos de Limite de Taxa

Quando os limites de taxa são excedidos, a API retorna uma resposta

com estes cabeçalhos:

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

Lidar com Limites de Taxa

É necessário lidar com o limite de taxa de chamadas da API com cuidado; aqui está um exemplo em 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 de Créditos

A 2slides utiliza um sistema baseado em créditos para a geração de slides. Cada página de slide custa 10 créditos.

Regras de Crédito

• Novos Utilizadores: Recebem 880 créditos gratuitos ao registar-se
• Custo: 10 créditos por página de slide (Fast PPT), 100 créditos por página de slide 1K/2K Nano Banana Pro, 200 créditos por página de slide 4K Nano Banana Pro
• Mínimo: Os utilizadores precisam de pelo menos 10 créditos para iniciar a geração
• Dedução: Os créditos são deduzidos apenas após a geração bem-sucedida
• Reembolsos: Os créditos são reembolsados se a geração falhar

Verificar Créditos

Pode verificar o seu saldo de créditos através do painel de controlo da conta ou examinando as informações de crédito nas respostas da API.

Comprar Créditos

Créditos adicionais podem ser comprados através da página de preços usando vários métodos de pagamento.

Exemplos

Exemplo de Fluxo de Trabalho Completo

Aqui está um exemplo completo de como gerar slides usando a API 2slides em Javascript e Python:

const API_KEY = 'sk-2slides-your-api-key-here';
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();

Exemplo em Python

import requests
import time
import json

API_KEY = 'sk-2slides-your-api-key-here'
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()

Exemplos cURL

Pesquisar temas:

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

Gerar slides:

curl -X POST "https://2slides.com/api/v1/slides/generate" \
  -H "Authorization: Bearer sk-2slides-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "Create a timeline for our project milestones",
    "themeId": "theme-uuid-here",
    "responseLanguage": "English",
    "mode": "async"
  }'

Verificar status do trabalho:

curl -X GET "https://2slides.com/api/v1/jobs/job-uuid-here" \
  -H "Authorization: Bearer sk-2slides-your-api-key-here"

Tratamento de Erros

A API utiliza códigos de status HTTP padrão e retorna informações detalhadas de erro em formato JSON.

Respostas de Erro Comuns

400 Pedido Inválido:

{
  "success": false,
  "error": "userInput is required and must be a non-empty string"
}

401 Não Autorizado:

{
  "success": false,
  "error": "Authentication required"
}

403 Proibido:

{
  "success": false,
  "error": "Access denied"
}

404 Não Encontrado:

{
  "success": false,
  "error": "Theme not found"
}

429 Demasiados Pedidos:

{
  "success": false,
  "error": "Rate limit exceeded"
}

500 Erro Interno do Servidor:

{
  "success": false,
  "error": "Internal server error"
}

Melhores Práticas de Tratamento de Erros

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;
  }
}

Melhores Práticas

1. Segurança da Chave da API

• Nunca exponha chaves da API em código do lado do cliente ou repositórios públicos
• Use variáveis de ambiente para armazenar chaves da API de forma segura
• Rode as chaves regularmente para maior segurança
• Monitorize o uso da chave através do painel de gestão da API
• Armazene as chaves de forma segura: Lembre-se que a 2slides não armazena as suas chaves da API, por isso deve mantê-las em segurança
• Faça backup das suas chaves: Armazene as chaves da API num gestor de palavras-passe seguro ou em armazenamento encriptado

2. Uso Eficiente da API

• Armazene em cache os resultados da pesquisa de temas para evitar pedidos repetidos
• Implemente intervalos de polling adequados para verificações de status de trabalho (2-5 segundos)
• Lide com os limites de taxa de forma elegante com backoff exponencial
• Agrupe operações quando possível para reduzir chamadas da API

3. Tratamento de Erros

• Verifique sempre os códigos de status da resposta
• Implemente lógica de repetição para falhas transitórias
• Registe os erros de forma adequada para depuração
• Forneça mensagens de erro amigáveis ao utilizador

4. Otimização de Desempenho

• Use intervalos de polling apropriados para evitar pedidos desnecessários
• Implemente timeouts de pedido para evitar pedidos pendurados
• Armazene em cache dados frequentemente usados, como informações de tema
• Monitorize o seu uso de créditos para evitar cobranças inesperadas

5. Diretrizes de Conteúdo

• Forneça entrada clara e estruturada para uma melhor geração de slides
• Use temas apropriados para o seu tipo de conteúdo
• Especifique o idioma quando necessário para conteúdo internacional
• Mantenha o conteúdo conciso para um layout de slide ideal

Suporte e Recursos

Documentação e Recursos

• Documentação da API - Documentação interativa da API e playground
• Galeria de Modelos - Navegue pelos modelos de slides disponíveis
• Informações de Preços - Pacotes de créditos e preços
• Blog - Últimas atualizações e dicas

Obter Ajuda

• API Playground: Teste as suas chamadas da API diretamente no navegador em 2slides.com/api
• Painel de Controlo da Conta: Gerencie o seu uso de créditos em 2slides.com/account
• Suporte: Contacte o suporte através do site principal

Comunidade e Atualizações

• Atualizações de Funcionalidades: Mantenha-se atualizado com novas funcionalidades e melhorias
• Biblioteca de Modelos: Adições regulares de novos modelos profissionais
• Melhorias na API: Melhorias contínuas no desempenho e funcionalidades da API

---

Conclusão

A API 2slides oferece uma forma poderosa e flexível de gerar apresentações profissionais programaticamente. Com o seu conjunto abrangente de funcionalidades, tratamento robusto de erros e uma vasta biblioteca de modelos, pode integrar a geração de slides com IA em qualquer aplicação ou fluxo de trabalho.

Comece a criar apresentações incríveis hoje com a API 2slides! Visite 2slides.com/api para obter a sua chave da API e começar a criar.