find-images

find-images: encontrar, selecionar, baixar e creditar imagens

O script é scripts/imgs.py no diretório deste skill. Nos comandos abaixo, substitua <skill-dir> pelo caminho completo do diretório que contém este SKILL.md (por exemplo C:/Users/<nome>/.claude/skills/find-images). As chaves vêm de variáveis de ambiente ou de ~/.config/image-search/keys.env (SERPER_API_KEY, PIXABAY_API_KEY, EXA_API_KEY opcional). O script as lê por conta própria: nunca as imprima nem procure em outro lugar. Se uma chave estiver faltando, o script informa qual fonte foi ignorada; continue com as outras fontes e peça ao usuário para configurar a chave conforme descrito no README.md deste skill. As mensagens do script, os rótulos das folhas e o credits.md seguem o idioma do sistema (chinês ou inglês); FIND_IMAGES_LANG=zh|en substitui o idioma. A saída vai para images/ no projeto atual: _work/<tag>/ contém os candidatos e as folhas de contato, assets/ as imagens escolhidas, manifest.json o registro de origem de cada imagem, e credits.md a página de créditos.

Primeiro, decida se o slide precisa de uma imagem encontrada

Conteúdo	O que fazer
Dados, comparações, tendências	Não pesquise; use gráficos nativos do pptx ou matplotlib
Processos, estruturas, relacionamentos	Não pesquise; desenhe com formas ou SVG
Conceitos, ilustração abstrata	Tente ícones (icons) primeiro; no Codex você também pode gerar um com imagegen
Produtos, lugares, pessoas, eventos, organizações específicos	Use este skill para encontrar fotos reais
Imagens de clima, fundos de capa	Use este skill com Pixabay ou Commons como fonte

Escolhendo fontes

Fonte (src / mode)	Boa para	Idioma da consulta	Licença
web (Serper, ou seja, Google Images)	Produtos específicos, eventos noticiosos, pessoas, assuntos em chinês	Qualquer. Para assuntos em chinês, adicionar 官方图 (imagem oficial), 高清 (HD) ou 新闻图 (foto de notícia) ajuda	Direitos desconhecidos: apenas apresentações internas e trabalhos acadêmicos, com a fonte citada
commons (Wikimedia Commons)	Marcos históricos, cidades, arquitetura, história, ciência, figuras públicas, logotipos de organizações	Apenas inglês, 2–4 palavras (consultas em chinês retornam quase nada)	CC0 é livre para usar; CC BY / BY-SA precisam de atribuição
pixabay	Imagens de clima e cenas genéricas (escritório, trabalho em equipe, cidade, natureza, indústria)	Chinês ou inglês	Livre para usar, atribuição opcional; máximo de 1280px
mode: site (página oficial)	Imagens oficiais de uma página de produto ou empresa	Forneça a URL da página	Imagem do site oficial; cite a fonte
mode: icons (Iconify)	Ícones de conjuntos de código aberto (MIT, Apache, …)	Apenas inglês, 1–2 palavras (drone, battery). Com menos de 6 resultados, o script também pesquisa cada palavra separadamente	Os conjuntos padrão são livres para usar sem atribuição; color é aplicado tanto em SVG quanto em PNG

Para um assunto específico, use src web ou web,commons. Quando as imagens devem ser livres para usar, use commons,pixabay e deixe web de fora.

Fluxo de trabalho

1. Escreva o plano de imagens (plan.json, UTF-8)

Um item por slide; nomeie cada tag de acordo com o número do slide e a finalidade:

[
 {"tag": "s01_capa", "q": "navio transportador de carros no porto", "q_en": "car carrier ship",
  "src": "commons,pixabay", "orient": "paisagem", "min_side": 1600, "n": 12},
 {"tag": "s04_produto", "q": "比亚迪 海豹07 官方图", "src": "web", "orient": "paisagem", "min_side": 1200, "n": 9},
 {"tag": "s05_oficial", "mode": "site", "url": "https://www.byd.com/cn/", "n": 9},
 {"tag": "s07_icone", "mode": "icons", "q": "battery", "color": "#1F4E79", "n": 16}
]

• q: consulta principal, usada por web e pixabay. Pode estar em chinês para assuntos chineses, como em s04_produto. q_en: consulta em inglês usada por commons; o padrão é q.
• orient: paisagem / retrato / quadrado / qualquer.
• min_side: comprimento mínimo do lado maior em pixels. Fundo de tela cheia 1600, metade de um slide 1000, ilustração pequena 600. A API gratuita do Pixabay fornece no máximo 1280px, então o script reduz a exigência para 1280 para o Pixabay. Isso é suficiente para um fundo de tela cheia em um projetor ou monitor comum, ligeiramente suave em uma tela 4K. Se uma imagem de tela cheia precisar ser muito nítida, prefira os candidatos do Commons.
• n: número de candidatos na folha, no máximo 16.

2. Pesquise e construa as folhas de contato

python <skill-dir>/scripts/imgs.py search --plan plan.json --out images

Itens individuais também funcionam: search --tag s04_produto --q "..." --src web, ou site --tag .. --url .., icons --tag .. --q ... Se argumentos não-ASCII saírem distorcidos no shell (por exemplo, chinês no Git Bash no Windows), coloque-os no plan.json.

