Guia de uso
Guia de introdução ao recraft/crisp-upscale: pontos-chave de integração e cobrança da API de ampliação de imagem
Dos limites de capacidade à cobrança por imagem: como desenvolvedores integram a ampliação de imagem de forma estável em processos de produção
- Modelo
- recraft-crisp-upscale
Nesta página
Que problema o crisp-upscale resolve
Transformar uma imagem já existente, mas com resolução insuficiente, em uma versão maior e com bordas mais nítidas — essa é a função do recraft/crisp-upscale. Ele pertence à categoria image-to-image (imagem para imagem): você fornece uma imagem e ele retorna uma imagem ampliada. Não há espaço para prompt de texto na entrada, e o tipo de saída é fixo: imagem.
O problema que esse tipo de modelo resolve é bem específico:
- Tamanhos de material inconsistentes. Imagens enviadas por usuários, imagens do acervo histórico e imagens fornecidas por parceiros têm resoluções desiguais, mas o tamanho de exibição no front-end é fixado pelo design.
- Conteúdo antigo precisa ser reaproveitado. Imagens de alguns anos atrás, capturas de tela e miniaturas ficam borradas quando colocadas diretamente em contêineres maiores.
- Finalização de resultados gerados. No fim de qualquer pipeline de geração ou edição de imagem, pode ser necessária uma etapa de ampliação para entregar o tamanho final.
Se a sua necessidade é "gerar uma imagem a partir de uma frase", isso não está no escopo deste modelo; se a sua necessidade é "tenho uma imagem e quero deixá-la maior e mais nítida", então ele é o modelo certo. O critério é simples: você já tem um arquivo de imagem concreto em mãos antes da chamada? Se sim, é ele; se não, resolva primeiro a geração em outro lugar.
Para desenvolvedores, essa responsabilidade única é até vantajosa: a semântica da interface é simples, a estrutura de entrada e saída é estável e as causas de falha são mais fáceis de localizar. A ampliação é uma etapa que pode ser testada e revertida de forma independente, sem se misturar com engenharia de prompt.

Limites de capacidade: o que faz e o que não espere
Se você tratar o crisp-upscale como um "ampliador dedicado", as expectativas não sairão do rumo.
O que ele faz
- Recebe uma imagem existente e devolve a imagem ampliada, sendo uma transformação padrão de image-to-image.
- Melhora a nitidez durante a ampliação, que é a direção sugerida pelo nome "crisp".
- Pode ser chamado repetidamente como uma etapa independente em um pipeline; entrada e saída são imagens, sem estado textual adicional.
- É adequado para processar em lote materiais homogêneos, por exemplo, padronizar um lote de imagens de produtos para o tamanho desejado.
O que ele não faz ou não consegue fazer
- Não aceita prompt de texto para gerar imagens. Não é um modelo texto-para-imagem; não existe o papel de prompt na entrada.
- Não se encarrega de entender o conteúdo da imagem. Ele não redesenha, muda o estilo, troca o fundo ou completa o sujeito ausente por você; essas necessidades pertencem a modelos de geração ou edição.
- Não cria detalhes do nada. A ampliação é essencialmente uma inferência baseada nos pixels existentes; quando a imagem original está muito desfocada, com artefatos de compressão intensos ou com informação insuficiente no próprio sujeito, o resultado da ampliação também fica limitado. A qualidade da entrada determina o teto da saída.
- Não permite especificar fator de ampliação ou resolução alvo. O único parâmetro público atual é o endereço público obrigatório da imagem
image_url, com suporte aos formatos JPEG, PNG e WEBP, arquivo único de até 10MB; não há prompt de texto nem parâmetros de fator ou tamanho de saída.
Um critério prático: faça uma rodada de testes com o pior lote de materiais de negócio que você tem, em vez de usar uma imagem de amostra refinada. Se a pior entrada produzir um resultado inaceitável, o problema costuma estar no lado da entrada, não no da chamada.

