POST/api/v1/generate/influencer

Criar influencer

Bearer tokenImplementadoescopo generate:image

Contrato OpenAPI

operationId: generateInfluencer · Implementada

Parâmetros

Nome	Local	Obrigatório	Tipo
`Idempotency-Key`	header	não	string

Schema do request

JSON

{
  "additionalProperties": true,
  "properties": {
    "bracos": {
      "enum": [
        "bracos_normais",
        "sem_bracos"
      ],
      "type": "string"
    },
    "cabelo": {
      "enum": [
        "cabelo_muito_curto",
        "cabelo_liso_longo",
        "cabelo_afro_black",
        "cabelo_afro_curto",
        "cabelo_espetado",
        "cabelo_punk",
        "cabelo_careca",
        "cabelo_tentaculos"
      ],
      "type": "string"
    },
    "callbackUrl": {
      "$ref": "#/components/schemas/HttpsMediaUrl"
    },
    "corpo": {
      "enum": [
        "corpo_normal",
        "corpo_atletico",
        "corpo_magro",
        "corpo_magro_definido",
        "corpo_musculoso",
        "corpo_curvas",
        "corpo_gordo"
      ],
      "type": "string"
    },
    "estilo": {
      "enum": [
        "estilo_hiper",
        "estilo_cartoon",
        "estilo_anime",
        "estilo_2d"
      ],
      "type": "string"
    },
    "etnia": {
      "enum": [
        "africana",
        "arabe",
        "asiatica",
        "europeia",
        "indiana",
        "mestico"
      ],
      "type": "string"
    },
    "genero": {
      "enum": [
        "feminino",
        "masculino"
      ],
      "type": "string"
    },
    "idade": {
      "maximum": 60,
      "minimum": 18,
      "type": "integer"
    },
    "name": {
      "maxLength": 100,
      "type": "string"
    },
    "olhos": {
      "enum": [
        "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"
      ],
      "type": "string"
    },
    "pele": {
      "enum": [
        "pele_normal",
        "pele_sardas",
        "pele_cicatrizes",
        "pele_pintas",
        "pele_queimaduras",
        "pele_velha",
        "pele_descascando",
        "pele_albina",
        "pele_vitiligo",
        "pele_marcas"
      ],
      "type": "string"
    },
    "pernas": {
      "enum": [
        "pernas_normais",
        "sem_pernas"
      ],
      "type": "string"
    },
    "referenceFileIds": {
      "items": {
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 4,
      "type": "array",
      "uniqueItems": true
    },
    "referenceImages": {
      "items": {
        "$ref": "#/components/schemas/HttpsMediaUrl"
      },
      "maxItems": 4,
      "type": "array"
    },
    "tipo": {
      "enum": [
        "humano",
        "elfo"
      ],
      "type": "string"
    }
  },
  "required": [
    "tipo",
    "genero",
    "idade",
    "etnia",
    "olhos",
    "pele",
    "corpo",
    "bracos",
    "pernas",
    "cabelo",
    "estilo"
  ],
  "type": "object"
}

Respostas

HTTP	Significado
`202`	Geração aceita para processamento assíncrono
`default`	Erro padronizado

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