Recurso · Fotos de detalhes

API de fotos de detalhes do produto para close-ups

Em uma frase

A API de fotos de detalhes da Photta renderiza um close-up de uma área específica do produto. Uma chamada gratuita de análise sugere detalhes que valem a pena fotografar; a chamada de geração custa um valor fixo de 3 credits, sem níveis de resolução.

Obter uma chave de API Ler a documentação

Tempo típico: 20–60 sec
Credits: 3 credits
Processamento: assíncrono, polling
Limites: 600 requisições/min
Autenticação: Chave Bearer

Todos os números nesta página vêm de a documentação da API da Photta · verificado 2026-09-10

POST/api/v1/detail-photos

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
    "detail_label": "collar stitching",
    "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
    "framing": "extreme-closeup",
    "source_type": "apparel"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/detail-photos",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
      "detail_label": "collar stitching",
      "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
      "framing": "extreme-closeup",
      "source_type": "apparel"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

Visão geral

Endpoint: POST /api/v1/detail-photos
Autenticação: API key Bearer
Processamento: Assíncrono — faça polling no endpoint de status
Tempo típico: 20–60 sec
Credits: 3 credits
Limites de entrada: Até 10 MB por imagem; JPEG, PNG, WebP
Idempotente: Não

Requisição e resposta

Requisição

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
    "detail_label": "collar stitching",
    "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
    "framing": "extreme-closeup",
    "source_type": "apparel"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/detail-photos",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
      "detail_label": "collar stitching",
      "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
      "framing": "extreme-closeup",
      "source_type": "apparel"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / Concluído

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "completed",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "output_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10-thumb.jpg",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z",
    "completed_at": "2026-07-30T14:20:42Z",
    "duration_ms": 42000
  },
  "request_id": "req_dtl003"
}

Parâmetros da requisição

CampoDescrição

product_image

Tipo: stringObrigatório

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

Tipo: stringObrigatório

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

Tipo: string

Extra guidance for the close-up. Max 400 characters.

framing

Tipo: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

extreme-closeupcloseupmedium-closeup

source_type

Tipo: string

Tunes what is preserved in the close-up.

= apparel

appareljewelry

Erros

StatusTipoSignificado

400invalid_request_error: The request is malformed or contains invalid parameters.
401authentication_error: The API key is missing, invalid, or expired.
402insufficient_credits_error: Your account does not have enough credits.
404not_found_error: The requested resource does not exist.
409conflict_error: The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error: Too many requests. Slow down and retry.Retry-After: 30
500api_error: An internal server error occurred. Retry later.

Limites

600 requisições por minuto por API key (Janela fixa; o limite é o mesmo em todos os planos)
Um 429 retorna Retry-After: 30 segundos
Até 10 MB por imagem
Formatos: JPEG, PNG, WebP
Batches concorrentes por plano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Apenas polling — a API não envia webhooks.

Pergunte o que vale a pena fotografar e depois fotografe

Analise gratuitamente, escolha um detalhe, envie, faça polling, baixe.

Passo 1
Gerar uma chave de API
As fotos de detalhes usam as mesmas credenciais e o mesmo saldo de credits que qualquer outro recurso da Photta.
Passo 2
Pergunte quais detalhes fotografar
Faça POST em `/api/v1/detail-photos/analyze` com `product_image`. A chamada retorna valores sugeridos de `detail_label`, `detail_description` e `framing` para esse produto, de forma síncrona e sem cobrança.
Passo 3
Faça o POST do close-up
Faça POST em `/api/v1/detail-photos` com `product_image` e `detail_label`. Defina `framing` como `extreme-closeup`, `closeup` ou `medium-closeup`, `source_type` como `apparel` ou `jewelry`, e adicione até 400 caracteres em `detail_description`.
Passo 4
Faça polling até o job ser concluído
Faça GET em `/api/v1/detail-photos/:id` a cada 3 segundos até que `data.status` seja `completed` ou `failed`; o tempo típico de conclusão é de 20 a 60 segundos.
Passo 5
Baixar e persistir
O corpo concluído traz a `output_url`. As fotos de detalhes se encaixam perfeitamente na galeria da PDP, ao lado da foto principal.

O mesmo endpoint em Node.js, Python e cURL

Perguntas que os desenvolvedores fazem antes de subir fotos de detalhes em produção

O que é uma API de fotos de detalhes?

Um endpoint que renderiza um close-up de uma área específica do produto — a costura da gola, um fecho, a trama no peito — a partir de uma única fotografia mais aberta, dispensando uma segunda sessão de estúdio com lente macro.

Quanto custa uma foto de detalhe?

3 credits fixos. Não há níveis de resolução neste endpoint, e a chamada de análise que sugere detalhes é gratuita.

O que o endpoint de análise retorna?

Uma lista de sugestões, cada uma com um `detail_label`, uma `detail_description` explicando por que vale a pena mostrar aquela área e um `framing` recomendado. Passe qualquer sugestão diretamente para a chamada de geração.

Quão fechada é cada opção de enquadramento?

`extreme-closeup` preenche quase todo o quadro com o detalhe, `closeup` mantém um pouco de contexto ao redor e `medium-closeup` mostra o detalhe dentro da peça de roupa ou joia ao redor. Escolha por detalhe, não por produto.

A imagem de origem pode ser uma imagem gerada?

Sim. `product_image` aceita o `output_url` de uma geração concluída, bem como qualquer foto de produto própria, como uma URL https ou um data URI base64.

Como faço polling pelo resultado?

GET `/api/v1/detail-photos/:id` a cada 3 segundos até que `data.status` seja `completed` ou `failed`. A chamada de análise é síncrona e não precisa de polling.

Recursos relacionados

Todos os números nesta página vêm de a documentação da API da Photta · verificado 2026-09-10

Experimente a API em cinco minutos

Gere uma chave de API do Photta, cole o snippet de cURL acima e você terá sua primeira imagem com modelo antes que o café termine de passar.

Criar uma conta e obter uma chave de API Ler a documentação

20–60 sec
3 credits
assíncrono, polling
600 requisições/min
Chave Bearer

API de fotos de detalhes do produto para close-ups

Visão geral

Requisição e resposta

Parâmetros da requisição

Erros

Pergunte o que vale a pena fotografar e depois fotografe

Gerar uma chave de API

Pergunte quais detalhes fotografar

Faça o POST do close-up

Faça polling até o job ser concluído

Baixar e persistir

O mesmo endpoint em Node.js, Python e cURL

Perguntas que os desenvolvedores fazem antes de subir fotos de detalhes em produção

Recursos relacionados

Experimente a API em cinco minutos