API v1 Developer Documentation

PromptGPT API Reference (v1)

The PromptGPT API provides programmatic access to an advanced prompt engineering pipeline. Use this API to improve raw user inputs, generate targeted Midjourney/Flux parameters, or extract photorealistic prompts from uploaded images with sub-95ms response times.

🤖 AI Builders & LLM Hub Ready-to-Paste Prompts

Build with AI Coding Tools & LLMs

Creating your app using Cursor, Windsurf, v0.dev, Bolt.new, Claude, or calling OpenAI / Claude / Gemini? Skip reading manual specs. Simply copy the ready-made prompt or middleware below and paste it into your AI assistant or codebase.

Prompt for Cursor Composer / Windsurf Cascade / Claude Code

How to use:

  1. Open Cursor Composer (Cmd+I or Ctrl+I) or Windsurf Cascade in your project.
  2. Click Copy Prompt above and paste it into the chat.
  3. Your AI coding assistant will automatically write the typed client module, error handling, and integrate it into your LLM route!
I want to integrate PromptGPT API (https://promptgpt.io) into this project as a prompt enhancement middleware before sending queries to our primary LLM.

API Specification:
- Endpoint: POST https://promptgpt.io/api/v1/prompts/optimize
- Headers:
  - "Authorization": "Bearer " + process.env.PROMPTGPT_API_KEY
  - "Content-Type": "application/json"
- Request Body Schema:
  {
    "prompt": "",
    "target_model": "chatgpt" // options: "chatgpt", "claude", "gemini", "midjourney", "flux", "universal"
  }
- Successful Response Schema (200 OK):
  {
    "success": true,
    "data": {
      "original_prompt": string,
      "optimized_prompt": string,
      "optimization_score": number
    },
    "usage": { "credits_deducted": 1, "credits_remaining": number, "latency_ms": number }
  }

Implementation Instructions:
1. Create a reusable client module `lib/promptgpt.ts` (or `utils/promptgpt.py` if Python).
2. Export an async function `optimizeUserPrompt(prompt: string, targetModel?: string): Promise` that calls this API.
3. Add resilient fallback logic: if PromptGPT API times out or fails (e.g., network error or rate limit), fail open and silently return the original raw prompt so user experience is never interrupted.
4. Add `PROMPTGPT_API_KEY=pgpt_live_your_key_here` to `.env.example`.
5. Integrate this `optimizeUserPrompt()` function right before our OpenAI / Anthropic LLM completion call.

Base URL

All production API requests must be transmitted securely over HTTPS.

https://promptgpt.io/api/v1 REST / JSON

Authentication

Authenticate all requests using an API secret key passed in the standard HTTP Authorization header:

Authorization: Bearer pgpt_live_YOUR_SECRET_KEY
Security Notice: Keep your secret keys safe! Never commit them to client-side code, GitHub, or public frontend apps. Use environment variables on your backend.

Rate Limits

Rate limits operate on a 60-second sliding window based on your plan tier. The API includes rate limit metadata headers in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
Retry-After: 60 (Sent on 429 status)
POST

/prompts/optimize

Takes an unpolished user prompt, analyzes the domain, applies category-native prompt engineering frameworks, and generates a structured, high-performing output.

Request Body Parameters

Field Type Required Description
prompt string Required The raw text prompt (max 4,000 characters).
target_model string Optional midjourney | chatgpt | claude | gemini | flux (default: universal)
negative_prompt boolean Optional Whether to include exclusion / negative prompt parameters.

Example Response (200 OK)

{
  "success": true,
  "data": {
    "original_prompt": "cyberpunk warrior in rain",
    "optimized_prompt": "Cinematic 8k portrait of a cybernetic warrior standing in drenched neon alley, reflective rain puddles, high-tech carbon-fiber visor, volumetric lighting, 85mm f/1.4 lens --ar 16:9 --v 6.0",
    "negative_prompt": "blurry, low resolution, artifacts, distorted anatomy, plastic skin",
    "target_model": "midjourney",
    "optimization_score": 94,
    "character_count": 214
  },
  "usage": {
    "credits_deducted": 1,
    "credits_remaining": 1499,
    "latency_ms": 84
  }
}
POST

/prompts/generate

Creates an authoritative, expert-level prompt from a topic keyword.

// Request
{
  "topic": "luxury architectural villa with glass facade",
  "mode": "advanced",
  "expertise": "designer",
  "target_model": "chatgpt"
}
POST

/prompts/image-to-prompt

Reverse-engineers visual styles, textures, and camera framing from an image URL or Base64 payload.

// Request
{
  "image_url": "https://example.com/art.jpg",
  "mime_type": "image/jpeg"
}

Error Handling

All error responses follow a uniform JSON schema:

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient API credits. Required: 1, Available: 0. Please top up at https://promptgpt.io/api#pricing"
  }
}
HTTP Code Error Code Description
401 invalid_api_key Key is missing, incorrect, or revoked.
402 insufficient_credits Account API credit balance is depleted.
422 validation_error Required payload parameter missing or too long.
429 rate_limit_exceeded Request volume exceeded per-minute quota.