API Helper Reference

Converts an uploaded browser-generated video file to MP4 with H.264 video and AAC audio. Shortform Studio normally uses its primary server-side assembler directly, so this endpoint is a fallback.

Returns video/mp4 on success. Errors are plain text and logged to api/convert_video_mp4.log. The helper is rate limited as video_studio_convert_mp4.

Creates a server-side Shortform Studio job, generates narration or music, generates missing scene images, renders subtitles onto portrait slides, and assembles an MP4. Use JSON for ordinary jobs or multipart form data when uploading starting photos.

The helper is rate limited as video_studio_server_job, logs debug details only when debug mode is enabled, and keeps temporary job files under api/video_studio_jobs/.

Sends a plain-text email through Hostinger's SMTP server using PHPMailer. The From address is always adam@promptbox.cn (PromptBox); an optional custom sender is set as the Reply-To header instead. All three of recipient, subject, and body are required.

Runs common FFmpeg tasks for external HTML apps without exposing arbitrary command execution. Supports media inspection, format conversion, and video thumbnail extraction from an uploaded file.

const form = new FormData();
form.append('action', 'convert');
form.append('preset', 'mp4');
form.append('width', '720');
form.append('media', fileInput.files[0]);

const response = await fetch('https://promptbox.cn/api/ffmpeg_helper.php', {
  method: 'POST',
  body: form
});
if (!response.ok) throw new Error(await response.text());
const mp4Blob = await response.blob();

info and probe return JSON like { "success": true, ... }. convert returns the requested media bytes with the matching content type, and thumbnail returns image/jpeg. Errors return JSON { "success": false, "error": "...", "code": 400 } with an appropriate HTTP status. The helper sends permissive CORS headers, logs errors to api/ffmpeg_helper.log, and is rate limited as ffmpeg_helper.

Takes a plain-English description and uses Gemini to generate a complete working program. By default it preserves the original HTML generator behavior: a self-contained mobile-friendly HTML/CSS/JavaScript app is saved in public_html/logi/logi_code/ as the next numbered codeN.html file, and the public URL is returned.

Pass api=1, rest=1, or mode=api to generate a PHP REST API endpoint instead of a user interface. API mode saves a unique descriptive PHP filename in public_html/api/, such as recipe-nutrition-calculator-api.php, then appends usage documentation for that generated endpoint to this api.html reference page. It does not create a separate .txt documentation file.

Every generated REST API uses the shared rate-limit.php helper, returns JSON 429 responses when the helper denies a request, and writes server-side failures to an endpoint-specific .log file in public_html/api/.

Generated HTML apps can call web.php for live web data, llm.php for lightweight AI tasks, and image_gen.php for runtime image generation. A pre-generation image manifest (<!-- APP_GEN_PREGENERATE_IMAGES [...] -->) can also be embedded in HTML output to generate up to 30 static images at save time. Generated REST APIs are PHP endpoints that accept HTTP inputs and return JSON.

Default HTML mode returns the created codeN.html file under logi/logi_code/:

API mode returns the created descriptive .php endpoint under api/ and reports whether this page was updated with generated endpoint documentation:

On completion or failure, html_gen.php also posts a notification with task_id, status, result URL, filename, docs URL, and a prompt preview to ve-asked-html-gen-inform-api.php.

Recommended image generation API. Use image_gen.php for normal text-to-image requests; use the Gemini or Seedream image helpers only when an existing image input is needed for editing, style transfer, or image-conditioned generation. Generates a PNG image from a text prompt using AIML's alibaba/z-image-turbo model. Returns the raw image bytes directly as image/png — use response.blob() and URL.createObjectURL() in browser apps. Portrait (3:4) by default; set landscape=1 for landscape (4:3) output. AIML acceleration is off by default; pass acceleration=high to enable it for faster generation. AIML's safety checker is off by default; opt in with safety_checker=1. To have the server rewrite and sanitize the image prompt with llm.php before generation, pass optimize_prompt=1.

When called as a library function (require_once 'image_gen.php'), use generateImage($prompt, $isLandscape, $enableSafetyChecker, $acceleration, $optimizePrompt) which returns the raw binary string, or run_image_gen($inputs) which saves the image to logi_image.png and returns a public URL.

On sites that block external fetch() but allow external images, such as newer free Neocities sites, set the helper URL directly as an image source instead of fetching a blob.

