Add complete API reference docs

docs/api-reference.json

@@ -0,0 +1,442 @@
+{
+  "_info": {
+    "base_url": "https://akash1313-selfapi-v2.hf.space",
+    "auth": "Authorization: Bearer YOUR_API_KEY",
+    "note": "All endpoints require API_KEY as Bearer token. Replace BASE with base_url in curl examples."
+  },
+
+  "chatgpt": {
+    "health": {
+      "method": "GET",
+      "url": "/gpt/health",
+      "response": { "ok": true, "mode": "chatgpt-api-bridge", "extensionConnected": true, "extension": {} }
+    },
+    "cookies_status": {
+      "method": "GET",
+      "url": "/gpt/api/cookies/status",
+      "response": { "ok": true, "has_cookies": true, "last_sync": "2026-06-16T05:00:00Z", "cookie_header_len": 1234, "extension_connected": true }
+    },
+    "chat": {
+      "method": "GET or POST",
+      "url": "/gpt/api/chat",
+      "type": "json",
+      "body": {
+        "prompt": "hello (required)",
+        "wait_for_response": true,
+        "conversation_id": "xxx or 'new' to start fresh (optional)",
+        "model": "gpt-5 (optional, uses default)",
+        "thinking_effort": "low|medium|high (optional)"
+      },
+      "note": "GET also works with query params: ?prompt=hello&model=gpt-5&conversation_id=new",
+      "response": {
+        "ok": true,
+        "response": "Hi! How can I help?",
+        "conversation_id": "xxx-xxx",
+        "images": ["output/prompt_name.png"]
+      }
+    },
+    "chat_with_image_edit": {
+      "method": "POST",
+      "url": "/gpt/api/chat/edit",
+      "type": "multipart/form-data",
+      "body": {
+        "prompt": "edit this image, make it cartoon style (required)",
+        "image": "<file upload> (optional)",
+        "conversation_id": "xxx or 'new' (optional)",
+        "model": "gpt-5 (optional)"
+      },
+      "note": "Upload image + prompt for ChatGPT image editing (DALL-E). Image is uploaded to ChatGPT then sent with prompt.",
+      "response": {
+        "ok": true,
+        "response": "Here's your edited image...",
+        "conversation_id": "xxx-xxx",
+        "images": ["output/cartoon_style_fileID.png"]
+      }
+    },
+    "bulk_chat": {
+      "method": "POST",
+      "url": "/gpt/api/chat/bulk",
+      "type": "json",
+      "body": {
+        "prompts": ["question 1", "question 2", "question 3"],
+        "delay_seconds": 2
+      },
+      "response": {
+        "ok": true,
+        "count": 3,
+        "results": [
+          { "prompt": "question 1", "response": "answer 1" },
+          { "prompt": "question 2", "response": "answer 2" }
+        ]
+      }
+    },
+    "openai_compatible": {
+      "method": "POST",
+      "url": "/gpt/v1/chat/completions",
+      "type": "json",
+      "body": {
+        "model": "gpt-5",
+        "messages": [
+          { "role": "system", "content": "You are helpful" },
+          { "role": "user", "content": "hello" }
+        ],
+        "stream": false
+      },
+      "note": "Drop-in replacement for OpenAI API. Use as base_url in OpenAI SDKs.",
+      "response": {
+        "id": "chatcmpl-xxx",
+        "object": "chat.completion",
+        "created": 1781588072,
+        "model": "gpt-5",
+        "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" }]
+      }
+    },
+    "download_image": {
+      "method": "GET",
+      "url": "/gpt/api/download?file_id=FILE_ID&prompt=optional_prompt",
+      "note": "Download ChatGPT generated images by file_id. Auto-saved to output/ folder.",
+      "response": "binary image/png"
+    },
+    "get_conversation": {
+      "method": "GET",
+      "url": "/gpt/api/conversation?conversation_id=CONV_ID",
+      "note": "Fetch full conversation data from ChatGPT backend",
+      "response": "raw ChatGPT conversation JSON"
+    },
+    "sniffs": {
+      "method": "GET or DELETE",
+      "url": "/gpt/api/sniffs",
+      "note": "GET: list sniffed requests. DELETE: clear sniffs.",
+      "response": { "ok": true, "count": 5, "sniffs": [] }
+    },
+    "reload_extension": {
+      "method": "GET",
+      "url": "/gpt/api/ext/reload",
+      "note": "Force reload Chrome extension files from disk",
+      "response": { "ok": true, "message": "reload request sent" }
+    }
+  },
+
+  "gemini": {
+    "status": {
+      "method": "GET",
+      "url": "/gemini/status",
+      "query": "?user_id=optional",
+      "response_active": { "session_id": "127.0.0.1", "initialized": true, "conversation_id": "c_xxx", "expired": false },
+      "response_inactive": { "session_id": "127.0.0.1", "active": false }
+    },
+    "chat_text_form": {
+      "method": "POST",
+      "url": "/gemini/chat",
+      "type": "application/x-www-form-urlencoded",
+      "body": {
+        "prompt": "hello (required)",
+        "new_chat": "true|false (optional, default false)",
+        "user_id": "session_id (optional, defaults to IP)",
+        "stream": "true|false (optional, default false)"
+      },
+      "response": {
+        "text": "Hey there! How's it going?",
+        "conversation_id": "c_xxx",
+        "response_id": "r_xxx",
+        "choice_id": "rc_xxx",
+        "images": null,
+        "videos": null,
+        "elapsed": 4.5
+      }
+    },
+    "chat_text_json": {
+      "method": "POST",
+      "url": "/gemini/chat",
+      "type": "application/json",
+      "body": {
+        "prompt": "hello",
+        "new_chat": true,
+        "user_id": "optional",
+        "stream": false
+      },
+      "note": "Same endpoint, accepts JSON too"
+    },
+    "chat_with_images": {
+      "method": "POST",
+      "url": "/gemini/chat",
+      "type": "multipart/form-data",
+      "body": {
+        "prompt": "describe this image",
+        "new_chat": "true",
+        "image": "<file1>",
+        "images": "<file2>, <file3>"
+      },
+      "note": "Max 10 images. Field name 'image' or 'images' both work. Supports image understanding + generation.",
+      "response": {
+        "text": "This image shows...",
+        "conversation_id": "c_xxx",
+        "response_id": "r_xxx",
+        "images": ["http://host/output/img_r_xxx_0.png"],
+        "videos": ["http://host/output/vid_r_xxx_0.mp4"],
+        "elapsed": 5.2
+      }
+    },
+    "chat_stream": {
+      "method": "POST",
+      "url": "/gemini/chat",
+      "type": "form or json",
+      "body": { "prompt": "write a long poem", "stream": true },
+      "note": "SSE stream. Each chunk: data: {\"text\":\"chunk\"}. Final: full response JSON then data: [DONE]. Text-only mode.",
+      "response_stream": [
+        "data: {\"text\":\"Once upon\"}",
+        "data: {\"text\":\" a time\"}",
+        "data: {full response JSON with images/videos}",
+        "data: [DONE]"
+      ]
+    },
+    "openai_compatible": {
+      "method": "POST",
+      "url": "/gemini/v1/chat/completions",
+      "type": "json",
+      "body": {
+        "model": "gemini-2.5-flash (optional, any name works)",
+        "messages": [{ "role": "user", "content": "hello" }],
+        "stream": false
+      },
+      "note": "OpenAI-compatible drop-in. Supports streaming (SSE) too. Use as base_url in any OpenAI SDK.",
+      "response": {
+        "id": "chatcmpl-xxx",
+        "object": "chat.completion",
+        "created": 1781588072,
+        "model": "gemini-2.5-flash",
+        "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" }]
+      },
+      "response_stream": [
+        "data: {\"id\":\"chatcmpl-xxx\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"}}]}",
+        "data: {\"id\":\"chatcmpl-xxx\",\"choices\":[{\"index\":0,\"finish_reason\":\"stop\"}]}",
+        "data: [DONE]"
+      ]
+    },
+    "music": {
+      "method": "POST",
+      "url": "/gemini/music",
+      "type": "json",
+      "body": {
+        "prompt": "lofi chill hip hop beats (required)",
+        "user_id": "optional",
+        "new_chat": false
+      },
+      "note": "Generates music via Gemini. Downloads tracks locally. Returns local URLs.",
+      "response": {
+        "text": "Here's your music...",
+        "music": [{ "title": "Lofi Chill", "download_url": "original_url", "local_path": "http://host/output/music_xxx_0.mp3", "duration": "3:45" }],
+        "conversation_id": "c_xxx"
+      }
+    },
+    "reset": {
+      "method": "POST",
+      "url": "/gemini/reset",
+      "type": "json",
+      "body": { "user_id": "optional" },
+      "response": { "status": "success", "message": "Session reset" }
+    },
+    "get_output": {
+      "method": "GET",
+      "url": "/gemini/output/{filename}",
+      "note": "Download generated images/videos/music from output folder",
+      "response": "binary file"
+    }
+  },
+
+  "flow": {
+    "health": {
+      "method": "GET",
+      "url": "/flow/health",
+      "response": { "status": "healthy", "extension_connected": true, "has_flow_key": true }
+    },
+    "generate_video_t2v": {
+      "method": "POST",
+      "url": "/flow/generate/video",
+      "type": "json",
+      "body": {
+        "prompt": "a cat surfing a wave, cinematic (required)",
+        "aspect": "portrait|landscape (default: portrait)",
+        "duration": "4|6|8|10 (default: 10)",
+        "count": "1-4 (default: 1)",
+        "project_id": "optional"
+      },
+      "note": "Text-to-Video. Polls until complete, downloads automatically.",
+      "response": {
+        "success": true,
+        "outputs": [{ "media_id": "xxx", "filename": "omni_xxx_1.mp4", "download_url": "/download/omni_xxx_1.mp4" }]
+      }
+    },
+    "generate_video_i2v": {
+      "method": "POST",
+      "url": "/flow/generate/video",
+      "type": "json",
+      "body": {
+        "prompt": "animate this photo",
+        "start": "image file path OR media_id OR base64 data",
+        "aspect": "portrait",
+        "duration": 8
+      },
+      "note": "Image-to-Video. Pass start image as file path, media_id, or base64."
+    },
+    "generate_video_fl": {
+      "method": "POST",
+      "url": "/flow/generate/video",
+      "type": "json",
+      "body": {
+        "prompt": "smooth transition",
+        "start": "start frame image (path/media_id/base64)",
+        "end": "end frame image (path/media_id/base64)",
+        "duration": 8
+      },
+      "note": "First-Last frame mode. Generates video between two keyframes."
+    },
+    "generate_video_r2v": {
+      "method": "POST",
+      "url": "/flow/generate/video",
+      "type": "json",
+      "body": {
+        "prompt": "make a video in this style",
+        "ref": ["reference_image_1 (path/media_id/base64)", "reference_image_2"],
+        "duration": 8
+      },
+      "note": "Reference-to-Video. Uses reference images for style/content guidance."
+    },
+    "generate_video_v2v": {
+      "method": "POST",
+      "url": "/flow/generate/video",
+      "type": "json",
+      "body": {
+        "prompt": "restyle as anime",
+        "edit": "existing_video_media_id",
+        "duration": 10
+      },
+      "note": "Video-to-Video editing. Restyle/edit existing video."
+    },
+    "edit_video": {
+      "method": "POST",
+      "url": "/flow/edit/video",
+      "type": "json",
+      "body": {
+        "prompt": "make it look like watercolor painting",
+        "video_media_id": "xxx (required)",
+        "aspect": "portrait",
+        "fps": 24,
+        "duration": 10,
+        "start_frame": 0,
+        "end_frame": null,
+        "download": false
+      },
+      "note": "Advanced V2V edit with frame control. Set download=true for direct binary response.",
+      "response": {
+        "success": true,
+        "outputs": [{ "media_id": "xxx", "filename": "edit_xxx_1.mp4", "download_url": "/download/edit_xxx_1.mp4" }]
+      }
+    },
+    "generate_image_t2i": {
+      "method": "POST",
+      "url": "/flow/generate/image",
+      "type": "json",
+      "body": {
+        "prompt": "neon city at night (required)",
+        "aspect": "portrait|landscape|square|4x3|3x4 (default: portrait)",
+        "count": "1-4 (default: 1)",
+        "project_id": "optional"
+      },
+      "note": "Text-to-Image generation.",
+      "response": {
+        "success": true,
+        "outputs": [{ "media_id": "xxx", "filename": "img_xxx_1.png", "download_url": "/download/img_xxx_1.png", "remote_url": "https://...", "downloaded": true }]
+      }
+    },
+    "generate_image_i2i": {
+      "method": "POST",
+      "url": "/flow/generate/image",
+      "type": "json",
+      "body": {
+        "prompt": "make it look vintage",
+        "ref": ["reference_image (path/media_id/base64)"],
+        "aspect": "square",
+        "count": 1
+      },
+      "note": "Image-to-Image. Uses reference images for style transfer."
+    },
+    "upload_image": {
+      "method": "POST",
+      "url": "/flow/upload/image",
+      "type": "multipart/form-data",
+      "body": {
+        "file": "<file upload> (OR)",
+        "path": "/local/path/to/image.jpg (OR)",
+        "project_id": "optional"
+      },
+      "note": "Upload image to Google Flow. Returns media_id for use in generation.",
+      "response": { "success": true, "media_id": "xxx" }
+    },
+    "upload_video": {
+      "method": "POST",
+      "url": "/flow/upload/video",
+      "type": "multipart/form-data",
+      "body": {
+        "file": "<file upload> (OR)",
+        "path": "/local/path/to/video.mp4 (OR)",
+        "project_id": "optional"
+      },
+      "note": "Upload video to Google Flow. Returns media_id for use in V2V editing.",
+      "response": { "success": true, "media_id": "xxx", "data": {} }
+    },
+    "download": {
+      "method": "GET",
+      "url": "/flow/download/{filename}",
+      "note": "Download any generated file from output folder. Supports mp4, png, jpg.",
+      "response": "binary file with correct content-type"
+    }
+  },
+
+  "curl_examples": {
+    "_note": "Replace BASE with https://akash1313-selfapi-v2.hf.space and KEY with your API key",
+
+    "gpt_health":             "curl -H 'Authorization: Bearer KEY' BASE/gpt/health",
+    "gpt_chat":               "curl -X POST BASE/gpt/api/chat -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"hello\",\"wait_for_response\":true}'",
+    "gpt_chat_with_model":    "curl -X POST BASE/gpt/api/chat -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"hello\",\"model\":\"gpt-5\",\"thinking_effort\":\"high\"}'",
+    "gpt_chat_new_convo":     "curl -X POST BASE/gpt/api/chat -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"hello\",\"conversation_id\":\"new\"}'",
+    "gpt_image_edit":         "curl -X POST BASE/gpt/api/chat/edit -H 'Authorization: Bearer KEY' -F 'prompt=make this cartoon style' -F 'image=@photo.jpg'",
+    "gpt_bulk":               "curl -X POST BASE/gpt/api/chat/bulk -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompts\":[\"q1\",\"q2\"],\"delay_seconds\":2}'",
+    "gpt_openai":             "curl -X POST BASE/gpt/v1/chat/completions -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"model\":\"gpt-5\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'",
+    "gpt_download":           "curl -H 'Authorization: Bearer KEY' 'BASE/gpt/api/download?file_id=FILE_ID'",
+
+    "gemini_status":          "curl -H 'Authorization: Bearer KEY' BASE/gemini/status",
+    "gemini_chat_form":       "curl -X POST BASE/gemini/chat -H 'Authorization: Bearer KEY' -d 'prompt=hello&new_chat=true'",
+    "gemini_chat_json":       "curl -X POST BASE/gemini/chat -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"hello\",\"new_chat\":true}'",
+    "gemini_chat_continue":   "curl -X POST BASE/gemini/chat -H 'Authorization: Bearer KEY' -d 'prompt=tell me more&new_chat=false'",
+    "gemini_with_image":      "curl -X POST BASE/gemini/chat -H 'Authorization: Bearer KEY' -F 'prompt=describe this' -F 'new_chat=true' -F 'image=@photo.jpg'",
+    "gemini_multi_images":    "curl -X POST BASE/gemini/chat -H 'Authorization: Bearer KEY' -F 'prompt=compare these' -F 'images=@img1.jpg' -F 'images=@img2.jpg'",
+    "gemini_stream":          "curl -X POST BASE/gemini/chat -H 'Authorization: Bearer KEY' -d 'prompt=write a poem&stream=true'",
+    "gemini_openai":          "curl -X POST BASE/gemini/v1/chat/completions -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"model\":\"gemini-2.5-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'",
+    "gemini_openai_stream":   "curl -X POST BASE/gemini/v1/chat/completions -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"model\":\"gemini\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}],\"stream\":true}'",
+    "gemini_music":           "curl -X POST BASE/gemini/music -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"lofi beats\"}'",
+    "gemini_reset":           "curl -X POST BASE/gemini/reset -H 'Authorization: Bearer KEY'",
+    "gemini_get_file":        "curl -H 'Authorization: Bearer KEY' BASE/gemini/output/img_xxx_0.png -o image.png",
+
+    "flow_health":            "curl -H 'Authorization: Bearer KEY' BASE/flow/health",
+    "flow_video_t2v":         "curl -X POST BASE/flow/generate/video -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"sunset timelapse\",\"aspect\":\"landscape\",\"duration\":8}'",
+    "flow_video_i2v":         "curl -X POST BASE/flow/generate/video -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"animate this\",\"start\":\"/path/to/image.jpg\",\"duration\":8}'",
+    "flow_video_fl":          "curl -X POST BASE/flow/generate/video -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"morph between\",\"start\":\"/path/start.jpg\",\"end\":\"/path/end.jpg\",\"duration\":8}'",
+    "flow_video_r2v":         "curl -X POST BASE/flow/generate/video -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"in this style\",\"ref\":[\"/path/ref.jpg\"],\"duration\":8}'",
+    "flow_video_v2v":         "curl -X POST BASE/flow/generate/video -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"restyle anime\",\"edit\":\"video_media_id\",\"duration\":10}'",
+    "flow_edit_video":        "curl -X POST BASE/flow/edit/video -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"watercolor\",\"video_media_id\":\"xxx\",\"fps\":24,\"duration\":10}'",
+    "flow_image_t2i":         "curl -X POST BASE/flow/generate/image -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"neon city\",\"aspect\":\"square\",\"count\":2}'",
+    "flow_image_i2i":         "curl -X POST BASE/flow/generate/image -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' -d '{\"prompt\":\"vintage style\",\"ref\":[\"/path/ref.jpg\"]}'",
+    "flow_upload_image":      "curl -X POST BASE/flow/upload/image -H 'Authorization: Bearer KEY' -F 'file=@image.jpg'",
+    "flow_upload_video":      "curl -X POST BASE/flow/upload/video -H 'Authorization: Bearer KEY' -F 'file=@video.mp4'",
+    "flow_download":          "curl -H 'Authorization: Bearer KEY' BASE/flow/download/omni_xxx_1.mp4 -o video.mp4"
+  },
+
+  "error_codes": {
+    "401": "Missing or wrong API_KEY",
+    "400": "Bad request (missing prompt, invalid form, etc.)",
+    "502": "Backend server not reachable (still booting or crashed)",
+    "503": "API_KEY not set on server OR extension not connected",
+    "504": "Request timed out (session auto-reset)"
+  }
+}