Início Rápido do Qwen Image Edit para Editar Imagens com Instruções de Texto

A API Qwen Image Edit na Novita AI modifica uma imagem existente usando uma instrução em linguagem natural, alimentada pelo modelo Qwen-Image de 20B. Este início rápido cobre o fluxo assíncrono completo: envie uma solicitação de edição com sua imagem de origem e prompt, receba um ID de tarefa, faça polling até que a edição seja concluída e recupere a URL da imagem editada. O endpoint é POST https://api.novita.ai/v3/async/qwen-image-edit.

Índice

Quando Usar Este Início Rápido

Use este guia quando precisar:

• Modificar uma imagem existente através de uma instrução de texto — alterar fundos, trocar estilos, remover elementos, girar objetos ou ajustar roupas sem reconstruir a imagem do zero.
• Manter regiões não tocadas intactas enquanto aplica edições direcionadas. A arquitetura de caminho duplo do modelo (Qwen2.5-VL para compreensão semântica + codificador VAE para preservação de aparência) é especificamente projetada para evitar que as edições se espalhem para áreas que você não descreveu.
• Editar texto em imagens com precisão. O Qwen Image Edit lida com substituições bilíngues em inglês e chinês em placas, cartazes e ativos de marca — preservando fonte, tamanho e estilo visual ao redor de uma forma que a maioria dos geradores de imagem falha.

Se você está gerando uma nova imagem a partir de um prompt apenas (sem imagem de entrada necessária), use o Início Rápido do Qwen Image txt2img em vez disso. Para uma visão geral completa das capacidades, benchmarks e arquitetura do modelo, veja o post de lançamento do Qwen-Image na Novita AI.

Passo 1: Obtenha Sua Chave de API da Novita

Crie uma conta na Novita AI e navegue até gerenciamento de chaves de API. Gere uma chave e armazene-a como uma variável de ambiente antes de executar qualquer um dos exemplos de código abaixo:

export NOVITA_API_KEY="sua_chave_api_aqui"

Mantenha a chave fora do código do lado do cliente, pacotes frontend e controle de versão. Se a chave for comprometida, rotacione-a na mesma página de configurações.

Passo 2: Confirme o Endpoint e o Modelo

Item	Valor
Endpoint de edição	POST https://api.novita.ai/v3/async/qwen-image-edit
Endpoint de polling de resultado	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Modelo	Qwen Image Edit (20B MMDiT, arquitetura de caminho duplo)
Documentação da API	Referência Qwen Image Edit da Novita AI

A API é assíncrona. A chamada de edição retorna um task_id imediatamente; você faz polling no endpoint de resultado até que o status seja TASK_STATUS_SUCCEED. Este é o mesmo padrão de duas etapas usado por todos os endpoints de geração de imagem da Novita AI, incluindo o endpoint txt2img.

O preço é $0,02 por imagem. Verifique a taxa atual na página de preços da Novita AI antes de construir um modelo de custo.

Passo 3: Envie sua Primeira Solicitação de Edição

POST para o endpoint de edição com sua imagem de origem e a instrução de edição:

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Altere o fundo para uma paisagem de montanha nevada",
    "image": "https://example.com/meu-retrato.jpg"
  }'

Uma resposta 200 bem-sucedida retorna:

{
  "task_id": "abc123..."
}

Salve o task_id — você precisa dele para recuperar a imagem editada.

Passo 4: Faça Polling para Obter Seu Resultado

GET no endpoint de resultado da tarefa com o task_id como parâmetro de consulta:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Continue fazendo polling até que o campo task_status seja TASK_STATUS_SUCCEED:

{
  "task_status": "TASK_STATUS_SUCCEED",
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "86400",
      "image_type": "JPEG"
    }
  ]
}

A image_url expira após a janela TTL (tipicamente 24 horas). Baixe e armazene o resultado em seu próprio armazenamento de objetos se precisar de acesso de longo prazo.

Valores de status a serem tratados:

Status	Significado
TASK_STATUS_QUEUED	A solicitação está aguardando na fila; continue fazendo polling
TASK_STATUS_PROCESSING	A edição está em andamento; continue fazendo polling
TASK_STATUS_SUCCEED	Concluída; leia a imagem editada de images[0].image_url
TASK_STATUS_FAILED	A geração falhou; verifique o campo de erro para a razão