Especificações de entrada e saída a confirmar antes da chamada
Ao integrar a interface unificada do HiAPI.ai, conclua a lista abaixo antes de escrever o código de negócio; isso evita a maior parte do retrabalho.
Lado da entrada
- O arquivo pode ser decodificado normalmente. Valide localmente o formato e a integridade; não envie arquivos corrompidos, pois o desperdício é das suas chamadas.
- O arquivo atende às restrições de entrada. As restrições públicas são formato JPEG, PNG ou WEBP e arquivo único de até 10MB; se a imagem original for muito pequena, o ganho da ampliação é limitado; se for muito grande, confirme primeiro se o tamanho excede o limite.
- Cor e canal de transparência. Os formatos públicos são JPEG, PNG e WEBP; para origens com canal de transparência ou fora dessa lista, use uma amostra para confirmar se a saída atende ao esperado.
- Tamanho do arquivo. O tempo de upload de arquivos grandes deve ser compatível com a configuração de timeout; não use o timeout curto padrão para imagens grandes.
Lado da saída
- Tamanho da saída. Não é possível especificar a resolução alvo na requisição. Na integração, verifique o comportamento real de "tamanho da origem → tamanho da saída" com algumas imagens de tamanhos diferentes e monte sua própria tabela de referência; não presuma a saída com base em algum nível de nome não disponibilizado.
- Formato e tamanho da saída. O arquivo ampliado costuma ser maior; estime antecipadamente o armazenamento e a largura de banda downstream.
- Critério subjetivo de aceitação da nitidez. Defina antecipadamente o que significa "suficientemente nítido"; caso contrário, não será possível julgar se atingiu o padrão.
Lado dos parâmetros
O único parâmetro público atual é o obrigatório image_url. Não adicione por conta própria fator, resolução alvo, prompt ou outros parâmetros não disponibilizados; primeiro faça a requisição mínima funcionar com esse único item.
Uma ordem mínima de validação: fazer funcionar com uma única imagem pequena → trocar por uma imagem típica do negócio → trocar pela imagem de pior qualidade → trocar pela imagem de maior tamanho. Depois de passar pelas quatro etapas, então discuta processamento em lote.

