MÓDULO 2.4 - AVANÇADO

🔧 A Estrutura JSON

Domine a linguagem de comunicação com APIs de IA. Aprenda a estruturar requisições JSON para DALL-E 3, Midjourney, Stable Diffusion e outras ferramentas avançadas.

~45
Minutos
5
Conceitos
JSON
Completo
📋

O que é JSON para IA

A linguagem universal das APIs modernas

JSON (JavaScript Object Notation) é o formato padrão para comunicação com APIs de IA. É uma linguagem leve e legível que estrutura dados em pares chave-valor, permitindo enviar instruções complexas para modelos de geração de imagem.

💡 Por que JSON?

✓

Estrutura Clara

Organiza parâmetros de forma hierárquica e intuitiva

✓

Legibilidade

Fácil de ler e escrever para humanos e máquinas

✓

Universalidade

Suportado por todas as principais APIs de IA

✓

Flexibilidade

Permite parâmetros opcionais e aninhados

🎨 APIs que usam JSON

  • • DALL-E 3 (OpenAI)
  • • Midjourney API
  • • Stable Diffusion API
  • • Leonardo.ai API
  • • Replicate API

📡 Onde você verá JSON

  • • Requisições HTTP (POST/GET)
  • • Documentação de APIs
  • • Configurações de ferramentas
  • • Respostas de servidores
  • • Arquivos de config
🏗️

Estrutura Básica do JSON

Anatomia de um documento JSON

Todo JSON é composto por pares chave-valor. Vamos entender cada elemento:

📐 Exemplo Básico

{
  "prompt": "a red apple on a wooden table",
  "model": "dall-e-3",
  "size": "1024x1024",
  "quality": "standard",
  "n": 1
}

🔑 Chaves (Keys)

Sempre entre aspas duplas

"prompt", "model"

💎 Valores (Values)

Texto, número ou booleano

"texto", 1, true

⚙️ Sintaxe

Separados por vírgula

"chave": "valor",

🎯 Tipos de Dados

{
  // String (texto entre aspas duplas)
  "prompt": "professional photo of a cat",

  // Número inteiro
  "n": 1,

  // Número decimal
  "temperature": 0.7,

  // Booleano (verdadeiro/falso)
  "hd": true,

  // Array (lista de valores)
  "sizes": ["256x256", "512x512", "1024x1024"],

  // Objeto aninhado
  "style": {
    "preset": "cinematic",
    "lighting": "dramatic"
  }
}

⚠️ Regras de Sintaxe Importantes

  • ❌ NÃO use vírgula após o último item
  • ❌ NÃO use aspas simples - sempre aspas duplas "assim"
  • ❌ NÃO use comentários em JSON real (apenas para documentação)
  • ✓ USE aspas duplas em todas as chaves e valores de texto
  • ✓ USE vírgulas entre pares, mas não no último
⚡

Parâmetros Principais para APIs de IA

Os controles essenciais de cada plataforma

🎨 DALL-E 3 (OpenAI)

{
  "model": "dall-e-3",
  "prompt": "A futuristic cityscape at sunset with flying cars",
  "n": 1,
  "size": "1024x1024",
  "quality": "hd",
  "style": "vivid"
}
📝 prompt

Tipo: String | Obrigatório: Sim

Descrição textual da imagem desejada. Máximo 4000 caracteres.

📐 size

Valores: "1024x1024", "1792x1024", "1024x1792"

Dimensões da imagem gerada. Quadrada, horizontal ou vertical.

💎 quality

Valores: "standard", "hd"

"hd" cria imagens com maior detalhamento (custo maior).

🎨 style

Valores: "vivid", "natural"

"vivid" = cores saturadas | "natural" = mais realista.

⚡ Stable Diffusion API

{
  "key": "YOUR_API_KEY",
  "prompt": "beautiful landscape with mountains, sunset, 8k, detailed",
  "negative_prompt": "blurry, low quality, distorted",
  "width": 512,
  "height": 512,
  "samples": 1,
  "num_inference_steps": 50,
  "guidance_scale": 7.5,
  "seed": null
}
negative_prompt

O que você NÃO quer na imagem. Essencial para evitar artefatos.

num_inference_steps

Número de passos de refinamento. Mais passos = maior qualidade (20-50).

guidance_scale

Quão próximo seguir o prompt. Valores 1-20 (7-12 recomendado).

seed

Número para reproduzir resultados. Mesmo seed = mesma imagem.

🚀

Exemplos Práticos Completos

Casos de uso reais com JSON configurado