HTTP 200 with Content-Type: image/png and raw PNG bytes on success. On error: plain text error message with an appropriate HTTP error code.

Use image_gen.php for normal text-to-image generation. Use this helper only when an existing input image is needed for Gemini image editing, style transfer, or image-conditioned generation. It uses Gemini's gemini-3.1-flash-image-preview model and returns raw image bytes; send the input image as base64 (with or without a data URI prefix) in the image parameter, or as a multipart file upload. Portrait (3:4) is the default; landscape (4:3) can be requested. The helper uses Gemini's default 1K output unless image_size=4K or four_k=1 is passed.

On sites that block external fetch() but allow external images, such as newer free Neocities sites, set the helper URL directly as an image source instead of fetching a blob.

HTTP 200 with the detected MIME type (image/png, image/jpeg, etc.) and raw image bytes. On error: plain text message with appropriate HTTP status code.

Use image_gen.php for normal text-to-image generation. Use this helper only when one or more existing input images are needed for Seedream editing or image-conditioned generation. It uses ByteDance Seedream v4 through AIML; without input images it calls bytedance/seedream-v4-text-to-image, and with input images it calls bytedance/seedream-v4-edit with image_urls. It returns raw image bytes like image_gen_gemini.php.

HTTP 200 with the detected image MIME type and raw image bytes. On error: plain text message with an appropriate HTTP status code.

Creates, updates, deletes, and answers questions from local JSON knowledge graphs saved in the site-level kgraph/ folder. It uses llm.php to extract entities and relationships from new knowledge, merge them into existing graph nodes and edges, and answer questions using only the saved graph. The helper is rate limited as kgraph and logs failures to api/kgraph.log.

Use this when an app needs a small, editable memory graph instead of document search. Each graph is stored as https://promptbox.cn/kgraph/{graph_id}.json with nodes, edges, and notes.

Create and add return the saved graph JSON. Delete returns { "success": true, "deleted": "graph-id" }. On error: { "success": false, "error": "...", "code": 400 } or another relevant HTTP status. Rate-limit failures return HTTP 429 and may include a Retry-After header.

Creates and manages compact long-term memory JSON files for LLM apps. Memory files are saved in the site-level memory/ folder as https://promptbox.cn/memory/{memory_id}.json. The helper stores only a summary plus structured sections: user_profile, preferences, operational_directives, interaction_tips, projects, knowledge_nodes, recent_context, and open_loops.

Use this when an app needs durable, compact context that can be read by humans and reloaded into prompts. Add and forget actions call llm.php to merge new facts, deduplicate memory, delete weak/noisy/insignificant details, and remove forgotten content. The helper is rate limited as memory and logs failures to api/memory.log.

Create, add, forget, and get return the complete memory JSON for easy review. Purge returns { "success": true, "purged": true }. On error: { "success": false, "error": "...", "code": 400 } or another relevant HTTP status. Rate-limit failures return HTTP 429 and may include a Retry-After header.

Creates and manages note files saved in the site-level notes/ folder as individual JSON documents. Each note includes note_id, title, text, status, tags, timestamps, and optional metadata.

Use this when an app needs server-backed notes instead of browser-only localStorage. The helper supports the existing Logi note vocabulary (add, list, update, complete, delete) plus REST-style actions (create, read, edit, overview, restore). It is rate limited as notes and logs failures to api/notes.log.

read, edit, complete, and restore return the full note. overview returns { "success": true, "count": 2, "total": 2, "notes": [...] }. delete returns { "success": true, "deleted": true }. On validation, missing note, rate-limit, or storage errors, the helper returns JSON like { "success": false, "error": "...", "code": 400 } with the matching HTTP status.

Recommended LLM API. Use llm.php for normal text prompts and answers; use the other LLM helpers only when an attachment, image, audio, or provider-specific capability is needed. The default model is deepseek/deepseek-v4-flash through AIMLAPI; pass model=pro, model=premium, quality=pro, or pro=1 to offload the request to llm_gemini.php using Gemini gemini-3-flash-preview. Passing model=lite, omitting model, or using any other value keeps the default flash model. Responses are uncapped by default; pass max_sentences to add sentence-limit guidance. Suitable for translations, classifications, rewrites, summaries, extractions, trivia lookups, and simple puzzles. For live web data use web.php instead.

Returns text/plain — no JSON wrapper — so it can be used directly in browser fetch() calls with response.text(). If you pass callback or cb on a GET request, it returns JSONP as application/javascript: callback({ ok: true, text: "..." }). JSONP responses use Cache-Control: no-store.

