Como chamar muse-image-1.0/text-to-image pela API do HiAPI: curl e Python

O que essa integração realmente envolve

No HiAPI, uma chamada de texto para imagem é uma única requisição HTTP síncrona: você envia um corpo JSON descrevendo a imagem desejada e a resposta retorna com os dados da imagem gerada. Esse endpoint não tem loop de polling nem fila de jobs para gerenciar — uma requisição, uma resposta.

Os componentes envolvidos são poucos:

• Sua chave de API — autentica a requisição por meio do cabeçalho Authorization.
• O endpoint — um caminho de URL fixo para muse-image-1.0/text-to-image na URL base do HiAPI.
• O corpo JSON — carrega seu prompt e quaisquer parâmetros opcionais aceitos pelo modelo.
• O payload de resposta — devolve os dados da imagem gerada, que você decodifica ou encaminha.

Essa é toda a superfície da interface. As seções abaixo constroem a requisição com curl peça por peça e depois repetem o mesmo processo em Python, para que você possa validar cada parte antes de adicionar complexidade.

Pré-requisitos e autenticação

Antes de fazer sua primeira requisição, verifique se você tem:

1. Uma chave de API do painel da sua conta HiAPI. Trate-a como uma senha; nunca a commit no controle de versão.
2. Um cliente HTTP — curl basta para testar; a versão do script tem como alvo Python 3.8+.
3. A URL base da API do HiAPI, que você encontra na documentação do painel junto com a chave.

A autenticação usa um token Bearer no cabeçalho Authorization. Toda requisição para muse-image-1.0/text-to-image precisa dele:

Authorization: Bearer $HIAPI_API_KEY

Armazene a chave em uma variável de ambiente em vez de deixá-la hardcoded no script:

export HIAPI_API_KEY="your-key-here"

O caminho do endpoint para este modelo é /muse-image-1.0/text-to-image, anexado à URL base. A URL base exata está documentada no seu painel HiAPI; guarde-a também em uma variável de ambiente para trocar de ambiente sem alterar o código:

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

Com essas duas variáveis definidas, você está pronto para enviar requisições.

Uma requisição curl que funciona

Abaixo está uma chamada mínima para muse-image-1.0/text-to-image. Ela envia um prompt e grava a resposta JSON bruta em um arquivo, para que você possa inspecioná-la antes de escrever qualquer código de parsing.

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

Alguns pontos a observar sobre o corpo da requisição:

• prompt é obrigatório — é a descrição textual que o modelo renderiza.
• n é opcional e controla quantas imagens você solicita. Omita-o para aceitar o valor padrão.
• Inclua apenas parâmetros que você confirmou na referência da API do HiAPI para este modelo. Não adivinhe campos não documentados; parâmetros desconhecidos podem ser rejeitados pela validação do servidor ou silenciosamente ignorados.

Se a requisição for bem-sucedida, response.json contém os dados da imagem. Se falhar, você recebe um corpo de resposta de erro e um código de status não 2xx — consulte a seção de tratamento de erros abaixo.

Você pode verificar o código de status HTTP sem imprimir o corpo inteiro da resposta:

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

A mesma requisição em Python

A versão em Python usa requests e é idêntica à chamada curl — mesmo endpoint, mesmos cabeçalhos, mesmo corpo. Extraia-a como uma função reutilizável.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

Dois detalhes valem a pena manter:

• timeout=60 — defina um timeout explícito. A geração de imagens é mais lenta que uma chamada típica de API JSON; sem timeout, seu processo pode travar indefinidamente se a conexão estagnar.
• raise_for_status() — expõe erros HTTP como exceções, em vez de deixar você interpretar silenciosamente um corpo de resposta de erro como se fosse imagem.

Se você já usa httpx ou aiohttp, a conversão é direta: mesmos cabeçalhos, mesmo corpo JSON. Essa requisição não depende de nenhuma biblioteca HTTP específica.

Lendo a resposta síncrona

Como muse-image-1.0/text-to-image é síncrono, os dados da imagem chegam na mesma resposta — não há segunda chamada para buscar o resultado. A resposta é JSON; inspecione sua estrutura uma vez antes de escrever o parser:

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

