POST/api/v1/generate/influencer

Criar influencer

Bearer tokenescopo generate:image

Cria um influencer virtual com aparência parametrizada, usando o modelo nano-banana-pro (aspect ratio 9:16, quality 1K). Responde 202 Accepted com um taskId; acompanhe o resultado por polling em GET /api/v1/tasks/:id ou via webhook.

Escopo necessário: generate:image.

Body

Campo	Tipo	Obrigatório	Valores aceitos	Padrão
`tipo`	string	sim	`humano`, `elfo`	—
`genero`	string	sim	`feminino`, `masculino`	—
`idade`	inteiro	sim	18–60	—
`etnia`	string	sim	`africana`, `arabe`, `asiatica`, `europeia`, `indiana`, `mestico`	—
`olhos`	string	sim	`olhos_ambar`, `olhos_azul`, `olhos_azul_claro`, `olhos_branco`, `olhos_castanho_claro`, `olhos_castanho_escuro`, `olhos_preto`, `olhos_roxo`, `olhos_todo_branco`, `olhos_todo_preto`, `olhos_verde`, `olhos_vermelho`	—
`pele`	string	sim	`pele_normal`, `pele_sardas`, `pele_cicatrizes`, `pele_pintas`, `pele_queimaduras`, `pele_velha`, `pele_descascando`, `pele_albina`, `pele_vitiligo`, `pele_marcas`	—
`corpo`	string	sim	`corpo_normal`, `corpo_atletico`, `corpo_magro`, `corpo_magro_definido`, `corpo_musculoso`, `corpo_curvas`, `corpo_gordo`	—
`bracos`	string	sim	`bracos_normais`, `sem_bracos`	—
`pernas`	string	sim	`pernas_normais`, `sem_pernas`	—
`cabelo`	string	sim	`cabelo_muito_curto`, `cabelo_liso_longo`, `cabelo_afro_black`, `cabelo_afro_curto`, `cabelo_espetado`, `cabelo_punk`, `cabelo_careca`, `cabelo_tentaculos`	—
`estilo`	string	sim	`estilo_hiper`, `estilo_cartoon`, `estilo_anime`, `estilo_2d`	—
`name`	string	não	Nome do personagem (max 100 chars)	`"Influencer"`
`referenceImages`	string[]	não	URLs de referência (max 4); se omitido, geradas automaticamente a partir dos atributos	—
`callbackUrl`	string	não	HTTPS, host não-privado	—

O prompt é gerado automaticamente a partir dos atributos informados.

Exemplo de request

cURL

curl -X POST https://avatrix.io/api/v1/generate/influencer \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-inf-001" \
  -d '{
    "tipo": "humano",
    "genero": "feminino",
    "idade": 27,
    "etnia": "europeia",
    "olhos": "olhos_verde",
    "pele": "pele_normal",
    "corpo": "corpo_atletico",
    "bracos": "bracos_normais",
    "pernas": "pernas_normais",
    "cabelo": "cabelo_liso_longo",
    "estilo": "estilo_hiper",
    "name": "Aurora"
  }'

Resposta — 202

JSON

{
  "success": true,
  "data": { "taskId": "...", "status": "queued" }
}

O status: "queued" é só o rótulo de criação. No polling (GET /api/v1/tasks/:id) a task evolui por pending → processing → completed (com resultUrl) ou failed. Ver Ciclo de vida da task.

Exemplo de erro

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Valor 'foo' inválido para 'etnia'. Valores aceitos: africana, arabe, asiatica, europeia, indiana, mestico."
  }
}

Idempotência

Envie o header Idempotency-Key (opcional, ≤128 chars, TTL 24h). Repetir a mesma chave retorna a resposta original sem novo débito. A concorrência é limitada a 20 tasks simultâneas por usuário. Ver Idempotência.

Custo

Valor fixo por geração.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	campos obrigatórios ausentes ou com valor fora da lista aceita, `idade` fora de 18–60, `name` > 100 chars, mais de 4 `referenceImages`
`INSUFFICIENT_CREDITS`	402	saldo insuficiente
`FORBIDDEN`	403	token sem `generate:image`
`RATE_LIMITED` / `MAX_CONCURRENT_TASKS`	429	rate limit ou 20 tasks simultâneas
`INTERNAL_ERROR`	500	erro interno ao processar a cobrança
`GENERATION_FAILED`	502	falha do provider
`PROVIDER_UNAVAILABLE`	503	provider indisponível