|

Tutorial completo de 5 passos para integrar a API de imagem Nano Banana Pro usando o OpenClaw

ByAPIYI - Stable and affordable AI API

Fazer com que o OpenClaw AI Agent gere imagens automaticamente é um recurso que muitos desenvolvedores querem implementar. Este artigo vai mostrar como criar um Skill personalizado para o OpenClaw em 5 passos, conectando a API de geração de imagens Nano Banana Pro para criar um fluxo de trabalho completo, desde o comando no chat até a imagem final.

Valor central: Ao ler este artigo, você vai dominar a criação de Skills personalizados no OpenClaw e aprender a usar a plataforma APIYI para acessar o Nano Banana Pro, permitindo que seu AI Agent gere imagens profissionais, faça edições e processamento em lote.

openclaw-nano-banana-pro-image-api-tutorial-pt-pt 图示

Visão Geral dos Recursos Principais da API de Imagem Nano Banana Pro

Antes de começar a integração, entenda o que o Nano Banana Pro pode oferecer ao seu OpenClaw Agent.

O Nano Banana Pro (nome oficial Gemini 3 Pro Image Preview) é um modelo de geração de imagens de nível profissional da Google DeepMind, construído sobre o Gemini 3 Pro. Ele é reconhecido como o "melhor modelo para gerar imagens com renderização de texto clara e legível".

Parâmetros Técnicos do Nano Banana Pro

Recurso Parâmetro Descrição
Renderização de Texto Taxa de erro < 10% Precisão de texto em linha única líder do setor
Resolução de Saída 1K / 2K / 4K Resolução nativa alta, sem necessidade de pós-processamento
Imagem de Referência Até 14 imagens Suporte para composição de várias imagens e consistência de personagens
Consistência Facial Até 5 personagens Rosto do personagem consistente em diferentes cenas
Modo de Pensamento Thinking Process Visualização do raciocínio para composições complexas
Grounding de Pesquisa Google Search Geração visual baseada em dados em tempo real

🎯 Dica de integração: O acesso oficial ao Nano Banana Pro exige um cartão de crédito internacional no Google Cloud, o que pode ser uma barreira. Recomendamos usar a plataforma APIYI (apiyi.com), com preço fixo de $0,05 por imagem (80% mais barato que o preço oficial para 4K), suporte a pagamentos locais e sem necessidade de cartão internacional.

Arquitetura completa da integração do OpenClaw Skill com o Nano Banana Pro

Entender a arquitetura geral ajuda você a realizar as configurações subsequentes de forma mais eficiente.

openclaw-nano-banana-pro-image-api-tutorial-pt-pt 图示

Por que escolher a integração via APIYI

Item de Comparação Conexão Direta Google Via APIYI (apiyi.com)
Preço Unitário 4K $0.24/imagem $0.05/imagem (80% de desconto)
Forma de Pagamento Cartão de crédito internacional Alipay / WeChat Pay / USDT
Formato da API SDK nativo do Google Compatível com formato nativo do Gemini
Requisitos de Rede Requer VPN/Proxy Conexão direta
Limite de Concorrência Sujeito a cotas Sem limite, RPM 2000+
Bônus para Grandes Clientes Nenhum Bônus de recarga de até 20%

Passo 1: Criar a estrutura de diretórios do OpenClaw Skill

# Criar a estrutura de diretórios da Skill
mkdir -p ~/.openclaw/skills/nano-banana-pro/scripts
cd ~/.openclaw/skills/nano-banana-pro
touch SKILL.md scripts/generate.py scripts/edit.py

Passo 2: Escrevendo o arquivo de definição SKILL.md

O SKILL.md é o arquivo central que o OpenClaw usa para identificar e chamar sua Skill, composto por metadados YAML (Front Matter) e instruções em Markdown.

---
name: nano-banana-pro
description: Generate and edit images using Nano Banana Pro (Gemini 3 Pro Image) via APIYI platform. Supports text-to-image, image editing, multi-image composition, and batch processing.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - APIYI_API_KEY
      bins:
        - python3
    primaryEnv: APIYI_API_KEY