📸 Exemplo 1: Fotografia de Produto

produto-profissional.json - DALL-E 3
{
  "model": "dall-e-3",
  "prompt": "Professional product photography of a luxury watch on marble, studio lighting, shallow depth of field, 8k resolution",
  "size": "1792x1024",
  "quality": "hd",
  "style": "natural",
  "n": 1
}

Por que funciona:

  • ✓ Formato horizontal (1792x1024) ideal para produto
  • ✓ Qualidade HD para detalhes precisos
  • ✓ Style "natural" para fotografia realista
  • ✓ Prompt específico sobre iluminação e estilo

🐉 Exemplo 2: Arte Conceitual Fantasy

arte-fantasy.json - Stable Diffusion
{
  "key": "YOUR_API_KEY",
  "prompt": "epic fantasy dragon over ancient castle, dramatic sunset, concept art, highly detailed, 8k",
  "negative_prompt": "blurry, low quality, bad anatomy, deformed, text, watermark",
  "width": 768,
  "height": 512,
  "samples": 4,
  "num_inference_steps": 50,
  "guidance_scale": 9.0,
  "seed": 42
}

Técnicas aplicadas:

  • ✓ Negative prompt detalhado para evitar artefatos
  • ✓ 4 samples para variações
  • ✓ 50 steps para alta qualidade
  • ✓ Guidance scale 9.0 para seguir bem o prompt
  • ✓ Seed fixo (42) para reproduzibilidade

👤 Exemplo 3: Retrato Fotorrealista

retrato-realista.json - Leonardo.ai API
{
  "apiKey": "YOUR_API_KEY",
  "modelId": "leonardo-diffusion-xl",
  "prompt": "portrait of a 30 year old woman, professional headshot, natural lighting, soft smile, business casual, Canon 5D 85mm f/1.8",
  "negative_prompt": "cartoon, anime, painting, 3d render, multiple people",
  "num_images": 1,
  "width": 1024,
  "height": 1536,
  "guidance_scale": 7,
  "photoReal": true,
  "photoRealStrength": 0.55,
  "presetStyle": "CINEMATIC"
}

Parâmetros específicos do Leonardo:

  • ✓ photoReal: true - Ativa modo fotorrealista
  • ✓ photoRealStrength - Intensidade do realismo (0-1)
  • ✓ presetStyle - Preset visual (CINEMATIC, CREATIVE, etc.)
  • ✓ Formato vertical (1024x1536) ideal para retratos
🐛

Debugging: Erros Comuns e Soluções

Como identificar e corrigir problemas

❌ Erros de Sintaxe

Erro: Vírgula no último item

ERRADO
{
  "prompt": "a cat",
  "size": "1024x1024",
  "n": 1,  ← ERRO
}
CORRETO
{
  "prompt": "a cat",
  "size": "1024x1024",
  "n": 1
}

Erro: Aspas simples

ERRADO
{
  'prompt': 'sunset'
}
CORRETO
{
  "prompt": "sunset"
}

Erro: Chaves sem aspas

ERRADO
{
  prompt: "a red car"
}
CORRETO
{
  "prompt": "a red car"
}

⚠️ Erros de API

Error 400: Bad Request

Causa: Parâmetros inválidos ou ausentes.

Solução: Verifique se todos os parâmetros obrigatórios estão presentes e com valores válidos.

Error 401: Unauthorized

Causa: API key inválida ou ausente.

Solução: Verifique se a chave da API está correta e ativa.

Error 429: Rate Limit Exceeded

Causa: Muitas requisições em pouco tempo.

Solução: Implemente delays entre requisições ou aguarde reset do limite.

✅ Checklist de Debug

✓ Todas as chaves estão entre aspas duplas?
✓ Valores de texto entre aspas duplas?
✓ Sem vírgula após o último item?
✓ Colchetes {} e [] balanceados?
✓ Sem comentários no JSON final?
✓ API key correta e ativa?

✅ O que você aprendeu neste módulo

✓ O que é JSON e por que é usado em APIs
✓ Estrutura básica: chaves, valores e tipos
✓ Parâmetros principais do DALL-E 3
✓ Parâmetros do Stable Diffusion
✓ Exemplos práticos completos
✓ Erros comuns e como corrigi-los
✓ Ferramentas de validação JSON
✓ Debugging de APIs de IA

Próximo: Aprenda a fazer requisições HTTP reais para APIs de IA!

Módulo 2.3 Módulo 2.5

Baseado em: OpenAI API Documentation, Stable Diffusion API Reference, JSON.org