Passo 5: Verifique Preços, Limites e Erros Comuns

Preço: $0,02 por imagem (verifique na página de preços).

Limites de taxa: Consulte a referência da API para limites de taxa atuais. Se você encontrar um 429, reduza sua taxa de solicitação e implemente backoff exponencial nas tentativas.

Erros HTTP comuns:

Código de status	Causa provável
400	Corpo da solicitação malformado — faltando prompt ou image, formato de imagem inválido ou tamanho de entrada não suportado
401	Chave de API ausente ou inválida — confirme o formato Authorization: Bearer <key>
429	Limite de taxa excedido — adicione lógica de backoff e repetição
500	Erro do lado do servidor — tente novamente após um breve atraso

Se o status da tarefa for TASK_STATUS_FAILED, a resposta geralmente inclui uma mensagem de erro. Razões comuns incluem formatos de imagem não suportados, imagens que excedem limites de tamanho ou prompts que acionam filtros de segurança de conteúdo.

Exemplo em Python

Este script envia uma solicitação de edição, faz polling até a conclusão e imprime a URL da imagem de saída:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai/v3/async"


def submit_edit(image: str, prompt: str, seed: int | None = None) -> str:
    payload: dict = {"prompt": prompt, "image": image}
    if seed is not None:
        payload["seed"] = seed
    response = requests.post(
        f"{BASE_URL}/qwen-image-edit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, timeout: float = 120.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("task_status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Tarefa de edição falhou: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Tarefa {task_id} não foi concluída em {timeout}s")


if __name__ == "__main__":
    task_id = submit_edit(
        image="https://example.com/foto-produto.jpg",
        prompt="Troque a jaqueta para uma jaqueta de couro vermelha, preserve o fundo",
    )
    print(f"ID da tarefa: {task_id}")

    result = poll_result(task_id)
    for img in result["images"]:
        print(img["image_url"])

Exemplo em cURL

Fluxo de dois comandos usando jq para análise JSON:

#!/bin/bash
# Passo 1: envie a solicitação de edição
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Converta para estilo de pintura em aquarela, preserve o assunto e a composição",
    "image": "https://example.com/paisagem.jpg"
  }' | jq -r '.task_id')

echo "ID da tarefa: $TASK_ID"

# Passo 2: faça polling até a conclusão
while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task_status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.images[].image_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "Tarefa falhou:"
    echo "$RESULT" | jq .
    exit 1
  fi
  sleep 2
done

Instale o jq com apt install jq (Debian/Ubuntu) ou brew install jq (macOS) se ainda não estiver presente.

Parâmetros Chave

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
prompt	string	Sim	—	Instrução em linguagem natural descrevendo a edição desejada
image	string	Sim	—	Imagem de origem como URL ou string codificada em base64
seed	integer	Não	aleatório	Semente fixa para saídas reproduzíveis em múltiplas execuções
output_format	string	Não	jpeg	Formato de saída — consulte a documentação da API para valores aceitos

Escrevendo prompts eficazes: Especificidade importa. “Altere o texto no outdoor para ‘Summer Sale’” dá ao modelo uma tarefa clara e delimitada. “Melhore a imagem” não. Quando você deseja alterar um elemento e deixar todo o resto intacto, nomeie o que deseja preservar: “troque a cor da jaqueta para vermelho, mantenha o fundo e o rosto inalterados.” Isso ajuda o caminho do codificador VAE a fazer seu trabalho de travar regiões não tocadas.

Usando seed para iteração: Ao ajustar um prompt, fixar a semente permite comparar edições diretamente — a variação na saída vem da sua mudança no prompt, não da amostragem aleatória. Quando encontrar um prompt que funciona, remova a restrição de semente se quiser diversidade de saída em múltiplas edições.

Casos de Uso Típicos

Substituição de fundo: “Substitua o fundo por um estúdio branco minimalista” — o Qwen Image Edit preserva as bordas e a iluminação do assunto enquanto troca o ambiente. Funciona de forma confiável quando o assunto tem um limite claro contra o fundo original.