Como lidar com a imagem depende do que a resposta carrega:

Se a resposta contiver dados de imagem em base64

Decodifique a string e grave os bytes em um arquivo:

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

Se a resposta contiver uma URL

Baixe-a com um GET comum — a URL já está autorizada para recuperação, então não anexe a chave de API a hosts de terceiros:

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Os nomes exatos dos campos — b64_json vs url, e a estrutura externa que os envolve — estão definidos na referência da API do HiAPI deste modelo. Imprima a resposta uma vez, confirme a estrutura e depois escreva o código de acordo. Não presuma que a estrutura seja a mesma entre modelos diferentes.

Em um serviço, não grave cegamente no disco local: faça streaming dos bytes para um object storage ou passe-os diretamente para onde a imagem for consumida (etapa de upload, fila, resposta para seu próprio cliente). Antes de encaminhar, verifique se os bytes decodificados parecem uma imagem (cheque os magic bytes).

Lidando com códigos de erro e retentativas

O HiAPI retorna códigos de status HTTP padrão. A regra de triagem útil é: se eu reenviar a mesma requisição sem alterá-la, ela terá sucesso?

Corrija a requisição — não tente de novo

• 400 Bad Request — JSON malformado ou parâmetros que o modelo não aceita. Verifique se prompt existe e se você não inventou campos. Corrija o corpo; repetir como está falhará igualmente.
• 401 Unauthorized — chave de API ausente ou inválida. Verifique se HIAPI_API_KEY está definida e não foi rotacionada.
• 403 Forbidden — a chave é válida, mas não tem acesso a este endpoint. Verifique as permissões de acesso da sua conta no painel.
• 404 Not Found — caminho errado. Confirme se a string do endpoint é exatamente /muse-image-1.0/text-to-image e se a URL base está correta.
• 422 Unprocessable Entity — JSON bem formado, mas semanticamente inválido, por exemplo um valor fora do intervalo. Leia a mensagem de erro; ela geralmente indica o nome do campo.

Retentativas com backoff

• 429 Too Many Requests — você está sendo limitado por rate limit. Aplique backoff exponencial e tente novamente; se houver cabeçalho Retry-After, respeite-o.
• Erros 5xx — falhas do lado do servidor. Tente novamente com backoff exponencial e um limite (por exemplo, três tentativas), depois desista e exponha o erro.

Um loop de retentativa compacto:

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

Sempre registre o código de status e o corpo de resposta de erro em caso de falha. A mensagem no corpo da resposta indica a qual das duas categorias o erro pertence.

Checklist de produção antes de publicar

Alguns hábitos mantêm as chamadas a muse-image-1.0/text-to-image previsíveis mesmo fora do seu notebook:

• Fixe a estrutura da requisição. Valide o corpo JSON contra os campos documentados na referência da API. Se adicionar um parâmetro, confirme primeiro que ele é suportado.
• Defina timeouts em todos os lugares. Chamadas de geração e qualquer download dos dados de imagem retornados precisam de timeout explícito.
• Diferencie as categorias de erro. Separe falhas retentáveis (429, 5xx) das definitivas (400, 401, 403, 404, 422), para que seus alertas não fiquem ruidosos e as retentativas não sejam desperdiçadas.
• Registre informações-chave. Se a resposta fornecer um request ID, registre-o, além do código de status, da latência e do comprimento do prompt — mas não registre o próprio prompt se ele puder conter texto sensível.
• Atenção aos fatores de custo. A geração é cobrada por saída — a quantidade de imagens, o tamanho e a frequência das suas retentativas afetam o custo. Evite retentativas em erros definitivos e evite regerar quando o cache de resultados for viável.
• Mantenha as chaves no servidor. Nunca embuta a chave de API em navegadores ou clientes móveis para chamar o endpoint diretamente.

Com isso, a integração é uma função pequena e sem surpresas que você pode chamar de qualquer lugar — exatamente o que você quer. Para a superfície completa de parâmetros e os campos de resposta atuais, consulte a referência da API do HiAPI deste modelo.