Agente sobe imagens na galeria

Objetivo: o agent envia imagens para uma galeria da CDN e entrega a URL pública ao app, sem montar URL à mão.

Token necessário: galleries:manage (criar galeria), assets:write (enviar), assets:read (consultar); para gravar a URL no serviço, projects:write e env:write.

1. Criar a galeria

Guarde o key devolvido: ele vai nas rotas. Cada chamada cria uma galeria nova; use Idempotency-Key para repetir com segurança.

curl -sS -X POST "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: receita-imagens-$(date +%s)-$RANDOM" \
  -H "Content-Type: application/json" \
  -d '{"name": "Imagens do site"}'

{"id": "gal_01J9ZK5Q", "key": "imagens-do-site-k7p2", "name": "Imagens do site"}

Erro	Ação
403 forbidden	falta galleries:manage (ou o token é restrito a galerias): peça outro token
429	espere Retry-After e repita

2. Enviar, esperar e ler a URL

Envie com Idempotency-Key derivada do conteúdo. 201 já vem publicado; 202 é pending (não reenvie): consulte o arquivo com backoff (2 s, dobrando até 30 s) até scan.status ser clean. Só então alias_url e url existem. Use sempre o valor devolvido.

GAL=$(curl -sS -X POST "$NEBULAR_API/v1/galleries" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: receita-imagens-b-$(date +%s)-$RANDOM" \
  -d '{"name": "Imagens do site"}' | jq -r '.key')

code=$(curl -sS -o resp.json -w '%{http_code}' -X POST "$NEBULAR_API/v1/galleries/$GAL/assets" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: hero-$(cksum < hero.png | tr ' ' '-')" \
  -F "file=@hero.png" -F "name=site/hero.png")
echo "upload: $code"
delay=2
for attempt in 1 2 3 4 5 6 7 8; do
  status=$(curl -sS "$NEBULAR_API/v1/galleries/$GAL/assets/site%2Fhero.png" \
    -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.asset.current.scan.status')
  [ "$status" = "pending" ] || break
  sleep "$delay"; delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
[ "$status" = "clean" ]
curl -sS "$NEBULAR_API/v1/galleries/$GAL/assets/site%2Fhero.png" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" | jq -r '.asset.alias_url'

Resposta	Ação
413 payload_too_large / quota_exceeded	reduza a imagem (25 MB, 40 MP) ou libere espaço
415, 422	arquivo recusado: não reenvie o mesmo; veja a tabela de erros
409 idempotency_conflict	chave reutilizada com outro arquivo: gere outra
scan.status = rejected	pare: o arquivo foi recusado, scan.reason diz o motivo

Detalhes de pending, lote e troca de imagem mantendo a alias_url: Galerias e arquivos.

3. Entregar a URL ao serviço

Guarde a alias_url como variável do serviço (env:write); o app lê ASSET_BASE_URL e monta os caminhos. A alias sempre aponta para a versão atual, então trocar a imagem não exige novo deploy. Mudar o valor de uma variável marca o serviço como “precisa de redeploy” para pegar o valor novo.

NAME="imagens-$(date +%s)-$RANDOM"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: proj-$NAME" -d "{\"name\": \"$NAME\"}" | jq -r '.id')
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"visibility": "public", "source": {"type": "upload"}}' | jq -r '.id')
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/ASSET_BASE_URL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "https://media.nebularcdn.com/imagens-do-site-k7p2/site/"}'

No exemplo real, use o prefixo da alias_url obtida no passo 2 (a última linha do bloco anterior).

Erro	Ação
403 forbidden	falta projects:write ou env:write
404 not_found	projeto/serviço inexistente ou de outro time: confira os ids; não tente adivinhar
400 invalid_request	nome do serviço fora de ^[a-z][a-z0-9-]{0,30}$ ou campo inválido