docs/api-reference.json

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