Como usar a API do Krea 3? Gere sua primeira imagem em 5 minutos

Resumo rápido

• Krea 3 (krea-3/text-to-image) é um modelo de texto para imagem: uma descrição gera fotografia realista, ilustração e concept art; antes de gerar, ele entende e expande o prompt, e dois variantes berry (prioridade em qualidade, padrão) / jam (prioridade em velocidade) alternam pelo mesmo preço. Abra a página do modelo para testar; novos usuários ganham 200 créditos ao se cadastrar.
• O preço é por imagem: Krea 3 $0.036; na mesma família há o mais econômico Krea 2 Medium Turbo (krea-2-medium-turbo) $0.0215 (tabela de preços completa na página de preços).
• A chamada usa a interface /v1/tasks da HiAPI: envie a tarefa e receba o taskId, depois consulte o resultado e, em caso de sucesso, baixe a imagem de output[0].url.

O que ele faz

• Uma única frase de prompt já gera uma cena completa: antes de gerar, o modelo faz raciocínio e expansão; escrever apenas a lighthouse já acrescenta hora, luz e composição; se você escrever com detalhes, ele segue a sua descrição.
• Dois variantes berry / jam com um único ID: alternados por variant, com parâmetros e preço idênticos; com o mesmo seed, os dois têm composição e tonalidade diferentes, então você pode rodar cada um uma vez como duas opções para escolher.
• 6 presets de tamanho até 1K: quadrado, retrato e paisagem, total de 6 (de 1024×1024 a 1024×576), saída em PNG ou JPEG.
• Também gera pôsteres com texto no título: coloque o texto entre aspas; títulos curtos costumam sair corretos.

Esta é uma imagem real gerada com berry:

Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look

(Em português: fotografia de produto em estúdio: frasco de perfume de vidro fosco com tampa de latão escovado sobre um bloco de travertino, luz forte da tarde projetando a sombra longa de uma folha de palmeira em uma parede bege quente, reflexos nítidos, visual editorial de alto padrão. Tamanho padrão square_hd.)

krea-3/text-to-image, berry, square_hd, 1024×1024, $0.036.

Gerar com este prompt →

Como escolher entre os dois modelos

	krea-3/text-to-image (Krea 3)	krea-2-medium-turbo (Krea 2 Medium Turbo)
Por imagem	$0.036	$0.0215
Tamanho	6 presets (máx. 1024×1024), sem suporte a personalizado	aspect_ratio com 8 proporções, incluindo 2.35:1 cinematográfico
Parâmetros especiais	variant (berry/jam), reasoning_level (raciocínio e expansão), negative_prompt (apenas berry)	creativity com 4 níveis (raw/low/medium/high)
Tratamento do prompt	Raciocínio e expansão antes de gerar; frases curtas também geram cenas completas	Gera direto do texto original; quanto mais detalhado, mais detalhado o resultado
Indicado para	Imagem final, exploração rápida com prompts curtos, pôsteres com texto	Geração em lote, composições widescreen, produção diária com orçamento sensível

Os dois modelos podem ser usados em sequência: Krea 2 para esboçar a direção, Krea 3 para a imagem final; um esboço mais uma imagem final custa $0.0575. Para escolher prompts por cenário, veja o guia de prompts.

Dois caminhos para começar

No navegador em 3 passos: abra a página do modelo → cole o prompt, escolha o tamanho → clique em gerar, $0.036 por imagem.

Via API em 3 passos: POST /v1/tasks para enviar → receba o taskId → GET /v1/tasks/<taskId> até success e baixe.

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": "krea-3/text-to-image",
  "input": {
    "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
    "image_size": "square_hd",
    "variant": "berry",
    "reasoning_level": "medium"
  }
}'

Para trocar para Krea 2 Medium Turbo, altere apenas model e os campos de input:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "krea-2-medium-turbo",
  "input": {
    "prompt": "Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen",
    "aspect_ratio": "2.35:1",
    "creativity": "low"
  }
}'

