Como usar a API do Recraft V4.1? Gere imagens com paleta de cores em 5 minutos

TL;DR

• A série Recraft V4.1 é um par de modelos de texto para imagem com parâmetros totalmente idênticos: recraft-v4.1/text-to-image gera a versão final com mais detalhes ($0.05/imagem), recraft-v4.1-flash/text-to-image para rascunhos rápidos ($0.01/imagem, preços completos na página de preços), a única diferença é o campo model. Abra a página do modelo para testar; novos usuários ganham 200 créditos ao se registrar.
• O diferencial é a paleta de marca: colors recebe um conjunto de RGB e a imagem tende a ficar dentro dessa gama de cores (ainda não disponível no Playground, apenas via API).
• As chamadas usam a interface /v1/tasks do HiAPI: envie a tarefa e receba o taskId, depois consulte o resultado e, em caso de sucesso, baixe em output[0].url.

O que ele faz

• Fotografia, ilustração e pôster: imagens realistas de produtos, ilustrações vetoriais flat e pôsteres com título, tudo a partir de uma descrição.
• Cores controláveis: colors define a paleta e background_color define a cor de fundo, para manter o material de marca alinhado ao VI.
• 6 tamanhos predefinidos: square_hd (padrão), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, sem largura e altura personalizadas.
• Rascunho com Flash + finalização com V4.1: mesmos parâmetros, só troca o model; 10 rascunhos mais 1 versão final custam $0.15.

Abaixo está um resultado real do V4.1:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(Em português: pôster de marca minimalista para uma marca de café especial, título enorme em negrito sem serifa "NORTH BEAN", paleta de terracota quente e creme, ilustração de um único grão de café, muito espaço negativo, layout de grade suíça. Tamanho escolhido: portrait_4_3.)

recraft-v4.1/text-to-image, portrait_4_3, imagem de exemplo deste artigo 896×1216, $0.05.

Gerar com este prompt →

Como escolher entre os dois modelos

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
Por imagem	$0.01	$0.05
Posicionamento	Rascunho rápido, escolha de direção	Versão final com mais detalhes
Parâmetros	Totalmente iguais (prompt / image_size / colors / background_color)	Mesmo que à esquerda
Indicado para	Exploração em lote, imagens para redes sociais, rodadas de rascunho	Entregáveis, materiais de marca

Os dois modelos usam o mesmo fluxo: o Flash gera 10 direções por $0.10, a escolhida é executada novamente trocando o model para gerar a versão final no V4.1 por $0.05, total de $0.15. Se for só gerar esboços, use o Flash do início ao fim: 1.000 imagens custam apenas $10.00. Para escolher prompts por cenário, veja o guia completo de prompts.

Dois caminhos para começar

Navegador em 3 passos: abra a página do modelo → cole o prompt, escolha o tamanho → clique em gerar, $0.05 por imagem no V4.1. (colors e background_color exigem a API.) Na primeira vez, recomendamos gerar uma imagem no navegador para confirmar se o estilo atende antes de escrever código.

API em 3 passos: POST /v1/tasks para enviar → obter o taskId → GET /v1/tasks/<taskId> até receber success e baixar.

curl: primeiro resultado (com paleta de marca)

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-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

Este exemplo usa os parâmetros reais do caso do Flash: paleta de três cores com azul-escuro, laranja e trigo, mais fundo bege. Para gerar a versão final, troque model por recraft-v4.1/text-to-image e mantenha o restante igual.

Python: enviar, consultar, 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-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

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(3)

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("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Tabela de parâmetros (igual para os dois modelos)

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–10000 caracteres	Descrição da imagem
image_size	Não	square_hd (padrão) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 predefinições, sem largura e altura personalizadas
colors	Não	Array de objetos RGB, cada canal de 0 a 255	Direcionamento forte de paleta: a imagem tende a ficar dentro desse conjunto de cores; ainda não disponível no Playground
background_color	Não	Um único objeto RGB	Cor de fundo; ainda não disponível no Playground

Cada objeto RGB exige as três chaves r/g/b, cada uma de 0 a 255, sem chaves extras. 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
Não enviou prompt	400 invalid input: prompt: missing required field "prompt"
Passou um objeto de largura/altura em image_size	400 invalid input: image_size: got object, want string
Enviou 256 em um canal de colors	400 invalid input: colors.0.r: maximum: got 256, want 255
Faltou a chave b em colors	400 invalid input: colors.0.b: missing required field "b"
Passou colors como string	400 invalid input: colors: got string, want array
Passou uma chave extra no objeto RGB	400 invalid input: colors.0: additional properties 'a' not allowed
Saldo insuficiente	402 insufficient account balance; top up and retry
Reenviar com o mesmo Idempotency-Key retorna 409 ou 422; use uma chave nova e tente de novo.

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 final.
• Salve imediatamente: output[0].url é um endereço temporário; baixe e guarde no seu armazenamento assim que receber, não o trate como link permanente.
• A paleta é direcionamento, não bloqueio: se o prompt citar cores que conflitam com colors, o resultado pode misturar as duas; para seguir estritamente as cores, não cite outras cores no prompt.
• Flash→V4.1 só troca o model: os demais parâmetros permanecem iguais e a ideia de composição é reaproveitada diretamente.

Perguntas frequentes

Os parâmetros dos dois modelos são iguais?

Totalmente iguais. Só troque o campo model, sem nenhuma alteração no código.

Onde configurar o parâmetro colors?

Apenas via API. O Playground ainda não oferece os parâmetros colors e background_color.

O colors garante que só as cores especificadas serão usadas?

Não. É um direcionamento forte: a imagem tende a ficar dentro desse conjunto de cores, mas não é um bloqueio rígido.

Quantas imagens por vez?

1 por vez. Para várias, envie mais tarefas ou entre na fila.

Quantas imagens com $10?

Flash custa $0.01 por imagem, então $10 geram 1.000 imagens. Falhas não são cobradas.

Próximo passo: use o prompt NORTH BEAN para gerar uma imagem na página do modelo; quando precisar das cores da marca, adicione colors à requisição da API; para modelos de cenário, veja o guia completo de prompts.