aisplice

Riferimento API

Immagini: task asincroni

Modelli su questo endpoint (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
Provalo nel Workbench
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Generazione di immagini asincrona — la route usata da tutti i modelli di immagini del catalogo. L'invio restituisce un task_id; interroga l'endpoint di stato, poi leggi gli URL persistenti dei risultati da /content — oppure registra un webhook e salta il polling.

#Parametri della richiesta

  • modelstringobbligatorio

    Un ID di modello di immagini asincrono, per esempio gpt-image-2. I modelli solo sincroni rifiutano questo endpoint.

  • promptstringobbligatorio

    Cosa disegnare.

  • sizestringfacoltativo

    Proporzioni predefinite come "16:9" — il formato della maggior parte dei modelli di immagini; i valori esatti sono nella scheda del modello. Alcuni modelli più vecchi accettano anche WIDTHxHEIGHT.

  • resolutionstringfacoltativo

    Fascia di risoluzione dell'output come "1K", "2K" o "4K", se la scheda del modello la riporta — anche una dimensione della fascia di prezzo.

  • qualitystringfacoltativo

    Livello di qualità del fornitore (per esempio standard / hd) — anche una dimensione della fascia di prezzo.

  • nintegerfacoltativo

    Numero di immagini (la fatturazione si moltiplica per immagine).

  • imagesarrayfacoltativo

    Immagini di riferimento da modificare o da seguire, come URL o data URI. La scheda del modello indica quante ne accetta ogni modello.

  • maskstringfacoltativo

    Ridisegna una zona della prima immagine di riferimento: vedi «Modificare una parte di un’immagine» più sotto. La accettano solo i modelli la cui scheda elenca mask; mask_url è accettato come lo stesso campo.

  • webhook_urlstringfacoltativo

    URL HTTPS chiamato quando il task raggiunge uno stato finale — vedi la guida ai video per il contratto della callback.

  • webhook_secretstringfacoltativo

    Se impostato, le consegne includono X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

I parametri variano in base al modello

Controlla nella scheda del modello quali campi e valori accetta ogni modello. gpt-image-2.5-ext vuole size come proporzione più resolution; una dimensione in pixel come 2560x1088 viene ricondotta alla proporzione e alla risoluzione più vicine (21:9 a 2K). Non permette di controllare background: "auto" viene ignorato, gli altri valori vengono rifiutati. Genera un’immagine per richiesta e non permette di scegliere version: omettilo o invia "flare".

I nomi dei campi possono variare in base alla famiglia di modelli

I payload di stato dei task rispecchiano ciò che riporta il fornitore upstream; considera autorevoli le risposte che ricevi davvero e basati su task_id, status e sull'endpoint /content, che sono stabili tra i fornitori.

#Modificare una parte di un’immagine

Invia l’immagine in images e una mask: viene ridisegnata solo la zona mascherata e il resto dell’immagine resta com’è. Scrivi in prompt cosa deve comparire lì. Oggi accettano una maschera gpt-image-2.5-flare e gpt-image-2.5-sunburst; la scheda del modello la mostra come campo mask.

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

Come creare la maschera

Un PNG con canale alfa: i pixel completamente trasparenti indicano la zona da ridisegnare, il resto viene mantenuto. Deve avere esattamente le dimensioni in pixel della prima immagine di riferimento (non quelle dell’output) e pesare meno di 4 MB. Una maschera per richiesta; con più immagini di riferimento si applica alla prima. Sui modelli gpt-image-2.5 ometti size, così il risultato mantiene le proporzioni dell’immagine.
  • 400 invalid_requestmask è stato inviato senza immagine di riferimento, oppure a un modello che non accetta maschere (gpt-image-2.5-ext risponde "mask is not supported on Ext").

Tabella completa dei codici di errore →

#Errori correlati

  • 404 not_foundPercorso sconosciuto, nome del modello sconosciuto o un task_id scaduto o di un altro account.
  • 401Bearer token non valido o mancante. Su questo percorso non c'è error.code — basati sullo stato.
  • 402 insufficient_user_quotaIl saldo del portafoglio non copre la stima pre-riservata.
  • 429Limitazione per chiave. Corpo vuoto; attendi Retry-After. Un 429 che contiene insufficient_user_quota indica invece un limite di spesa giornaliero.
  • 503 model_not_foundModello sconosciuto, oppure nessun canale funzionante lo serve al momento.

Tabella completa dei codici di errore →

#Esempio di richiesta

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#Risposta

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

Non hai ancora risolto?

Inviaci l'ID richiesta o il messaggio di errore e verificheremo.

PrecedenteMessages (formato Anthropic)SuccessivoVideo