O taskId retornado é o comprovante para consultar o resultado.

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": "krea-3/text-to-image",
    "input": {
        "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
        "image_size": "square_hd",
        "variant": "berry",
        "reasoning_level": "medium",
    },
}

# 提交：带 Idempotency-Key，网络重试不会重复建任务
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 轮询：queued -> handling -> archiving -> success / fail
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(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # 扩展名按实际返回的格式命名
        f.write(img.content)
    print("saved")

Tabela de parâmetros (krea-3/text-to-image)

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–5000 caracteres	Descrição da cena; quanto mais específico, mais fiel à descrição
image_size	Não	square_hd / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9, padrão square_hd	Preset de tamanho, máx. 1024×1024; sem suporte a auto ou largura/altura personalizadas
variant	Não	berry / jam, padrão berry	berry prioriza qualidade, jam prioriza velocidade; mesmo preço
reasoning_level	Não	low / medium, padrão medium	Grau de raciocínio e expansão do prompt; use medium para prompts curtos e low para prompts detalhados
negative_prompt	Não	≤1024 caracteres	Conteúdo indesejado; funciona apenas com berry
output_format	Não	png / jpeg, padrão png	Formato de saída
seed	Não	inteiro 0–2147483647	Reproduz dentro do mesmo variante; berry e jam não reproduzem entre si

Os campos do Krea 2 Medium Turbo são diferentes: prompt (obrigatório), aspect_ratio (8 opções, padrão 1:1), creativity (raw/low/medium/high, padrão low), seed. Campos fora da tabela no corpo da requisição retornam 400.

Erros que você vai encontrar (texto original da interface)

O que você fez	Retorno
Passou auto em image_size	400 invalid input: image_size: value must be one of 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9'
Passou campo fora da tabela (ex.: num_images)	400 invalid input: <root>: additional properties 'num_images' not allowed
prompt vazio	400 invalid input: prompt: minLength: got 0, want 1
variant escrito errado	400 invalid input: variant: value must be one of 'berry', 'jam'
Saldo insuficiente	402 insufficient account balance; top up and retry

Requisições que não passam na validação de parâmetros não são cobradas. Reenviar com o mesmo Idempotency-Key retorna 409 (em processamento) ou 422 (parâmetros inconsistentes); use uma chave nova e tente de novo.

Antes de ir para produção

• Callback: passe "callback": {"url": "https://..."} no nível superior do corpo da requisição; a tarefa notificará seu serviço ao chegar ao estado final, dispensando o polling.
• Salve logo: output[0].url é um endereço temporário; baixe e guarde no seu próprio armazenamento assim que receber.
• Só existem 6 tamanhos: para 2.35:1 cinematográfico ou mais proporções, use o aspect_ratio do Krea 2 Medium Turbo.
• O seed só reproduz dentro do variante: berry e jam com o mesmo seed geram imagens diferentes; para séries de imagens, fixe variant + seed.

Perguntas frequentes

Prompts curtos também geram imagem?

Sim. O modelo faz raciocínio e expansão; uma frase como a lighthouse já gera uma cena completa; para controlar detalhes, escreva o prompt com mais especificidade.

berry e jam diferem apenas na velocidade?

Não apenas na velocidade. Com o mesmo seed, os dois têm composição e tonalidade diferentes, com qualidade equivalente; trate-os como duas opções, rode cada um uma vez e escolha.

O negative_prompt vale para os dois variantes?

Funciona apenas com berry; se você passar para jam, não terá efeito.

Quantas imagens por vez?

Apenas 1 por vez. Para várias, envie mais tarefas ou rode novamente com outro seed.

Quantas imagens com $10?

Krea 3 custa $0.036 por imagem, cerca de 277 imagens. Novos usuários ganham 200 créditos ao se cadastrar (1 dólar = 2.000 créditos).

Próximo passo: pegue o prompt do frasco de perfume e teste uma imagem na página do modelo, depois copie os modelos do guia de prompts conforme o seu cenário.