Come chiamare muse-image-1.0/text-to-image tramite l'API HiAPI: curl e Python

Cos'è effettivamente coinvolto in questa integrazione

Su HiAPI, una chiamata text-to-image è una singola richiesta HTTP sincrona: invii un corpo JSON che descrive l'immagine desiderata e la risposta arriva contenendo i dati dell'immagine generata. Questo endpoint non prevede cicli di polling né code di job da gestire: una richiesta, una risposta.

I componenti coinvolti sono pochi:

• La tua chiave API — autentica la richiesta tramite l'header Authorization.
• L'endpoint — il percorso URL fisso di muse-image-1.0/text-to-image sull'URL di base di HiAPI.
• Il corpo JSON — trasporta il tuo prompt e qualsiasi parametro opzionale accettato dal modello.
• Il payload di risposta — restituisce i dati dell'immagine generata, che tu decodifichi o inoltri.

Questa è l'intera superficie dell'interfaccia. Le sezioni seguenti costruiscono la richiesta pezzo per pezzo con curl, poi ripetono lo stesso processo in Python, così puoi verificare ogni parte prima di aggiungere complessità.

Prerequisiti e autenticazione

Prima di inviare la prima richiesta, assicurati di avere:

1. Una chiave API, disponibile dalla dashboard del tuo account HiAPI. Trattala come una password; non inserirla mai nel controllo di versione.
2. Un client HTTP — curl è sufficiente per i test; l'ambiente di destinazione per la versione script è Python 3.8+.
3. L'URL di base dell'API HiAPI, che trovi nella documentazione della dashboard insieme alla chiave.

L'autenticazione utilizza un token Bearer nell'header Authorization. È necessario per ogni richiesta a muse-image-1.0/text-to-image:

Authorization: Bearer $HIAPI_API_KEY

Conserva la chiave in una variabile d'ambiente, non codificarla direttamente nello script:

export HIAPI_API_KEY="your-key-here"

Il percorso dell'endpoint per questo modello è /muse-image-1.0/text-to-image, aggiunto all'URL di base. L'URL di base esatto è documentato nella tua dashboard HiAPI; salvalo anch'esso in una variabile d'ambiente, così puoi cambiare ambiente senza modificare il codice:

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

Una volta impostate queste due variabili, sei pronto a inviare la richiesta.

Una richiesta curl funzionante

Quella che segue è una chiamata minima a muse-image-1.0/text-to-image. Invia un prompt e scrive la risposta JSON grezza su file, così puoi esaminarla prima di scrivere qualsiasi codice di 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

Alcune note sul corpo della richiesta:

• prompt è obbligatorio — è la descrizione testuale che il modello renderizza.
• n è opzionale e controlla il numero di immagini richieste. Se lo ometti, viene accettato il valore predefinito.
• Includi solo i parametri che hai confermato nella documentazione di riferimento dell'API HiAPI per questo modello. Non indovinare campi non documentati; i parametri sconosciuti potrebbero essere rifiutati dalla validazione del server o ignorati silenziosamente.

Se la richiesta ha successo, response.json contiene i dati dell'immagine. Se fallisce, ricevi un corpo di risposta di errore e un codice di stato non 2xx — vedi la sezione sulla gestione degli errori più sotto.

Puoi controllare il codice di stato HTTP senza stampare l'intero corpo della risposta:

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"}'

Implementare la stessa richiesta in Python

La versione Python utilizza requests ed è del tutto identica alla chiamata curl — stesso endpoint, stessi header, stesso corpo della richiesta. Estraila in una funzione riutilizzabile.

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

Due dettagli meritano di essere mantenuti:

• timeout=60 — imposta un timeout esplicito. La generazione di immagini è più lenta di una tipica chiamata API JSON; senza timeout, il tuo processo potrebbe bloccarsi indefinitamente se la connessione si blocca.
• raise_for_status() — espone gli errori HTTP come eccezioni, invece di lasciarti interpretare silenziosamente un corpo di risposta di errore come se fosse un'immagine.

Se già utilizzi httpx o aiohttp, la conversione è diretta: stessi header, stesso corpo JSON. Questa richiesta non dipende da alcuna libreria HTTP specifica.

Leggere la risposta sincrona

Poiché muse-image-1.0/text-to-image è sincrono, i dati dell'immagine arrivano nella stessa risposta — non serve una seconda chiamata per ottenere il risultato. La risposta è JSON; esamina la sua struttura una volta prima di scrivere il parser:

