Documentazione API di GPT Image Hub

Tutti gli endpoint v1, ad eccezione dell'elenco dei modelli, richiedono una chiave API nell'intestazione Authorization. La chiave grezza viene mostrata una volta al momento della creazione; il server memorizza solo un hash.

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

L'endpoint dei modelli restituisce ID modello, fornitori, proporzioni supportate, qualità supportate, limiti di immagini di riferimento e crediti per immagine.

curl https://www.gptimagehub.com/api/v1/models

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

L'endpoint dei crediti restituisce il saldo, il tipo di account e la prossima scadenza dei crediti per l'utente proprietario della chiave API.

curl https://www.gptimagehub.com/api/v1/credits \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Per impostazione predefinita, l'endpoint di generazione delle immagini attende il completamento. Imposta async su true per ricevere subito un ID di generazione e interroga /api/v1/generations/:generationId per ottenere il risultato. I crediti vengono addebitati prima della generazione da parte del fornitore e rimborsati automaticamente se il fornitore non riesce a generare o restituisce meno immagini di quelle richieste.

Richiesta JSON

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a transparent perfume bottle on black marble",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

Attività asincrona

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero-image" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "async": true
  }'

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "queued",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "created_at": "2026-04-30T08:00:00.000Z",
  "images": [],
  "usage": {
    "credits": 0,
    "credits_requested": 7
  },
  "poll_url": "https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id"
}

Richiesta immagine di riferimento

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the reference image and render it as a premium studio product shot" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1" \
  -F "reference_image=@./reference.png"

Risposta

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "succeeded",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "images": [
    {
      "id": "clx_image_id",
      "object": "image",
      "url": "https://cdn.example.com/generations/user/image.png",
      "created_at": "2026-04-30T08:00:00.000Z"
    }
  ],
  "usage": {
    "credits": 7
  },
  "balance": {
    "credits": 113,
    "account_type": "PRO",
    "next_expiration": null
  }
}

Utilizza l'ID restituito dall'endpoint di generazione per recuperare il log salvato e gli URL delle immagini. Le chiavi API possono leggere solo generazioni possedute dallo stesso utente.

curl https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "error": {
    "message": "Invalid request body",
    "code": "invalidRequest"
  }
}

• La generazione sincrona può essere eseguita per un massimo di 800 secondi in produzione.
• n deve essere compreso tra 1 e 4.
• Le immagini di riferimento supportano PNG, JPG, JPEG e WebP. L'intera richiesta, inclusa ogni immagine di riferimento, deve rimanere al di sotto di 4.5MB (mantieni le immagini sotto i 4MB in totale). Le richieste di dimensioni maggiori vengono rifiutate dalla piattaforma di hosting con un 413 in testo normale prima di raggiungere l'API, pertanto ridimensiona o comprimi prima le immagini.
• Il numero massimo di immagini di riferimento è definito dal reference_image_limit di ciascun modello.
• Limiti di frequenza: 60 richieste di generazione al minuto per API key e 120 al minuto per indirizzo IP. Ogni risposta include gli header RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; una risposta 429 include anche Retry-After.
• Per ritentare una generazione in sicurezza, invia un header Idempotency-Key (fino a 120 caratteri). Ripetere la stessa chiave con la medesima API key restituisce la generazione originale invece di addebitarla nuovamente.
• La modalità asincrona restituisce 202 con poll_url. I webhook non sono ancora disponibili.