text/plain with the model's answer and an X-LLM-Model response header showing deepseek-v4-flash or gemini-3-flash-preview. On error: plain error string with appropriate HTTP status. In JSONP mode, the response is always JavaScript with { ok, text, model } or { ok: false, error, status }.

Scores one photo of a person against a weighted beginner composition checklist: eyes open, clean background, face lighting, focus, crop, level camera, headroom, distractions, flattering camera angle/height, and subject size. The built-in weights add to 15 points, and optional additional rules must include weights that are added to max_score. It uses llm_gemini.php with the lite Gemini model and returns a compact JSON score plus one short hint that prioritizes actions the picture taker can control, such as moving left, stepping closer, raising the camera, or reframing.

Requests are rate-limited under program photo_score. Server-side failures are logged to api/photo_score.log.

Scores are rounded to half-point steps. With details=1, the response includes base item scores, base weights, and any additional rule scores. If the weighted score is within 10% of max_score, hint and comment return PERFECT!. If no person is visible, hint and comment return No person detected in the image. Error responses are JSON with { "ok": false, "error": "..." } and an appropriate HTTP status.

Use llm.php for normal text prompts and answers. Use this helper only when Gemini attachments, image/audio content, structured Gemini contents or parts, or Gemini-specific generation controls are needed. The default model is gemini-3-flash-preview; pass model=lite or model=gemini-3.1-flash-lite to use gemini-3.1-flash-lite, which always runs with temperature=0.

This helper is for general Gemini text, vision, and audio/content requests. It does not accept Gemini File Search tools; use rag.php for File Search / RAG queries against a document store.

Like llm.php, the response is text/plain with no JSON wrapper. If you pass callback or cb on a GET request, it returns JSONP as application/javascript for Neocities/free-CSP pages.

text/plain with the model's answer. Returns null (the literal string) on API-level errors, or an HTTP error code on input validation failures. In JSONP mode, the response is always JavaScript with { ok, text } or { ok: false, error, status }.

Use llm.php for normal text prompts and answers. Use this helper only when image attachments or Grok-specific behavior are needed. It is a thin proxy to the xAI Responses API, including multimodal prompts with image uploads. It uses xAI directly when grok_key.txt is available. The default model is grok-4.5; pass model=lite or model=grok-4-1-fast-non-reasoning to use the AIMLAPI lite model. Text-only responses are uncapped by default; pass max_sentences to add sentence-limit guidance.

Returns text/plain with no JSON wrapper, so browser apps can call it directly with response.text(). If you pass callback or cb on a GET request, it returns JSONP as application/javascript: callback({ ok: true, text: "..." }). Use this mode for newer free Neocities sites, where external fetch() is blocked by Content Security Policy.

text/plain with the model's answer. On error: plain error string with appropriate HTTP status. In JSONP mode, the response is always JavaScript with { ok, text } or { ok: false, error, status }.

Creates a MiniMax minimax/music-2.0 music generation job through AIMLAPI, checks the status of an existing job, and streams completed audio through Promptbox so browser apps do not need to fetch provider storage URLs directly. This is a JSON REST helper for create/status: use POST with a prompt and lyrics to start generation, or set is_instrumental and omit lyrics for a no-vocal instrumental request. Use GET with generation_id for status or action=audio to download the finished MP3. The AIMLAPI key remains server-side. The helper is rate limited as music_gen and logs failures to api/music_gen.log.

Successful create/status responses pass through AIMLAPI's JSON, usually including id, status, optional audio_file.url, optional error, and optional meta.usage. action=audio returns raw audio bytes with Content-Type: audio/mpeg or another provider audio MIME type. The model can take time; use conservative, user-started automatic status checks.

On validation, rate-limit, or upstream API errors, returns JSON like { "success": false, "error": "..." } with an appropriate HTTP status code. Rate-limit denials also set Retry-After when available.

Provides the REST planning interface used by logi/logi_code/music-videos.html. It generates original lyrics from a song idea without section markers, and creates batched image-generation prompt directions for lyric lines. Uploaded MP3 lyric transcription is handled by lyrics.php so subtitles are based on audio instead of filename inference. Music audio is still generated by music_gen.php, images by image_gen.php, and MP4 assembly by assemble_shortform_mp4.php.