import json

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

Come gestire l'immagine dipende da ciò che contiene la risposta:

Se la risposta contiene dati immagine base64

Decodifica la stringa e scrivi i byte su file:

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 la risposta contiene un URL

Scaricalo con una normale GET — l'URL è già autorizzato per il recupero, quindi non aggiungere la chiave API a un host di terze parti:

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)

I nomi esatti dei campi — b64_json rispetto a url, e la struttura esterna che li contiene — sono definiti nella documentazione di riferimento dell'API HiAPI per questo modello. Stampa la risposta una volta, conferma la struttura, quindi scrivi il codice di conseguenza. Non dare per scontata la struttura di modelli diversi.

In un servizio, non scrivere ciecamente su disco locale: trasmetti i byte in streaming verso l'object storage, oppure passali direttamente a qualsiasi cosa consumi l'immagine (fase di upload, coda, risposta al tuo client). Prima di inoltrarli, verifica che i byte decodificati sembrino un'immagine (controlla i magic number).

Gestire i codici di errore e i tentativi

HiAPI restituisce codici di stato HTTP standard. La regola di triage utile è: se invio di nuovo la stessa richiesta senza modificarla, avrà successo?

Correggi la richiesta — non ritentare

• 400 Bad Request — JSON malformato o parametri non accettati dal modello. Verifica che prompt sia presente e che tu non abbia inventato campi. Correggi il corpo della richiesta; ritentare senza modifiche fallirà allo stesso modo.
• 401 Unauthorized — chiave API mancante o non valida. Verifica che HIAPI_API_KEY sia impostata e non sia stata ruotata.
• 403 Forbidden — la chiave è valida ma non ha accesso a questo endpoint. Controlla i permessi di accesso del tuo account nella dashboard.
• 404 Not Found — percorso errato. Verifica che la stringa dell'endpoint sia esattamente /muse-image-1.0/text-to-image e che l'URL di base sia corretto.
• 422 Unprocessable Entity — JSON ben formato ma semanticamente non valido, ad esempio un valore fuori intervallo. Leggi il messaggio di errore; di solito indica il nome del campo.

Ritentare con backoff

• 429 Too Many Requests — stai subendo un rate limit. Applica un backoff esponenziale e ritenta; se è presente l'header Retry-After, rispettalo.
• Errori 5xx — guasti lato server. Ritenta con backoff esponenziale e un limite massimo (ad esempio tre tentativi), poi arrenditi ed esponi l'errore.

Un ciclo di retry compatto:

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}")

In caso di errore registra sempre il codice di stato e il corpo della risposta di errore. Il messaggio nel corpo ti dirà a quale delle due categorie appartiene un dato errore.

Checklist di produzione prima del rilascio

Alcune abitudini rendono le chiamate a muse-image-1.0/text-to-image prevedibili anche dopo che hanno lasciato il tuo notebook:

• Fissa la struttura della richiesta. Convalida il corpo JSON rispetto ai campi documentati nella documentazione di riferimento dell'API. Se aggiungi un parametro, verifica prima che sia supportato.
• Imposta timeout ovunque. Le chiamate di generazione e qualsiasi download dei dati immagine restituiti richiedono timeout espliciti.
• Distingui le categorie di errore. Separare i fallimenti ritentabili (429, 5xx) da quelli definitivi (400, 401, 403, 404, 422) evita che i tuoi avvisi siano rumorosi e che i retry siano sprecati.
• Registra le informazioni chiave. Se la risposta fornisce un ID richiesta, registralo insieme al codice di stato, alla latenza e alla lunghezza del prompt — senza registrare il prompt stesso se potrebbe contenere testo sensibile.
• Monitora i fattori di costo. La generazione è fatturata sull'output — numero di immagini, dimensioni e frequenza dei retry influiscono sui costi. Evita di ritentare errori definitivi e, quando la cache dei risultati è praticabile, evita di rigenerare.
• Mantieni la chiave sul lato server. Non incorporare mai la chiave API in un browser o in un client mobile per chiamare l'endpoint direttamente.

Con tutto questo, l'integrazione è una piccola e noiosa funzione che puoi chiamare da qualsiasi luogo — esattamente ciò che vuoi. Per l'intera superficie dei parametri e i campi di risposta attuali, consulta la documentazione di riferimento dell'API HiAPI per questo modello.