POST/api/v1/studio/products

Criar produto do Studio

Bearer tokenImplementadoescopo generate:video

Contrato OpenAPI

operationId: createStudioProduct · Implementada

Parâmetros

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

Schema do request

JSON

{
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "images"
      ]
    },
    {
      "required": [
        "productFileIds"
      ]
    }
  ],
  "description": "A soma de images e productFileIds aceita no máximo 6 itens.",
  "properties": {
    "description": {
      "type": "string"
    },
    "images": {
      "items": {
        "$ref": "#/components/schemas/StudioProductImageInput"
      },
      "maxItems": 6,
      "minItems": 1,
      "type": "array"
    },
    "productFileIds": {
      "items": {
        "maxLength": 200,
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 6,
      "minItems": 1,
      "type": "array",
      "uniqueItems": true
    },
    "title": {
      "type": "string"
    }
  },
  "type": "object"
}

Respostas

HTTP	Significado
`200`	Produto criado
`default`	Erro padronizado

Um produto é o recurso que o Marketing Studio usa como base do vídeo. Criar um produto é pré-requisito de Vídeo do Studio: você envia as imagens, a IA analisa e gera título/descrição, e o id retornado vira o productId da geração.

Escopo necessário: generate:video. Criar um produto não debita créditos (o débito é só na geração de vídeo).

POST /api/v1/studio/products — criar

Body

Campo	Tipo	Obrigatório	Valores / restrições
`images`	array	sim	1 a 6 URLs HTTPS já hospedadas (host não-privado). Item pode ser a string da URL ou `{ "url": "...", "role": "..." }`.
`title`	string	não	Nome do produto. Se omitido, a IA gera a partir das imagens.
`description`	string	não	Descrição. Se omitida, a IA gera.

Exemplo

cURL

curl -X POST https://avatrix.io/api/v1/studio/products \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://storage.avatrix.io/uploads/produto-frente.jpg",
      "https://storage.avatrix.io/uploads/produto-verso.jpg"
    ]
  }'

Resposta — 200

JSON

{ "success": true, "data": { "id": "prod_...", "title": "...", "description": "..." } }

GET /api/v1/studio/products — listar

Lista os produtos salvos do usuário (persistem entre sessões).

cURL

curl https://avatrix.io/api/v1/studio/products \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx"

JSON

{
  "success": true,
  "data": {
    "products": [
      { "id": "prod_...", "title": "...", "description": "...", "images": [{ "url": "..." }], "createdAt": "..." }
    ]
  }
}

Idempotência

O POST aceita o header Idempotency-Key (opcional, máx. 128 chars) — requisições repetidas com a mesma chave (24h) retornam a resposta original. Ver Idempotência.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	`images` ausente/inválida, não-HTTPS ou host privado
`FORBIDDEN`	403	Studio indisponível no plano, ou token sem `generate:video`
`GENERATION_FAILED`	502	falha ao processar as imagens ou no engine
`FEATURE_DISABLED`	503	Marketing Studio indisponível

Ver Códigos de erro e Escopos.