The helper is rate limited as music_video_studio and logs errors to api/music_video_studio.log. It accepts JSON, form data, GET parameters, and JSONP for GET requests.

On validation, rate-limit, or upstream text-helper errors, returns JSON like { "success": false, "error": "..." } with the relevant HTTP status. Rate-limit denials may include a Retry-After header.

Creates a downloadable PDF from finished, PDF-ready text. The helper supports a title, page size, orientation, margins, font size, headings written as # Heading, simple bullet lines, escaped newline normalization, and cleanup of common inline Markdown markers. It is rate limited as pdf_creator and logs failures to api/pdf_creator.log.

HTTP 200 with Content-Type: application/pdf and raw PDF bytes on success. On error: JSON { "success": false, "error": "..." } with an appropriate HTTP status. Rate-limit failures return HTTP 429 and may include a Retry-After header.

Asks a question against a Gemini File Search store and returns a short answer grounded in that store's documents. The helper uses gemini-2.5-flash, automatically adds a briefness hint to the prompt, enforces the shared rag rate limit, and logs failures to api/rag.log.

Use this when an app needs answers from a specific uploaded document corpus instead of open-web search or a general chat model. The caller must provide the File Search store name or ID in store_id. Prefer the full resource name, such as fileSearchStores/abc123; bare IDs such as abc123 are accepted and normalized. Contact admin@promptbox.cn to add new RAG file stores. Optional voice fields let a browser send microphone audio together with an instruction prompt.

On error: { "success": false, "error": "...", "code": 400 } or another relevant HTTP status. Rate-limit failures return HTTP 429 and may include a Retry-After header.

Provides rolling-window rate limiting for the public helpers. Unknown programs default to 300 requests per 24-hour window. An optional hourly sub-limit can also be configured.

Can also be called directly as an HTTP API to check or record usage for any program name, and includes an admin dashboard (password-protected) for monitoring and adjusting limits.

The Retry-After HTTP header is also set when denied.

Visit rate-limit.php?password=<password> in a browser to view all registered programs, their usage bars, last-used times, and controls for adjusting limits, resetting usage, or deleting program records.

Looks up a Steam game by name, resolves its App ID via the Steam store search API, then fetches either user reviews or community discussion search results. If the game name fails to resolve, the helper returns alternative search term suggestions and retry strategies. Discussion results are extracted from HTML and returned as a plain-text summary (up to 3000 words).

Fetches stock data from Finnhub's API. Given a ticker symbol (or ISIN/CUSIP), it can return a real-time quote snapshot, the company's profile, and key financial metrics. All three sections are returned by default; you can request only a subset. Quote data on the free tier may be delayed ~15 minutes during market hours.

On error: { "success": false, "error": "..." } with HTTP 400.

Accepts an uploaded MP3, optionally creates a Hostinger-local FFmpeg vocal-focused version, submits it to AIMLAPI speech-to-text, then formats the raw transcript into lyric lines. It can return plain lyric text or JSON with each line's start and end time for subtitle planning. This helper is intended for original songs, demos, voice memos, and user-provided audio where automatic lyrics are useful.

By default, returns text/plain with one cleaned lyric sentence or phrase per line. With JSON output, returns success, lyrics, lines, words, model, requested_model, and audio_preprocess; each line has text, start, and end in seconds when AIMLAPI provides word timestamps. Errors are plain text with an appropriate HTTP status. The helper logs server-side failures to api/lyrics.log and is rate-limited as program lyrics.

Provides a REST interface to the same temporary file-transfer storage used by transfer.promptbox.cn. Upload a file or several files, receive an 8-character receipt plus browser and API download URLs, inspect receipt metadata, stream the file, or delete a one-time file after clipboard copy. Files expire after 3 days; by default they are also deleted after first API download unless auto_delete=0 is sent during upload.

The helper is rate limited as program transfer and logs server-side failures to api/transfer.log. API uploads and browser downloads share the same storage metadata as transfer/index.php, so the returned download_url opens the standard transfer page and api_download_url streams the same file directly.

info, upload, delete, and clipboard_copied return JSON. download streams the file bytes directly and removes the receipt afterward unless the upload was retained. Validation, missing receipt, expired receipt, storage, and rate-limit errors return JSON like { "success": false, "error": "...", "code": 400 }; rate-limit denials also set Retry-After when available.

Transcribes spoken audio into plain text using Gemini (gemini-3.1-flash-lite). It is designed for browser microphone recordings from MediaRecorder, but also accepts base64 audio in JSON or form posts. The helper is rate limited as transcribe.

