Como usar a API de geração de imagens a partir de texto krea-2-medium-turbo (curl + Python)

krea-2-medium-turbo é o nível rápido e de baixo custo de geração de imagens a partir de texto oferecido pela Krea no hiapi. Basta enviar um prompt e escolher uma proporção de aspecto para obter uma imagem renderizada por meio da API de tarefas assíncronas. Este guia oferece exemplos de requisições curl e Python prontos para copiar e colar, voltados para /v1/tasks, com o schema de entrada exato e os tempos de execução e comportamentos de erro que testei em 2026-10-21 — incluindo um resultado que contradiz a documentação.

Pré-requisitos

Uma chave de API do hiapi (sk-...). Crie em API Keys console. Cada requisição é autenticada via Authorization: Bearer sk-<your-key>. Este é o único pré-requisito — o modelo roda no servidor, portanto nada além de um cliente HTTP precisa ser instalado.

Schema de entrada

krea-2-medium-turbo aceita cinco campos. Apenas prompt e model são obrigatórios:

Campo	Obrigatório	Tipo	Valor padrão	Descrição
model	Sim	string	—	Deve ser exatamente krea-2-medium-turbo.
prompt	Sim	string	—	1–5000 caracteres.
aspect_ratio	Não	enum	1:1	Um de 1:1, 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3, 9:16.
creativity	Não	enum	low	raw (mais literal) → low → medium → high (mais criativo).
seed	Não	integer	—	Opcional. Leia a observação sobre seed abaixo antes de depender dele.

O objeto input é estrito (additionalProperties: false): qualquer campo que não esteja nesta tabela é rejeitado antes do início da geração. Não há n / num_images, não há resolution nem size, e não há campo de prompt negativo. Uma requisição retorna exatamente uma imagem e o tamanho da saída é determinado exclusivamente por aspect_ratio. Se você usou outras APIs de imagem no hiapi que aceitam resolution (Seedream, Qwen-Image) ou size, remova esses campos aqui — eles retornarão 400.

Requisição mínima funcional (curl)

Criar uma tarefa retorna imediatamente um taskId; a imagem é renderizada em segundo plano.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

Resposta:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" }, "message": "success" }

Em seguida, consulte a tarefa por id até atingir o estado terminal:

curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" \
  -H "Authorization: Bearer sk-<your-key>"

Uma tarefa concluída se parece com isto (campos omitidos por clareza):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

A imagem está em data.output[0].url.

O mesmo fluxo em Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-<your-key>",
    "Content-Type": "application/json",
}

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # Consulta até a tarefa atingir o estado terminal.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # Atenção: ainda é HTTP 200, veja abaixo
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

Considerações para produção

• Consultar ou usar callback. O loop acima consulta a cada 3 segundos; isso é adequado para baixa concorrência. Em produção, anexe callback.url e defina when: "final" na requisição de criação para que o hiapi envie a tarefa concluída para você via POST, em vez de consultar — veja a convenção de callback na documentação da API de tarefas.
• Falhas de geração ainda retornam HTTP 200. O código de status HTTP no endpoint de consulta indica se a requisição foi bem-sucedida, não se a imagem foi. Falhas de renderização retornam 200 e data.status: "fail". Ramifique com base em data.status, e não no código de status HTTP, caso contrário você tratará falhas como sucessos.
• As URLs de saída são temporárias. Os resultados ficam armazenados em temp.hiapi.ai com "storage": "temp" e um carimbo de data/hora expireAt, expirando após cerca de sete dias (604.800 segundos na minha execução). Baixe os bytes e re-hospede (seu próprio bucket/CDN) assim que a tarefa concluir — não faça hotlink de URLs de temp.hiapi.ai diretamente em páginas de produção.
• O preço é uma tarifa fixa única por imagem, independente da proporção de aspecto ou do nível de criatividade — não há faixas de resolução. Consulte os números atuais na página de preços em vez de codificar valores fixos.

O que eu realmente testei (2026-10-21)

Tudo abaixo vem de chamadas reais, não da documentação:

• Tempo de execução e resolução. Uma requisição 2.35:1 foi concluída em cerca de 26 segundos (diferença de created → completed), retornando um PNG de 1568 × 672 px — portanto 2.35:1 é de fato um recorte cinematográfico widescreen, não aproximadamente quadrado. A tarefa passa por estados intermediários handling → archiving → success enquanto renderiza e move o arquivo para o armazenamento temporário.
• A validação de enum é imposta no servidor. Enviar "aspect_ratio": "21:9" (um valor plausível, mas não suportado) retorna imediatamente 400: invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. A mensagem de erro identifica o campo e lista os valores válidos, o que facilita o tratamento programático.
• Campos desconhecidos retornam 400, não são ignorados. "resolution": "2K" retorna invalid input: <root>: additional properties 'resolution' not allowed; "n": 2 retorna o mesmo erro para n. É a regra additionalProperties: false em ação — se você copiar um corpo de requisição de outro modelo, os campos extras bloquearão a chamada inteira.
• No meu teste, seed não reproduziu exatamente a mesma imagem. Enviei duas vezes seguidas o mesmo prompt, seed: 42, aspect_ratio: 2.35:1 e creativity: medium. Ambos os retornos foram imagens válidas de 1568 × 672, mas visivelmente de cenas diferentes (uma torre branca versus uma torre com listras vermelhas e brancas), com tamanhos de arquivo diferentes (1,30 MB versus 1,51 MB) e hashes diferentes. O campo é aceito e descrito na documentação como reproduzível, mas trate a reprodução exata de pixels como melhor esforço, não como garantia — se você precisa de uma imagem específica, salve o resultado obtido e não solicite novamente com seed.

Páginas relacionadas

• Página do modelo krea-2-medium-turbo — playground online e referência completa de parâmetros.
• Documentação da API krea-2-medium-turbo — detalhes de endpoint e callback.
• Krea 3 geração de imagens a partir de texto — o nível Krea mais novo, focado em qualidade (com modos berry/jam); use-o quando quiser mais refinamento e use krea-2-medium-turbo quando quiser velocidade e baixo custo.
• APIs de geração de imagens por IA no hiapi — outros modelos de geração de imagens a partir de texto por trás da mesma interface de tarefas.

FAQ

Quais proporções de aspecto posso solicitar? Oito: 1:1 (padrão), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3 e 9:16. Qualquer outro valor retorna 400.

Uma chamada pode gerar várias imagens? Não. Não há campo n, e o schema rejeita propriedades desconhecidas, portanto cada requisição gera exatamente uma imagem. Para geração em lote, envie requisições em loop (opcionalmente usando seeds diferentes).

O que creativity faz? Ele controla o quão literalmente o modelo segue o prompt: raw é o mais fiel à redação, high tem a maior liberdade interpretativa, e low (padrão) e medium ficam entre os dois.

krea-2-medium-turbo suporta imagem para imagem ou edição? Não — ele suporta apenas geração de imagens a partir de texto. Não há campo image_urls / imagem de entrada no schema. Se você precisa transformar uma imagem existente, use um modelo dedicado de edição/imagem para imagem no hiapi.

Quanto tempo as URLs de saída duram? Elas são servidas por armazenamento temporário e expiram (cerca de sete dias no meu teste). Baixe e re-hospede as imagens logo após a conclusão da tarefa.