Cobrança por imagem: como calcular o preço unitário
A base de cobrança do crisp-upscale é por imagem — uma chamada bem-sucedida corresponde a uma imagem e a uma cobrança. Há apenas uma faixa de preço: $0.004/imagem.
Como estimar o uso
Custo mensal ≈ número de imagens chamadas no mês × $0.004. A única variável que realmente precisa ser gerenciada é: o número de imagens chamadas no mês. Ele resulta da multiplicação de três fatores:
- Número de objetos de negócio processados por dia;
- Número médio de imagens a ampliar por objeto;
- Coeficiente extra decorrente de novas tentativas e retrabalho.
O terceiro item é o mais facilmente esquecido. Novas tentativas por falha, reampliação por insatisfação com a qualidade e processamento repetido da mesma imagem por fluxos diferentes fazem o número real de imagens ficar acima da expectativa de negócio. Registre esses três itens separadamente; assim o custo pode ser calculado e gerenciado com base no volume de chamadas.
Alguns meios de controlar o volume de chamadas
- Desduplicação. Amplie uma mesma imagem (identificada por hash de conteúdo) apenas uma vez e reutilize o resultado salvo. Em cenários em que o mesmo material do acervo é referenciado em vários lugares, esse item costuma economizar uma proporção considerável.
- Julgar antes de ampliar. Se o tamanho da imagem original já atende ao requisito de exibição, não é preciso ampliar; uma verificação de tamanho já barra chamadas inválidas.
- Processamento em lote e assíncrono. Para cenários não em tempo real, use filas e retire a ampliação do caminho da requisição do usuário; isso permite agrupar novas tentativas e evitar reenvios causados por timeout.
- Estratégia por níveis. Use ampliação em posições de alto valor, como capas e primeira tela; para miniaturas de listagem, use a imagem original, concentrando o orçamento onde é visível.
- Barreiras de orçamento. Defina limites diários ou semanais de chamadas com alertas para evitar que um bug em loop estoure a cota — esse tipo de acidente tem custo direto em modelos cobrados por imagem.
Faça primeiro uma estatística de amostra completa e depois decida o que ampliar e quanto ampliar; isso é bem mais confiável do que definir um fator no chute.
Usos típicos e combinações em pipeline
A ampliação raramente existe isolada; normalmente é uma etapa de um pipeline. A seguir estão alguns cenários adequados para encaixá-la.
Pós-processamento de materiais
Imagens enviadas por usuários ou pela operação passam por uma ampliação uniforme antes de entrar no acervo, deixando a linha de base de tamanho do acervo consistente. Assim, o front-end não precisa adaptar cada imagem individualmente, e o design pode trabalhar com tamanhos fixos.
Cadeia de reparo de imagens antigas e de baixa qualidade
Capturas de tela e imagens excessivamente comprimidas do conteúdo histórico passam primeiro por uma limpeza básica (como recorte e padronização de formato), depois são ampliadas pelo crisp-upscale e, por fim, recortadas para entrega no tamanho alvo. Atenção à ordem: reparar antes de ampliar, resolvendo os problemas corrigíveis antes da ampliação.
Finalização após a geração
Qualquer pipeline de geração ou edição de imagem pode ter uma etapa de ampliação no final, elevando o resultado do tamanho intermediário ao tamanho de entrega. A vantagem dessa cadeia é o desacoplamento — troque ou não o modelo de geração, a etapa de ampliação não precisa mudar.
Estrutura do pipeline
Upload → validação (formato, tamanho, desduplicação por hash) → chamada de ampliação → inspeção por amostragem de qualidade → armazenamento → distribuição via CDN. A inspeção por amostragem pode ser visual manual ou apenas monitoramento automático de métricas nos materiais principais; em qualquer caso, deve haver uma saída de "devolver se não atingir o padrão".
Duas recomendações de engenharia: a etapa de ampliação deve ser idempotente (mesma entrada, mesma saída, resultado cacheável); e as falhas devem permitir nova tentativa independente, sem reprocessar toda a cadeia.
Armadilhas comuns e checklist de validação
Seguem problemas recorrentes no processo de integração; a maioria pode ser evitada de uma vez antes do lançamento.
Armadilhas comuns
- Usá-lo como modelo de geração. Esperar que ele complete conteúdo ausente ou altere a imagem levará inevitavelmente à decepção. Alinhe primeiro os limites de capacidade.
- Aceitar com imagens refinadas. A amostra é bonita, mas ao entrar em produção com materiais de baixa qualidade o resultado desanda. As amostras de aceitação devem vir da distribuição real do negócio.
- Timeout curto demais. O processamento de imagens grandes leva mais tempo; o timeout padrão facilita a cobrança duplicada por "na verdade deu certo, mas o cliente desistiu".
- Sem desduplicação. O mesmo material é ampliado repetidamente, e o crescimento da fatura não acompanha o crescimento do negócio.
- Presumir níveis de saída não disponibilizados. Não é possível especificar o tamanho de saída na requisição; se você diagramar com base em alguma resolução nominal, pode ser preciso refazer todo o downstream.
- Novas tentativas em loop sem limite. Tentar novamente a cada falha sem limite pode consumir o orçamento de um dia inteiro em uma única falha.
Checklist de validação antes do lançamento
- Executar toda a cadeia com uma pequena amostra da distribuição real do negócio (incluindo imagens de pior qualidade);
- Registrar e confirmar o comportamento real das especificações de entrada e do tamanho de saída;
- Conferir a correspondência entre cada chamada e cada cobrança, confirmando que não há chamadas duplicadas ocultas;
- Validar a taxa de acerto do cache de desduplicação;
- Validar as políticas de timeout, nova tentativa e circuit breaker;
- Criar alertas diários de orçamento e um painel de volume de chamadas;
- Fazer um lançamento gradual com pouco tráfego, comparando a qualidade visual subjetiva e as métricas downstream antes e depois da ampliação, e então migrar totalmente.
O ganho da ampliação é gradual, e o risco também: com a etapa de comparação por pequena amostra bem feita, a integração em larga escala posterior é basicamente trabalho de operação.
Comece fazendo uma imagem funcionar, defina as três coisas — especificações, cobrança e desduplicação — e o crisp-upscale se tornará firmemente aquela etapa discreta, mas sempre ativa, do seu pipeline de imagens.
Artigos relacionados
Ver todos os artigos →-
Guia de uso
Guia de introdução ao gpt-6.2-sol: limites de capacidade, integração via API e noções de precificação por token
Decisões de integração e pontos práticos para equipes de engenharia
-
Guia de uso
Guia de introdução ao gpt-6.2-astra: limites de capacidade do modelo de texto, pontos de integração e controle de custos
-
Guia de uso
Guia de introdução ao Tripo H3.1: três modos de entrada, parâmetros e como escolher o preço
Decisão de integração e controle de custos na geração 3D para desenvolvedores