Returns text/plain with no JSON wrapper. Recordings under 0.5 seconds and locally detectable silent/near-silent WAV input return null without calling Gemini; if there is no intelligible speech in other audio formats, Gemini is instructed to return null.

text/plain transcript text. Too-short, silent, near-silent, or unintelligible recordings return null. On input errors, returns a plain error string with HTTP 400. On Gemini/API failure, returns null with HTTP 502.

Returns the plain-text transcript for a public YouTube video using the same multi-strategy extraction logic used by youtube.php. Pass either an 11-character YouTube videoId or a full YouTube URL. The helper is rate limited as transcript and logs failures to api/transcript.log.

Returns an error if the video ID is invalid, no transcript can be retrieved, or the helper hits its rate limit.

Converts text to speech using AIMLAPI's Inworld inworld/tts-1 model and streams the generated audio file. HTML tags, markdown syntax, control characters, and URL bodies are automatically stripped from the input before synthesis; URLs are spoken only as http, then narration continues with the next real text. Inworld TTS has a hard 2000-character limit per request; split longer narration at sentence breaks and combine the returned audio blocks in order. If the Inworld request fails, the helper silently falls back to tts.php.

tts_inworld_test.html lets you enter a prompt, choose an Inworld voice, and play the generated audio in the browser.

HTTP 200 with raw audio bytes on success. The response uses Content-Type: audio/mpeg for MP3 and audio/wav for WAV. On error: JSON { "success": false, "error": "..." } with appropriate HTTP status.

Searches multiple social platforms via the API Direct service. Despite the filename, it supports Twitter/X posts, Facebook posts, Reddit posts, and Reddit comments. Results are returned as a formatted text summary alongside the raw structured data. Up to 8 items per platform are included in the response.

A Tavily search proxy designed to be called from browser apps for live, public web data. By default it extracts and returns the first numeric value from the search answer — ideal for stock prices, scores, rates, and similar. Set text=true to get a plain-text answer instead, with length optionally capped by max_sentences. An optional url parameter narrows results to a specific domain.

A secondary mode (mode=image_prompt_refine) passes the prompt to Gemini and returns an enhanced image generation prompt — useful for improving image_gen.php inputs.

Returns text/plain. With text=false (default): a plain number string like 189.34, or null if no number was found. With text=true: a plain-text answer. If the Tavily query is over 400 characters, it is truncated and the response appends Tool Error: Query truncated, max query length is 400 characters. On error: null with an appropriate HTTP status code.

Fetches one specific public http or https URL from the server side and returns readable text for many source types. It reads HTML pages, plain/document text, basic generated PDFs, RSS/Atom feeds, Office-style archives such as docx, pptx, xlsx, odt, and epub, GitHub blob URLs via raw content, public YouTube transcripts, image descriptions through llm_gemini.php lite, and audio/video transcripts through transcribe.php. It also uses an MSN article JSON fallback and can use Tavily extraction when normal reading finds no usable text.

The helper blocks localhost, private-network, reserved, and credential-bearing URLs, follows up to 5 validated redirects, caps ordinary downloads at 1 MB and media downloads at 10 MB, rate-limits as web_read, and logs failures to api/web_read.log.

Returns application/json. On success: { ok, url, final_url, title, text, text_length, truncated, content_type, status, redirects }. Some sources may also include source_url, video_id, and reader_mode such as html_text, document_text, pdf_text, archive_document_text, feed_text, youtube_transcript, image_description, media_transcript, tavily_extract, or msn_article_json. On error: { ok:false, error } with an appropriate HTTP status code. Bad URL inputs return clear messages such as Missing required url., Invalid URL: only http:// and https:// URLs are supported., Invalid URL: hostname is not valid., or Invalid URL: target hostname could not be resolved.. JSONP mode wraps the response as { ok, status, data, error }.

Accepts a natural-language question, searches YouTube for up to 3 relevant videos, retrieves their transcripts (using multiple extraction strategies including the /youtubei/v1/get_panel API), and then feeds the transcripts to llm.php to synthesize a comprehensive answer. Only the transcript content is used — no external web search. The helper is rate limited as youtube and logs failures to api/youtube.log.

Returns an error if no videos are found, none have accessible transcripts, a dependency key is missing, or the helper hits its rate limit. GET also supports JSONP with callback or cb.