emoji: "🎨"
---

# Skill de Geração de Imagens Nano Banana Pro


## Funcionalidades
- **Texto para imagem**: Gere imagens de alta qualidade (1K/2K/4K) a partir de descrições de texto.
- **Edição de imagens**: Modifique, componha e realize a transferência de estilo em imagens existentes.
- **Processamento em lote**: Suporte para geração e edição em massa.

Como usar

Gerar imagem

exec python3 scripts/generate.py --prompt "descrição" --aspect-ratio "16:9" --resolution "2K"

Editar imagem

exec python3 scripts/edit.py --instruction "comando de edição" --image-url "URL da imagem"

Observações

  • Use o formato nativo da API do Gemini: /v1beta/models/{model}:generateContent
  • Imagens em 4K levam cerca de 60 segundos; recomenda-se configurar exec timeout=120
  • Recomenda-se usar comandos em inglês para obter os melhores resultados

> 💡 **Dica de Desenvolvimento**: Após a declaração de `primaryEnv: APIYI_API_KEY`, o OpenClaw injetará automaticamente a chave API no ambiente de execução da Skill. Seu script pode lê-la diretamente via variável de ambiente, sem a necessidade de inserir a chave diretamente no código (hardcoding).

---

## Passo 3: Escrevendo o script de texto para imagem generate.py

Este é o script principal, responsável por receber os parâmetros enviados pelo OpenClaw e chamar a API do Nano Banana Pro para gerar as imagens.

### Teste rápido com curl (formato nativo do Gemini)

Primeiro, use um comando curl para verificar se a API está funcionando corretamente; esta é a forma mais rápida de testar:

```bash
curl -s -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer sk-sua-chave-APIYI" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
img_data = data['candidates'][0]['content']['parts'][0]['inlineData']['data']
sys.stdout.buffer.write(base64.b64decode(img_data))
" > gemini-native-image.png

Se a execução for bem-sucedida, o arquivo gemini-native-image.png será gerado no diretório atual.

Script Python (formato nativo do Gemini)

#!/usr/bin/env python3
"""Script de texto para imagem do Nano Banana Pro - OpenClaw Skill (formato nativo do Gemini)"""
import os, json, base64, argparse, requests
from datetime import datetime

API_KEY = os.environ.get("APIYI_API_KEY", "")
API_BASE = "https://api.apiyi.com/v1beta/models"  # Interface nativa do Gemini na APIYI

def generate_image(prompt, aspect_ratio="16:9", resolution="2K"):
    url = f"{API_BASE}/gemini-3-pro-image-preview:generateContent"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "contents": [{"parts": [{"text": prompt}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": aspect_ratio,
                "imageSize": resolution
            }
        }
    }
    response = requests.post(url, headers=headers, json=data, timeout=120)
    response.raise_for_status()
    result = response.json()

    # Formato nativo do Gemini: extraindo inlineData de candidates
    parts = result["candidates"][0]["content"]["parts"]
    for part in parts:
        if "inlineData" in part:
            img_bytes = base64.b64decode(part["inlineData"]["data"])
            filename = f"nano_banana_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
            with open(filename, "wb") as f:
                f.write(img_bytes)
            print(f"Imagem gerada: {filename} ({len(img_bytes)/1024:.1f} KB)")
            return filename
    print("Não foi possível extrair os dados da imagem")
    return None

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt", required=True)
    parser.add_argument("--aspect-ratio", default="16:9")
    parser.add_argument("--resolution", default="2K", help="Resolução: 1K/2K/4K")
    args = parser.parse_args()
    generate_image(args.prompt, args.aspect_ratio, args.resolution)

🚀 Início Rápido: O código acima utiliza a interface de formato nativo do Gemini da APIYI (apiyi.com), com o endpoint /v1beta/models/{model}:generateContent. A estrutura de resposta é idêntica à oficial do Google. Basta criar uma chave no painel da APIYI (api.apiyi.com) para começar a usar.

Passo 4: Escrevendo o script de edição de imagem edit.py

O Nano Banana Pro não apenas gera imagens, mas também suporta a edição de imagens existentes.

#!/usr/bin/env python3
"""Script de edição de imagem Nano Banana Pro - OpenClaw Skill (Formato nativo do Gemini)"""
import os, json, base64, argparse, requests
from datetime import datetime

API_KEY = os.environ.get("APIYI_API_KEY", "")
API_BASE = "https://api.apiyi.com/v1beta/models"

def edit_image(instruction, image_url, extra_images=None):
    url = f"{API_BASE}/gemini-3-pro-image-preview:generateContent"
    headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    # Constrói as partes multimodais no formato nativo do Gemini
    parts = [{"text": instruction}]
    # Converte a URL da imagem em dados inline base64
    img_resp = requests.get(image_url, timeout=30)
    parts.append({"inlineData": {"mimeType": "image/png",
                                  "data": base64.b64encode(img_resp.content).decode()}})
    if extra_images:  # Suporta composição de múltiplas imagens (até 14 imagens de referência)
        for img_url in extra_images[:13]:
            r = requests.get(img_url, timeout=30)
            parts.append({"inlineData": {"mimeType": "image/png",
                                          "data": base64.b64encode(r.content).decode()}})

    data = {
        "contents": [{"parts": parts}],
        "generationConfig": {"responseModalities": ["IMAGE"]}
    }
    response = requests.post(url, headers=headers, json=data, timeout=120)
    response.raise_for_status()
    result_parts = response.json()["candidates"][0]["content"]["parts"]
    for part in result_parts:
        if "inlineData" in part:
            filename = f"editada_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
            with open(filename, "wb") as f:
                f.write(base64.b64decode(part["inlineData"]["data"]))
            print(f"Edição concluída: {filename}")
            return filename
    return None

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--instruction", required=True)
    parser.add_argument("--image-url", required=True)
    parser.add_argument("--extra-images", nargs="*")
    args = parser.parse_args()
    edit_image(args.instruction, args.image_url, args.extra_images)

Resumo das capacidades de edição de imagem

Tipo de Edição Exemplo de Comando Tempo de Processamento
Substituição de fundo "Remova o fundo e adicione um pôr do sol" ~10 seg
Conversão de estilo "Converta para estilo anime" ~15 seg
Adição de elementos "Adicione óculos de sol na pessoa" ~10 seg
Composição de múltiplas imagens "Combine estes logotipos e adicione…" ~20 seg
Adição de texto "Adicione o título: Olá Mundo" ~10 seg
Ajuste de cores "Deixe a imagem mais quente, aumente o contraste" ~8 seg

Passo 5: Configurando o OpenClaw e testando

Configurar a Chave API

No arquivo de configuração do OpenClaw ~/.openclaw/openclaw.json, adicione a configuração da Skill:

{
  "skills": {
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "sk-sua-chave-APIYI"
      }
    }
  }
}

openclaw-nano-banana-pro-image-api-tutorial-pt-pt 图示

Testar a Skill

Envie um comando de teste na plataforma de mensagens para validar a funcionalidade:

Gere uma imagem de exibição de produto de e-commerce em estilo moderno e minimalista, fundo branco, produto centralizado

Verifique se a Skill foi carregada corretamente:

openclaw skills list | grep nano-banana
openclaw skills test nano-banana-pro

💰 Otimização de Custos: O Nano Banana Pro tem um preço unificado de $0,05 por imagem através do APIYI (apiyi.com), independentemente da resolução. Se o seu projeto consome mais de 5.000 imagens por dia, você pode aproveitar bônus de recarga de até 20%, reduzindo o custo por imagem para apenas $0,04.

Comparação de Custo e Desempenho da API Nano Banana Pro

Escolher a forma certa de acesso é fundamental para o uso a longo prazo.

openclaw-nano-banana-pro-image-api-tutorial-pt-pt 图示

O gráfico SVG acima mostra uma comparação detalhada de preços e parâmetros de desempenho. Dados principais: ao acessar o Nano Banana Pro via APIYI, o custo de uma única imagem 4K é de apenas $0,05 (80% de economia em relação aos $0,24 oficiais). Com bônus de recarga para grandes clientes, o valor cai para $0,04 por imagem. A plataforma processa mais de 100 mil imagens por dia, sem limite de concorrência.

Perguntas Frequentes

Q1: Quais dependências preciso instalar para conectar o OpenClaw ao Nano Banana Pro?

Você só precisa do Python 3 e da biblioteca requests. Como fazemos a chamada através da interface de formato nativo do Gemini da APIYI (apiyi.com) (/v1beta/models/{model}:generateContent), não é necessário instalar o SDK google-generativeai do Google. Basta rodar pip install requests. Você também pode testar diretamente com comandos curl, sem qualquer dependência.

Q2: O que fazer se o OpenClaw der timeout ao gerar imagens 4K?

O Nano Banana Pro leva cerca de 60 segundos para gerar imagens em 4K. Nas instruções de uso do SKILL.md, recomendamos que o OpenClaw utilize exec timeout=120 ou exec timeout=180 para chamar o script, evitando que o tempo limite padrão interrompa a tarefa.

Q3: Posso substituir o Nano Banana Pro por outros modelos de geração de imagens?

Sim. A plataforma APIYI (apiyi.com) suporta diversos modelos de geração de imagens simultaneamente. Você só precisa alterar o parâmetro model no arquivo generate.py para trocar de modelo; o formato da API é exatamente o mesmo, sem necessidade de modificar o restante do código.

Q4: Como garantir a segurança da Skill do OpenClaw?

Três medidas fundamentais: primeiro, a chave API deve ser injetada via variáveis de ambiente, nunca escrita diretamente no script; segundo, use apenas Skills criadas por você, evitando instalar habilidades de geração de imagens de fontes desconhecidas no ClawHub (já foram detectadas mais de 820 skills maliciosas); terceiro, verifique periodicamente os logs do OpenClaw para confirmar que não há invocações anômalas.

Q5: Quais operações de edição de imagem são suportadas? Qual é a qualidade?

O Nano Banana Pro suporta substituição de fundo, transferência de estilo, adição/remoção de elementos, composição de múltiplas imagens (até 14 imagens de referência), renderização de texto, etc. A renderização de texto é sua maior vantagem, com uma taxa de erro em textos de linha única inferior a 10%, superando de longe o DALL-E 3 e o Midjourney. Chamando a função de edição pela plataforma APIYI, o custo é de apenas $0.05 por operação, concluída em média em 10 segundos.

Conclusão

Através dos 5 passos deste tutorial, você dominou o processo completo para criar uma Skill personalizada no OpenClaw e acessar a API de imagem do Nano Banana Pro:

  1. Criar o diretório da Skill — Estrutura padrão com SKILL.md + pasta scripts/
  2. Escrever o SKILL.md — Declarar dependências, variáveis de ambiente e comandos de uso
  3. Desenvolver o script de texto para imagem — Invocação do Nano Banana Pro via interface nativa Gemini da APIYI
  4. Desenvolver o script de edição — Suporte para composição de múltiplas imagens, troca de fundo e transferência de estilo
  5. Configuração e Testes — Definir a chave no openclaw.json e validar as funcionalidades

Recomendamos acessar o Nano Banana Pro via APIYI (apiyi.com) para aproveitar o preço unificado de $0.05 por imagem (80% de desconto em relação ao 4K oficial), suporte a interface unificada para Claude, GPT-4o, DeepSeek e outros modelos, além de poder testar gratuitamente os resultados em imagen.apiyi.com.

Este artigo foi escrito pela equipe técnica da APIYI, focada em práticas de integração de APIs de Modelos de Linguagem Grande e tutoriais de desenvolvimento de Agents. Para mais guias técnicos, visite a Central de Ajuda da APIYI: help.apiyi.com

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts