Como usar IA para trocar o estilo de imagens: guia de transferência de estilo imagem para imagem com a API hiapi

Trocar o estilo de uma foto com IA — transformar um clique casual em um quadro de animação, uma foto de produto em estúdio ou uma ilustração em aquarela — não é um endpoint especial de "transferência de estilo". É simplesmente uma chamada comum de imagem para imagem: você envia uma imagem de origem e uma instrução de texto indicando o estilo desejado, e o modelo retorna uma nova imagem. O que realmente determina se você obtém uma troca de estilo limpa ou uma meia-regeneração é como você escreve essa instrução, não algum parâmetro ajustável. Este guia apresenta o mecanismo de requisição na API unificada de tasks da hiapi, os padrões de prompt que impedem que a troca de estilo se desvie para uma nova imagem, e como escolher entre dois modelos de imagem para imagem validados de acordo com o grau de liberdade criativa que você deseja.

O que você precisa preparar

1. Uma chave de API da hiapi — obtenha-a no seu painel. Ela vai no cabeçalho Authorization: Bearer sk-... de cada requisição.
2. Uma URL de imagem de origem acessível publicamente. Os servidores da hiapi buscam a imagem por conta própria, portanto caminhos localhost ou buckets privados sem URL assinada não funcionam. URLs pré-assinadas de S3/R2/GCS funcionam.

Cada id de modelo e campo abaixo foi revalidado contra a API em produção antes da publicação, incluindo uma sondagem de erro forçado para confirmar os valores de enumeração atuais.

Por que a troca de estilo precisa de uma "cláusula de preservação"

Nenhum dos dois modelos deste guia oferece um parâmetro numérico de intensidade ou força — enviar um (strength: 0.5) é rejeitado diretamente, com o erro additional properties 'strength' not allowed. A intensidade do estilo é controlada inteiramente pela redação do prompt, o que significa que uma instrução como "make this a Studio Ghibli anime frame" só diz ao modelo o que adicionar, mas não diz o que manter inalterado — a identidade do sujeito, a pose e a composição podem ser reinterpretadas livremente pelo modelo.

A solução é sempre escrever duas cláusulas no prompt:

1. O estilo alvo, declarado com uma referência visual concreta (um meio, um gênero artístico, uma aparência específica — "anime cel-shading", "1970s film photography", "clean studio product shot on white"), em vez de adjetivos vagos como "cooler".
2. Uma cláusula de preservação explícita — nomeie o que não pode mudar: "keep the same subject, pose, and composition", "keep the text and logo unchanged", "keep the camera angle".

Um prompt como "Restyle this photo as a woodblock print. Keep the subject's pose, framing, and the position of every object in the scene." dá ao modelo, na mesma instrução, um objetivo e uma restrição — esta é a maior alavanca para obter uma troca de estilo em vez de uma regeneração.

Exemplo mínimo funcional: curl

Este exemplo usa seedream-5.0-pro/image-to-image, que troca estilos muito bem e tem um schema estrito e totalmente validado:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Restyle this portrait as a watercolor painting with visible brush texture and soft bleeding edges. Keep the subject'\''s pose, expression, and framing exactly as in the source.",
      "image_urls": ["https://your-bucket.example.com/portrait.jpg"],
      "aspect_ratio": "3:4",
      "resolution": "2K"
    }
  }'

aspect_ratio é obrigatório e vem de uma enumeração fixa — atualmente 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9. Este endpoint não tem opção de "corresponder à imagem de origem", então escolha o valor mais próximo da proporção real da imagem de origem (foto vertical → 3:4 ou 9:16, não 16:9), para evitar que o modelo adicione bordas ou corte a composição para ajustar.

Após a criação bem-sucedida, o id da tarefa é retornado em data.taskId:

{ "data": { "taskId": "<your-task-id>" } }

Faça polling até chegar ao estado terminal:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status eventualmente será success (saída em data.output[0].url) ou fail (detalhes em data.error).

Script Python completo: criar, fazer polling, baixar

Usando apenas a biblioteca padrão:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the restyle task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": (
            "Restyle this street photo as a 1980s film-grain photograph with warm, "
            "faded colors. Keep the same subject, pose, and every object in the "
            "same position in the frame."
        ),
        "image_urls": ["https://your-bucket.example.com/street.jpg"],
        "aspect_ratio": "16:9",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "restyled.png")
print("saved restyled.png")

Escolha o modelo de acordo com a liberdade criativa desejada

Ambos os modelos foram revalidados online e nenhum aceita o parâmetro strength, mas eles diferem quanto ao controle que você tem sobre a influência da imagem de origem:

	seedream-5.0-pro/image-to-image	grok-imagine-quality/image-to-image
Imagens de referência	1–10 URLs públicas	1–3 URLs públicas
resolution	1K / 2K (maiúsculas)	1k / 2k (minúsculas) — opcional
Controle de composição	Enumeração fixa de 8 valores de aspect_ratio, sem correspondência automática	aspect_ratio: "auto" segue o quadro de entrada
Mais adequado para	Troca de estilo precisa, com uma única imagem de referência, quando você já conhece a proporção alvo	Troca de estilo rápida em que você quer que a saída herde a composição exata da imagem de origem sem precisar escolher a proporção

Se a sua cláusula de preservação inclui "same framing" e você não quer calcular manualmente a proporção da imagem de origem, usar grok-imagine-quality/image-to-image com aspect_ratio: "auto" é o caminho mais direto — substitua-o na requisição acima, use até 3 image_urls e defina resolution como 2k em minúsculas.

Considerações para produção

Em servidores, prefira callbacks ao polling. Adicione um objeto callback na requisição e a hiapi fará um POST uma única vez no estado terminal, sem que você precise fazer polling:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

Trate o payload do callback como um sinal, não como fonte da verdade — obtenha o id da tarefa a partir dele e faça você mesmo uma nova requisição GET /v1/tasks/<id> antes de agir. Para scripts e notebooks, fazer polling a cada 5 segundos é suficiente.

Torne as retentativas idempotentes. Armazene seu próprio mapeamento de imagem de origem → taskId ao criar a tarefa. Se o seu processo cair no meio do polling, ao reiniciar ele deve reassociar o taskId armazenado em vez de reenviar — reenviar é uma segunda tarefa cobrada.

Erros que você realmente vai encontrar:

• 401 permission_denied — chave mal formatada ou ausente. O cabeçalho deve ser exatamente Authorization: Bearer sk-....
• 400 INVALID_REQUEST — violação de schema, por exemplo aspect_ratio: value must be one of '1:1', '4:3', ... ou additional properties 'strength' not allowed. O schema dos dois modelos é estrito — não aplique parâmetros de uma família de modelos em outra.
• image_urls must be an array — foi passada uma string simples em vez de uma lista, mesmo que haja apenas uma imagem de referência.

Leitura relacionada

• Referência completa campo a campo do modelo principal deste guia: Como usar seedream-5.0-pro/image-to-image.
• Prompts de troca de estilo prontos para copiar, com comparações reais de antes e depois: Receitas de prompt imagem para imagem do Grok Imagine Quality.
• Comparação de qualidade de saída entre modelos na mesma edição: Melhores APIs de imagem para imagem de 2026.
• Preço atual por imagem: página de preços.
• Referência completa da API: documentação da hiapi.

Perguntas frequentes

Existe um controle deslizante de intensidade ou força para transferência de estilo? Não. Nenhum dos dois modelos deste guia aceita o campo strength — enviá-lo é tratado como propriedade não reconhecida e rejeitado. A intensidade do estilo é controlada inteiramente pelo grau de especificidade e força da descrição de estilo no prompt.

Como impedir que o modelo altere a pose ou a identidade do meu sujeito? Adicione ao prompt uma cláusula de preservação explícita, nomeando o que deve permanecer inalterado — pose, expressão, composição, posição dos objetos. Quando a restrição é escrita explicitamente em vez de implícita, o modelo é mais conservador na troca de estilo.

Posso preservar automaticamente a proporção exata da imagem de origem? Em grok-imagine-quality/image-to-image, sim — defina aspect_ratio: "auto". Em seedream-5.0-pro/image-to-image não há opção automática; escolha, na enumeração fixa, o valor mais próximo da proporção real da imagem de origem.

Minhas imagens de origem precisam ser URLs públicas? Elas precisam ser acessíveis via HTTPS pelos servidores da hiapi. URLs pré-assinadas de buckets privados funcionam; caminhos localhost ou não autenticados e inacessíveis não funcionam.

Posso gerar várias variantes de estilo a partir de uma foto em paralelo? Sim — cada variante é uma tarefa independente. Faça várias chamadas POST /v1/tasks com os mesmos image_urls e instruções de estilo diferentes, e então faça polling ou use callbacks para cada taskId separadamente.

Qual é a diferença entre troca de estilo e inpainting ou remoção de objetos? A troca de estilo altera a forma como a imagem inteira é renderizada, mantendo o conteúdo inalterado; o inpainting/remoção de objetos altera regiões específicas, mantendo o estilo de renderização inalterado. São modos de prompt diferentes no mesmo tipo de endpoint de imagem para imagem — se o que você realmente precisa é inpainting e remoção de objetos, consulte o guia de inpainting e remoção de objetos.