GPT Image Hub

npx add-mcp 'https://www.gptimagehub.com/mcp'

Quickstart

Create an API key

Sign in, open API Keys in your account, create a key, and store the one-time secret.

Check models and credits

Call /api/v1/models for model capabilities, then /api/v1/credits for your balance.

Submit a generation request

Call /api/v1/images/generations. For long-running calls, set async to true and poll the returned poll_url.

Endpoints

GET /api/v1/models No

List available image models, supported ratios, qualities, and credit cost.

GET /api/v1/credits Bearer

Read the credit balance for the user that owns the API key.

POST /api/v1/images/generations Bearer

Generate images from a prompt, or set async=true to queue a background task.

GET /api/v1/generations/:generationId Bearer

Fetch a generation log and the images saved for that generation.

Authentication

All v1 endpoints except model listing require an API key in the Authorization header. The raw key is shown once at creation time; the server stores only a hash.

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Models

The models endpoint returns model IDs, providers, supported aspect ratios, supported qualities, reference image limits, and credits per image.

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

GPT IMAGE 2 Saver

gpt-image-2-saver

openai

API model ID gpt-image-2-saver

Provider openai

Credits low: 5; medium: 5; high: 5

Default options auto, 1K, medium

Supported qualities low, medium, high, 1K, 2K, 4K

Supported ratios auto, 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 5:4, 4:5, 21:9, 9:21, 2:1, 1:2, 3:1, 1:3

Reference images Max images: 14

Request fields

Field	Value	Notes
model	gpt-image-2-saver	Must be set to this model ID
size	1024x1024	OpenAI-compatible output size, for example auto or 1024x1024
quality	high	Available qualities: auto, low, medium, high
n	1	Image count, from 1 to 4
reference_image	@./reference.png	Only for multipart/form-data; count cannot exceed the model limit

JSON call

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-saver",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

Reference image call

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

Credits

The credits endpoint returns the balance, account type, and upcoming credit expiration for the user that owns the API key.

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

Generate images

The image generation endpoint waits for completion by default. Set async to true to receive a generation id immediately and poll /api/v1/generations/:generationId for the result. Credits are charged before provider generation and refunded automatically when the provider fails or returns fewer images than requested.

JSON request

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

Async task

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

Reference image request

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"

Response

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

Retrieve generation

Use the id returned by the generation endpoint to retrieve its saved log and image URLs. API keys can only read generations owned by the same user.

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

Errors

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

HTTP	code	Description
400	invalidRequest	The request body or parameters are invalid.
401	missingApiKey	The Authorization header is missing.
401	invalidApiKey	The API key does not exist or has been revoked.
401	expiredApiKey	The API key is expired.
401	emailUnverified	The account email is not verified yet. Verify it from the email we sent, then retry.
402	insufficientCredits	The account does not have enough credits.
404	notFound	The requested resource was not found.
429	rateLimited	Too many requests. Wait the number of seconds in the Retry-After header, then retry.
429	freeTierLimited	Accounts with only free sign-up credits can generate up to 10 images per hour.
500	generationFailed	Image generation failed.
503	serviceUnavailable	The service is temporarily unavailable. Retry after the Retry-After header.

Limits

• Synchronous generation can run for up to 800 seconds on production.
• n must be between 1 and 4.
• Reference images support PNG, JPG, JPEG, and WebP. The whole request, including every reference image, must stay under 4.5MB (keep the images under 4MB in total). Larger requests are rejected by the hosting platform with a plain-text 413 before they reach the API, so resize or compress images first.
• The maximum reference image count is defined by each model's reference_image_limit.
• Rate limits: 60 generation requests per minute per API key and 120 per minute per IP address. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers; a 429 also carries Retry-After.
• To retry a generation safely, send an Idempotency-Key header (up to 120 characters). Repeating the same key with the same API key returns the original generation instead of charging again.
• Async mode returns 202 with poll_url. Webhooks are not available yet.