Texto em imagens: Substituição de letreiros de lojas, manchetes de cartazes ou rótulos de produtos com novo texto — incluindo chinês e inglês. O modelo preserva o estilo da fonte e o contexto visual ao redor melhor do que abordagens de inpainting generativas que tendem a regenerar toda a região.

Conversão de estilo: “Converta para estilo de pintura a óleo” ou “faça isso parecer um esboço a lápis” aplicado a uma imagem de origem em vez de descrito do zero. O caminho do codificador VAE preserva a composição original e o posicionamento dos objetos enquanto o prompt conduz a transformação de estilo.

Alterações em nível de objeto: Troca de roupas, alteração de cores de itens específicos, adição ou remoção de acessórios. A instrução deve nomear o elemento específico que está sendo alterado para evitar que a edição afete regiões adjacentes.

Conversão de propriedade intelectual e rotação de objetos: O modelo suporta alterações de síntese de vista (por exemplo, girar um objeto para mostrar um ângulo diferente) e conversão entre estilos visuais para imagens de personagens ou produtos — casos de uso documentados na visão geral do Qwen-Image-Edit na Novita AI.

Solução de Problemas

A saída parece inalterada: A instrução provavelmente é pouco especificada. Torne-a mais explícita sobre qual elemento deve ser alvo: “Altere a cor do carro de azul para vermelho” em vez de “torne-o vermelho.”

Edições indesejadas se espalham para áreas não intencionais: Para edições locais altamente específicas, inclua linguagem de preservação explícita em seu prompt: “altere apenas X, deixe Y intacto.” Prompts muito abertos dão ao modelo latitude para reinterpretar toda a composição.

Tarefa concluída, mas a URL da imagem retorna 403 ou 404: O campo image_url_ttl (em segundos) informa por quanto tempo a URL é válida. Se você fizer polling da URL após o TTL, a URL expirou. Baixe a imagem imediatamente após um polling bem-sucedido.

401 Não Autorizado: Verifique se o formato do cabeçalho Authorization é exatamente Bearer <key> com um espaço após Bearer. Confirme se a chave está ativa e não foi revogada no console Novita AI.

Tarefas expirando consistentemente: A edição de imagens leva mais tempo do que a geração de texto — tipicamente 15–60 segundos sob carga normal. Se as tarefas excederem rotineiramente seu timeout, aumente a janela de polling antes de tratar como uma falha.

FAQ

A imagem de origem permanece nos servidores da Novita?

Sua imagem é enviada para a API da Novita AI via HTTPS e processada na infraestrutura deles. Revise as políticas de tratamento de dados da Novita AI antes de enviar imagens com informações pessoais sensíveis, dados de saúde privados ou conteúdo confidencial.

Posso usar imagens codificadas em base64 em vez de uma URL?

Sim. Passe a string base64 bruta no campo image. Consulte a referência da API para quaisquer limites de tamanho em payloads base64.

Existe um parâmetro de semente para consistência?

Sim — o parâmetro opcional seed fixa o estado aleatório para que o mesmo prompt e imagem produzam resultados consistentes. Útil para iterar na redação do prompt sem ruído na saída devido a reamostragem.

Posso usar este endpoint para trabalhos em lote?

Sim. Envie múltiplas solicitações de edição em paralelo e colete os valores task_id, depois faça polling concorrente. Cada solicitação é independente.

Qual é a diferença entre este e o endpoint Qwen Image txt2img?

O endpoint de edição requer uma imagem de origem e produz uma versão modificada dela. O endpoint txt2img gera uma imagem inteiramente a partir de um prompt de texto — sem imagem de entrada. Use o endpoint de edição quando você tem conteúdo existente que deseja modificar; use txt2img quando estiver criando do zero.

Artigos Recomendados

• Início Rápido Qwen Image Texto-para-Imagem para Gerar Imagens a partir de Prompts
• Qwen-Image-Edit na Novita AI: Edição de Nível Profissional por Apenas $0,02
• Novita AI Agora Oferece Qwen-Image: Modelo Avançado de Texto-para-Imagem de 20B