Como usar a API Recraft Crisp Upscale? Ampliação de 2x com um único campo

TL;DR

• Recraft Crisp Upscale (recraft/crisp-upscale) faz uma coisa: dobra a largura e a altura da imagem, deixando bordas e texturas mais nítidas e preservando o conteúdo e os textos exatamente como estavam. Não há prompt; o corpo da requisição tem apenas um image_url. Abra a página do modelo, envie uma imagem e teste; novos usuários ganham 200 créditos ao se cadastrar.
• $0.004 por imagem: 1.000 imagens por $4,00; com $10 saem cerca de 2.500 imagens; o tamanho da imagem de entrada não afeta o preço (preços completos na página de preços).
• A chamada usa o endpoint /v1/tasks da HiAPI: envie a tarefa e receba um taskId, depois consulte o resultado e, em caso de sucesso, baixe em output[0].url (JPEG, sem canal alfa).

O que ele faz

• Ampliação fiel, não redesenho: texturas do mostrador, rugas de pele, letras pequenas de pôsteres ficam mais nítidas, mas conteúdo, composição e textos não mudam em nada — materiais com texto não serão "ampliados para virar outra imagem".
• Ajustável com um único campo: image_url recebe um endereço público (JPEG / PNG / WebP, ≤10 MB), sem prompt e sem opção de fator de ampliação.
• Ideal para fotos de produtos, pôsteres com texto e materiais de design: qualquer cenário em que "a imagem original já está certa, só falta resolução".
• Cenários inadequados também são claros: se você quer detalhes redesenhados em nível 4K ou quer alterar o conteúdo de passagem, use redesenho generativo (veja também o tutorial em inglês sobre aumentar a resolução com modelos image-to-image); o Crisp Upscale só dobra o tamanho, sem redesenhar o conteúdo.
• Saída de 1 JPEG; se precisar de resultado com transparência, amplie primeiro e remova o fundo depois (o uso da remoção de fundo está no tutorial em inglês de remoção de fundo).

Abaixo há um par real de "original → 2x":

Original 640×640	Resultado ampliado 1280×1280

recraft/crisp-upscale, 640×640 → 1280×1280, $0.004. O guilloché do mostrador, a caixa de aço escovado e as letras pequenas do mostrador continuam nítidos no dobro do tamanho.

Abra a página do modelo e envie uma imagem para testar →

Dois caminhos para começar

3 passos no navegador: abra a página do modelo → envie a imagem → clique em ampliar, $0.004 por imagem.

3 passos via API: POST /v1/tasks para enviar → receba o taskId → GET /v1/tasks/<taskId> e, quando aparecer success, baixe. Para lotes, repita esses três passos em loop, uma tarefa por imagem.

curl: a primeira imagem

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft/crisp-upscale",
  "input": {
    "image_url": "https://static.hiapi.ai/gallery/2026/10/4fdfd6b43b638849.jpg"
  }
}'

O corpo da requisição é só isso — enviar qualquer campo a mais (como prompt ou scale) retorna 400 direto.

Python: enviar, consultar e baixar

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft/crisp-upscale",
    "input": {
        "image_url": "https://example.com/your-image.jpg",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # endereço temporário, baixe e salve o quanto antes
    img = requests.get(image_url, timeout=60)
    with open("upscaled.jpg", "wb") as f:
        f.write(img.content)
    print("saved upscaled.jpg")

Tabela de parâmetros

Campo	Obrigatório	Valores	Descrição
image_url	Sim	Endereço público http/https	JPEG / PNG / WebP, uma imagem por vez ≤10 MB

É só esse campo. O fator de ampliação é fixo em 2x na largura e na altura, sem opção; não há prompt nem parâmetro de formato de saída.

Erros que você vai encontrar

Código de status	Significado	Como tratar
400 INVALID_REQUEST	image_url ausente, não é um endereço http/https ou foram enviados campos inexistentes como prompt / scale	Deixe apenas image_url no corpo da requisição
402 INSUFFICIENT_QUOTA	Saldo insuficiente (não há cobrança)	Recarregue e tente novamente
429 RATE_LIMITED	Limite de requisições atingido	Reduza a frequência de envio
409 / 422 IDEMPOTENCY_KEY_*	Reenvio com a mesma chave de idempotência	Use um novo Idempotency-Key

Falhas em estado terminal da tarefa também têm códigos como TASK_FAILED e TASK_TIMEOUT; falhas não são cobradas.

Atenção antes de ir para produção

• Callback: envie no nível superior do corpo da requisição "callback": {"url": "https://..."} para ser notificado automaticamente no estado terminal.
• Salve logo: output[0].url é um endereço temporário; baixe assim que receber.
• Tempo de execução: geralmente de 10 segundos a cerca de 1 minuto por imagem; não configure intervalos de consulta curtos demais.
• Canal alfa: a saída é JPEG sem transparência; para materiais com fundo transparente, amplie primeiro e remova o fundo depois (se inverter a ordem, as bordas do recorte ficam borradas).
• A conta de lotes é fácil: ampliar cinco imagens de um SKU custa $0.02; uma rodada de 1.000 materiais da loja inteira custa $4,00, basta enviar em lote, com cada tarefa contando o tempo separadamente.
• A qualidade da original define o limite: a ampliação de 2x deixa as bordas mais nítidas, mas trechos borrados da original não ganham detalhes do nada; teste com uma imagem em materiais críticos antes de ir para o lote.

Perguntas frequentes

É mesmo só 2x?

Sim. A largura e a altura dobram (640×640 → 1280×1280, 480×640 → 960×1280), o fator é fixo e não há opção de 4x; se precisar de mais, rode novamente sobre o resultado.

Os textos na imagem mudam?

Não. Pôsteres com texto mantêm os glifos como estavam, sem reescrita nem acréscimo de texto.

Quanto custa por imagem?

$0.004 por imagem, 1.000 imagens por $4,00; o tamanho da imagem de entrada não afeta o preço. Falhas não são cobradas e a validação de parâmetros que falha não entra na cobrança.

Dá para enviar base64?

Não. image_url precisa ser um endereço público http/https; envie o arquivo local para o seu armazenamento e passe o endereço.

Quanto tempo leva uma imagem?

Normalmente de 10 segundos a cerca de 1 minuto; tarefas em lote entram na fila conforme a quantidade, então envie em partes se estiver com pressa.

Próximo passo: pegue uma imagem do seu produto e amplie na página do modelo para ver o resultado; cinco pares reais de "original → 2x" estão na página de casos; a comparação com o redesenho generativo na mesma imagem original está na página de comparação.