Cada item produz uma folha de contato numerada images/_work/<tag>/sheet.jpg e uma lista de texto com uma linha por candidato (tamanho, domínio de origem, licença). Pesquisar a mesma tag novamente sobrescreve seus candidatos e números, então escolha de uma folha antes de pesquisar essa tag novamente.

3. Olhe a folha e escolha

• Abra a imagem da folha: Read no Claude Code, view_image no Codex. Uma folha custa cerca de 1.600 tokens. Não abra candidatos um por um.
• Verifique se o assunto está correto (modelo, lugar), a composição deixa espaço para texto, não há marca d'água ou bloco grande de texto, o estilo combina com o resto da apresentação e a resolução é suficiente.
• Se nada servir, pesquise novamente. Após a primeira pesquisa, pesquise novamente no máximo duas vezes, cada vez de um ângulo diferente, em vez de com sinônimos: um assunto mais específico ou mais amplo, outra fonte ou o outro idioma. Se ainda assim falhar, recorra a ícones ou um layout só de texto, ou avise o usuário.
• Quando houver conflito entre adequação ao tópico e licença: se a solicitação disser que imagens gratuitas são preferidas, pesquise commons,pixabay primeiro; se pesquisar novamente ainda não encontrar nada sobre o tópico, use uma imagem web e rotule-a como "direitos desconhecidos" em seu relatório. Se a solicitação disser que as imagens devem ser gratuitas ou serão publicadas, nunca use web; recorra.
• Os rótulos da folha mostram tamanho, licença (Commons mostra a licença exata, como CC BY-SA 4.0) e domínio de origem; a lista de texto mostra as mesmas informações.

4. Baixe as imagens escolhidas

python <skill-dir>/scripts/imgs.py pick --tag s04_produto --ids 6 --out images

O script baixa a imagem original (Commons através de sua miniatura padrão de 1920px; lados longos acima de 2560px são redimensionados; webp/avif se tornam jpg/png) e a registra em manifest.json. Se o pick relatar um download degradado ("degraded": true no manifesto: proteção de hotlink bloqueou o original e apenas uma miniatura foi obtida), escolha outro candidato.

5. Insira as imagens e construa a página de créditos

• Ao inserir, use file, width e height em manifest.json; corte para caber no layout e nunca estique. Ícones vêm como PNG e SVG (o campo svg).
• Execute credits --out images para escrever credits.md e coloque sua seção de créditos dos slides no último slide (fontes). Se houver uma seção de notas, repasse ao usuário.
• Quando a apresentação estiver concluída, renderize-a e verifique as capturas de tela como de costume. Essa é a única vez que o agente principal precisa olhar as imagens.

Economizando contexto: passe três ou mais imagens para um subagente

O agente principal apenas escreve o plan.json e lê o manifesto. Visualizar folhas, escolher e baixar vão para um subagente, para que as imagens candidatas nunca entrem no contexto principal. Modelo de prompt do subagente:

Leia <skill-dir>/SKILL.md e siga-o para encontrar imagens para a apresentação em <caminho do projeto>.
Plano de imagens: <caminho para plan.json> (tag, finalidade e contexto do slide para cada item abaixo).
<Para cada item: o que o slide diz, onde a imagem vai, paisagem ou retrato, estilo>
Para cada item, olhe a folha uma vez e escolha 1 imagem (no máximo 1 reserva); selecione para <projeto>/images. Se nada servir, pesquise novamente com palavras diferentes, no máximo mais duas rodadas.
Retorne para cada tag: o id escolhido, caminho do arquivo, tamanho, classe de licença e um motivo de uma linha; liste as tags sem imagem adequada e o porquê. Não retorne as imagens em si.

Regras de licença

• Livre para usar (CC0, Pixabay, ícones de código aberto): qualquer uso. Creditar imagens CC0 e Pixabay é uma cortesia, não um requisito.
• Atribuição necessária (CC BY / BY-SA): credite o autor e a licença no slide de fontes. Uma imagem BY-SA modificada deve ser compartilhada sob a mesma licença.
• Direitos oficiais / desconhecidos (site, web): apenas apresentações internas, trabalhos acadêmicos e palestras acadêmicas, com a fonte citada. Antes de publicar ou usar comercialmente, avise o usuário e substitua por imagens livres.
• Fotos de pessoas: figuras públicas em um contexto de notícias são aceitáveis; não use fotos de pessoas comuns como decoração.

Cotas e limites

• Serper: 2.500 consultas gratuitas no cadastro. Uma pesquisa por 20 resultados (quando n > 6) custa 2 consultas, 10 resultados custam 1. Depois disso, você recarrega, a partir de $50 por 50.000 consultas, e as recargas expiram após 6 meses. O saldo restante está no painel serper.dev.
• Pixabay: 100 requisições por minuto; as imagens não devem ser hotlinkadas (o script as baixa).
• Commons: apenas larguras de miniatura padrão (960/1280/1920/3840) podem ser obtidas; pesquise em inglês.
• Iconify: gratuito, sem chave. Converter SVG para PNG precisa do Node.js com sharp. Se estiver faltando, o script avisa; use outra abordagem ou peça ao usuário para executar npm install -g sharp.
• Exa: usado apenas quando o modo site não consegue encontrar imagens na própria página; ele usa créditos do Exa.