Promptbox API Reference

Controls a JavaScript-enabled browser: open pages, read content, fill forms, click links, manage tabs, take screenshots, and reuse saved login profiles. Use mode=agent for guided actions with current control IDs. Requires a browser API key. Uses two CPU cores and a 110-thread ceiling within a 120-thread hosting allowance, reserving ten threads for other hosting work. Supports up to two concurrent sessions and four tabs per session when resources permit; idle sessions expire after about three minutes and operations have a 45-second deadline. File uploads/downloads and interactive human takeover are unavailable.

POST JSON with Authorization: Bearer YOUR_BROWSER_API_KEY. Set mode=agent, open a URL, and use the latest page_id and control IDs for each action. Give state-changing actions a unique request_id, inspect the returned page, and close the session when finished. If content is loading or controls are truncated, request one snapshot, using focus when needed. Human-verification pages require human help; inspect uncertain results before retrying.

POST https://promptbox.cn/api/browser.php with JSON and Authorization: Bearer <browser API key>. Request a key from admin@promptbox.cn.

Operation deadline: Each operation is limited to 45 seconds. An expired agent operation closes its sessions; do not reuse those IDs. Concurrent actions return HTTP 409. Inspect uncertain results before retrying a click or submission.

Agent interface: Set mode:"agent" to receive short IDs for visible fields, buttons, links, and select options. Use the current page_id and control IDs for each action because every response returns a fresh observation. Mutating actions require a unique request_id of 8–160 letters, digits, hyphens, or underscores.

{"mode":"agent","action":"open","url":"https://example.com","request_id":"unique-open-001"}
{"mode":"agent","action":"fill_form","page_id":"LATEST_PAGE_ID","fields":{"field-1":"10 Market Street","field-2":"San Francisco","field-3":"option-2","field-4":true},"request_id":"unique-fill-001"}
{"mode":"agent","action":"click","page_id":"NEW_PAGE_ID","target_id":"OBSERVED_BUTTON_ID","request_id":"unique-click-001"}

fill_form fills fields sequentially and does not submit. Select controls use returned option-N IDs; checkbox and radio values are booleans. Inspect applied and the returned page, then click the submit control using the new page_id. Use snapshot with focus when controls are truncated. Close the session when finished.

Example: If an open response lists field-1 as Street address, field-2 as a Drink select with option-2 labeled Jasmine milk tea, field-3 as a checkbox, and button-4 as Continue, fill and continue like this:

{"mode":"agent","action":"fill_form","page_id":"PAGE_A","fields":{"field-1":"10 Market Street","field-2":"option-2","field-3":true},"request_id":"order-fields-001"}
{"mode":"agent","action":"click","page_id":"PAGE_B","target_id":"button-4","request_id":"order-continue-001"}
{"mode":"agent","action":"close","session_id":"SESSION_A","request_id":"order-close-001"}

PAGE_B is the fresh page ID returned by fill_form. Read the page returned by click before deciding the next action.

Low-level interface: Omit mode and use Playwright locators, coordinates, tabs, or profiles directly.

{"action":"create","url":"https://example.com"}
{"action":"snapshot","session_id":"RETURNED_SESSION_ID"}
{"action":"fill","session_id":"RETURNED_SESSION_ID","label":"Search","value":"milk tea"}
{"action":"click","session_id":"RETURNED_SESSION_ID","role":"button","name":"Search"}
{"action":"close","session_id":"RETURNED_SESSION_ID"}

Use one of selector, role + name, label, or text for low-level actions. Optional tab_id chooses a tab; optional frame resolves a locator inside an iframe. Read the page after navigation or interaction and do not repeat an uncertain state-changing action before inspecting current state.

Maximum 2 sessions and 4 tabs per session. Idle sessions expire after 3 minutes of inactivity. Cleanup runs every minute, so actual closure occurs after approximately 3–4 idle minutes. Interaction timeouts accept 1–25,000 ms. Requests are limited to 100 KB and responses to 8 MB.

Capacity and recovery: Browser v2.3.1 runs on two allowed CPUs with one raster thread. Automatic startup uses a restricted local launcher to avoid inherited web-worker virtual-memory limits. Its thread ceiling is 110 within the verified account allowance of 120, leaving ten slots for other work; browser memory remains capped at 1.5 GiB. Opening a cold browser reserves 75 threads; adding a session to a warm browser or adding a tab reserves 20. These are admission estimates; complex pages can still exceed capacity. If capacity_full reports rejected:true, no action started; wait at least retry_after seconds before an intentional retry. A resource shutdown may close existing sessions; inspect saved observations and never replay an uncertain click or submission automatically.

Complete usage reference · OpenAPI contract

Converts an uploaded browser-recorded or other FFmpeg-readable video into an iPhone-compatible MP4 with H.264 video and AAC audio. It accepts uploads up to 600 MB, returns raw video/mp4 bytes, and has no Promptbox request quota.

Send a multipart POST request with the source file in the video field. On success, save or play the returned video/mp4 bytes.

Returns video/mp4 on success. Errors are returned as plain text. The helper has no Promptbox request quota.

Returns a yes/no decision, one choice from supplied options, or a score on an ordered scale, based on your context and question. The JSON result contains only answer and probability. Choose this helper when you need a typed decision rather than a prose answer. It has no Promptbox request quota.

POST JSON with context, question, output_type, and any required options. Use noul for yes/no, choice for 2–255 options, or score for 2–255 ordered levels. Prefer 2–10 levels for native scoring; 11–255 levels return an approximate score calculated from choice probabilities. Scores are zero-based and may be fractional.

GET returns a compact usage description. POST makes one JEV decision.

curl https://www.promptbox.cn/api/decision.php \
  -H 'Content-Type: application/json' \
  -d '{"context":"Payments have failed for three days.","question":"Is this urgent?","output_type":"noul"}'

curl https://www.promptbox.cn/api/decision.php \
  -H 'Content-Type: application/json' \
  -d '{"context":"Customer asks for a refund.","question":"Which team should handle this?","output_type":"choice","options":{"billing":"Payments and refunds","technical":"Bugs and outages","sales":"Pricing and upgrades"}}'

curl https://www.promptbox.cn/api/decision.php \
  -H 'Content-Type: application/json' \
  -d '{"context":"I have asked five times and nobody replied!","question":"How frustrated is the customer?","output_type":"score","options":["Calm","Frustrated","Very angry"]}'

Returns application/json. For a 2–10-level score, answer is TypeSafe's native score and probability is its native score confidence. For an 11–255-level compatibility score, answer is the probability-weighted mean of the choice indices and probability is TypeSafe's choice confidence. Input errors use HTTP 400, 413, or 415; disallowed browser origins use 403; unsupported methods use 405; configuration or upstream failures use 502 or 503. There is no Promptbox request quota. Only the selected answer and its confidence are returned.

Simulates activity in a male fruit-fly neural network from images, retinal brightness, or direct neuron currents. Returns spike totals, population activity, selected neurons, firing rates, voltages, and optional control readouts. Sessions preserve neural state across successive inputs. Use this helper to explore neural activity; its fixed weights do not learn or establish natural fly behavior.

Set the desired route in the path query parameter. Start with a JSON POST to /v1/step; create a session only when successive inputs must share state, and DELETE it when finished. No caller API key is needed. For compact visualization, first confirm section_top80_v1 is advertised by /v1/model, cache /v1/activity-layout, and request that activity_view with top_k:0. Omit activity data when no visualization is shown.

curl 'https://www.promptbox.cn/api/doomfly.php?path=/v1/step' \
  -H 'Content-Type: application/json' \
  -d '{"luminance":0.5,"duration_ms":20,"top_k":10}'

Returns application/json. Step responses include complete-network total_spikes and active_neurons, population summaries, selected top_spikes, requested readouts, interval timing, graph identity, and fixed doom_controls. With activity_view requested, activity contains base64 delta-unsigned-varint index/count pairs plus section totals; absent values render black. Colors use count × 1000 / interval.duration_ms on a fixed logarithmic 0–500 Hz scale. At least 20% per section is black; selected zero-spike neurons also stay black. Reuse the cached activity layout identified by layout_id. Activity format reference. Errors use HTTP 400, 404, 405, 409, 413, 422, 429, or 503 with a JSON error; capacity failures include Retry-After.

The shared rate limit is 120 HTTP calls per minute, with one neural computation at a time. Requests are limited to 3 MB and image data to 2.8 million base64 characters. Sessions permit up to 512 unique steps and must be released promptly. The fixed lease deadline does not renew on activity. Creation responses report max_steps, steps_used and steps_remaining; stateful step responses include these under session with expires_at. Step 512 succeeds; further unique steps return 409, and expired sessions return 404. Identical retries do not advance state. Stop sending steps at the step limit or lease expiry; create a new session to start another sequence. Read the complete Fly Brain API documentation, session semantics, and scientific limitations.

Sends a plain-text email immediately and returns a JSON delivery result. The sender is adam@promptbox.cn; a different valid sender value becomes the Reply-To address. Verify the recipient, subject, and body before calling.

Prefer POST with the recipient, subject, and message fields below. Check the JSON result before reporting success. An uncertain result may still have sent the message; verify before sending it again.

Inspects, converts, or creates a thumbnail from an uploaded audio or video file using safe FFmpeg presets. Conversion defaults to MP4 and also supports WebM, MP3, M4A, WAV, and GIF, with uploads up to 300 MB and durations up to 600 seconds. The helper returns metadata as JSON or raw media bytes and has no Promptbox request quota.

Send a multipart request with an action and the uploaded media file. Use info or probe for JSON metadata, convert for converted media bytes, or thumbnail for a JPEG image.

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://www.promptbox.cn/api/ffmpeg_helper.php', {
  method: 'POST',
  credentials: 'omit',
  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 has no Promptbox request quota. Browser origin restrictions described above still apply.

Generates a self-contained HTML/CSS/JavaScript browser tool from a text description, publishes it on Promptbox, and returns its public URL. Choose it to create a new static tool; use publish.php to deploy an existing build. It does not create server-side code or new REST endpoints.

POST action=start with a prompt, save task_id, and check action=status later. Do not poll continuously or restart a pending job. When job.status is completed, open url; when it is failed, read job.error. Generated tools are public, so keep secrets out of the prompt.

All responses use application/json. A successful start request returns HTTP 202 with success, pending, task_id, status, and status_url. A status request returns HTTP 200 when the task lookup succeeds; inspect job.status to determine the generation result. A completed job includes the published url. A failed job includes job.error and does not include a new published URL.

Invalid requests return HTTP 400, disallowed browser origins return 403, unknown or expired task IDs return 404, unsupported methods return 405, and rate limits return 429 with a Retry-After header.

Preferred helper for ordinary text-to-image requests. Generates a PNG from a text prompt, with portrait 3:4 output by default and landscape 4:3 available. It does not accept reference images; choose image_gen_gemini.php or image_gen_seedream.php for image editing.

Send prompt by GET or POST and read the successful response as image/png. Choose orientation and other optional settings below. Use an editing helper when the request includes an existing image.

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.

Generates an image or edits one reference image, with 1K output and portrait 3:4 by default. Accepts PNG, JPEG, WebP, HEIC, or HEIF input up to 20 MB. Choose this helper for editing with one reference; use image_gen_seedream.php for multiple references or higher resolution, and image_gen.php for ordinary text-to-image requests.

Send prompt by GET or POST. For editing, POST an uploaded or base64 reference image using the fields below. Save or display the returned image bytes.

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.

Generates or edits images using up to 14 reference images. Supports 2K, 4K, or explicit dimensions from 1440 to 4096 pixels per side. Choose it for multiple references or high-resolution editing; use image_gen.php for ordinary text-to-image requests.

Send prompt and any reference images using the fields below. Choose dimensions when needed, then save or display the returned image bytes.

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

Creates, reads, updates, deletes, and queries persistent knowledge graphs containing nodes, relationships, and notes. Supports up to 5,000 nodes and 10,000 edges per graph, with no Promptbox request quota. Graph files are publicly accessible; do not store secrets or confidential information.

Send an action, graph_id, and the fields required by that action. Save the graph ID for later calls and inspect the JSON result. Use the query action to ask questions about the stored graph.

Create and add return the saved, normalized graph JSON. Delete returns { "success": true, "deleted": "graph-id" }. Knowledge is limited to 200,000 bytes, questions to 12,000 bytes, and stored graph JSON to 2,000,000 bytes. JSON requests must contain a valid object. On error: { "success": false, "error": "...", "code": 400 } or another relevant HTTP status.

Preferred LLM helper for ordinary text requests. Answers questions, summarizes, translates, and generates text. Defaults to glm-5.3 with low reasoning effort and no Promptbox request quota; model=pro selects deepseek/deepseek-v4-flash. Use a multimodal helper for images, audio, or files.

Send prompt by GET or POST and read the answer as plain text. Set reasoning_effort to low, high, or max; medium is an alias for high. Set max_tokens up to 32768 when a longer answer or reasoning needs room; use the optional model and timeout settings below when needed.

text/plain with the model's answer and an X-LLM-Model response header showing deepseek-v4-flash or glm-5.3. 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 }.

Returns a plain-text answer with selectable OpenAI models and optional image input. Choose it when you specifically need an OpenAI model; use llm.php for ordinary text requests. Defaults to gpt-6.1-sol with low reasoning and the Promptbox request-count limit. The lite route uses gpt-6-luna and is exempt from that limit.

Send prompt by GET or POST and read the answer as plain text. POST JSON when supplying images. Set model=lite for Luna or another supported model name when needed. Use reasoning_effort to override the model default and max_tokens up to 32768 to allow room for reasoning and the answer.

Successful non-JSONP requests return the model answer as text/plain. Input errors return an HTTP error status and a plain-text message. Upstream or empty-response failures return an HTTP error status and null.

Returns a plain-text Gemini answer from text, images, audio, files, or structured Gemini content. Choose this helper when native voice/audio input is needed. Use llm.php for ordinary text. Defaults to gemini-3-flash-preview without specifying thinking effort; Gemini uses its own default when no thinking controls are supplied. The standard route allows 300 requests per rolling day; model=lite selects gemini-3.1-flash-lite and is exempt from that limit.

POST the prompt and audio as Gemini parts or contents, then read the answer as plain text. Set model=lite for the lightweight model. Use the fields below for images, conversation history, system instructions, or generation settings.

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

Returns text or multimodal answers through a simple prompt endpoint or OpenAI-compatible chat routes. Choose it for OpenAI-compatible clients, function-tool workflows, or automatic multimodal routing; use llm.php for ordinary text. Text-only requests use the default model in llm.php. Non-text input uses the default model in llm_gemini.php. Each route inherits its downstream helper's request limits; model selection stays centralized in those helpers. Streaming returns the completed answer in one chunk, not token by token.

For simple calls, send prompt to llm_jb.php and read plain text. For OpenAI-compatible clients, set the base URL to https://www.promptbox.cn/api/llm_jb.php/v1 and POST messages to /chat/completions; GET /models lists models. Send attachments using the documented image or Gemini content fields. Set skip_prefix=true to use only your own instructions. Use provider=gemini to send text through the default model in llm_gemini.php. The optional model field is accepted for compatibility and does not override either helper's default, including when set to lite. Check HTTP errors and Retry-After before retrying.

Legacy mode returns text/plain with the model's answer. Helper failures return their actual HTTP status and a readable error message; rate-limit errors preserve HTTP 429 and the Retry-After header. Empty or invalid helper responses return a descriptive HTTP 502, and transport timeouts return HTTP 504. Input validation failures use their existing HTTP error codes. In JSONP mode, the response is always JavaScript with { ok, text } or { ok: false, error, status }.

OpenAI-compatible mode returns JSON with choices[0].message.content for text responses or choices[0].message.tool_calls when the text helper requests a function call. Errors retain the OpenAI-style JSON error envelope, the helper HTTP status, and any Retry-After header. Downstream usage counters and tool-call ids are preserved. Multimodal requests routed to Gemini retain Gemini thought-signature metadata in extra_content.google.thought_signature when Gemini provides it.

Creates and manages persistent structured memory for preferences, project context, knowledge, and tasks. Supports section-specific additions, exact item edits, consolidation, and semantic forgetting. Memory files are publicly accessible and limited to 400,000 bytes; do not store secrets, confidential material, or sensitive personal information.

Send an action and memory_id with the fields required by that action. Save the memory ID for later calls. Use include_ids=true to retrieve item IDs for exact edits; use forget with item_id to remove one item and purge to delete the entire memory. Mutating actions require POST.

Create, add, forget, and get return the complete normalized memory JSON for easy review. Purge returns { "success": true, "purged": true }. Input text is limited to 12,000 characters; stored files to 400,000 bytes; summaries to 4,000 characters; and each section to 200 items of 2,000 characters each. JSON requests must contain a valid object. On error: { "success": false, "error": "...", "code": 400 } or another relevant HTTP status.

Creates vocal songs from a prompt and lyrics, or instrumental music, and returns a job ID for later status checks and audio download. Supports MP3 and WAV. Prompts must contain 10–2,000 characters; vocal lyrics must contain 10–3,000 characters.

POST a prompt and lyrics for a vocal track, or set is_instrumental for an instrumental. Save the generation ID, check status later with GET, and request action=audio when complete. Do not poll continuously.

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.

Creates, reads, searches, edits, completes, restores, and deletes persistent JSON notes with titles, text, status, tags, timestamps, and optional metadata. The default overview action lists up to 100 notes, while individual note text may contain up to 50,000 characters. The helper has no Promptbox request quota, but stored notes are publicly accessible and must not contain secrets.

Send an action with the fields required for that operation and save returned note IDs for later edits. Notes are publicly accessible, so do not store secrets, confidential material, or sensitive personal information.

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, or storage errors, the helper returns JSON like { "success": false, "error": "...", "code": 400 } with the matching HTTP status.

JSON POST requests must contain a valid JSON object. Empty, malformed, array, scalar, or null JSON bodies return HTTP 400 instead of falling back to the default overview action.

Creates a downloadable PDF from finished text or converts one supported office document while preserving its layout. Text input supports page size, orientation, margins, fonts, headers, footers, and metadata. File uploads are limited to 10 MB. Returns PDF bytes.

POST either content or one multipart file, with any optional page settings. Check the response status, then save the successful application/pdf bytes. Errors return JSON.

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

Searches named places and businesses, finds nearby results, and retrieves addresses, coordinates, ratings, websites, opening hours, phone numbers, prices, and reviews. No caller API key is needed. If an initial text search finds no location, the helper automatically geocodes the query with Photon/OpenStreetMap and retries Google once with a coordinate bias before returning a not-found error.

Send GET or JSON POST with action=search, nearby, or details and the required fields below. Use a Google place ID from search results for details. Request only fields you display and show the required attribution. For street addresses, submit the complete address as query; fallback is automatic. Only returned Google IDs can be used for details. Fallback coordinates are a search hint, not a verified house destination. Review the fallback response before displaying or using coordinates.

Use query parameters for GET or an application/json object for POST. Do not combine POST with query parameters. Maximum JSON body: 16 KiB.

Version 1.1.0: An initial search returning no places or HTTP 404 triggers one Photon/OpenStreetMap geocoding lookup, followed by one Google text-search retry biased to the returned coordinates. The original query, requested fields, limit, language and ranking remain unchanged; the supplied radius or 5,000 meters is used for the retry bias. Any distance_meters still measures from the caller's original coordinates. No unrelated nearby business is substituted for an address.

Fallback does not run for pagination, nearby, details, invalid input, authentication failures, quota errors or upstream outages. A geocoder with no match ends the search with HTTP 404; a geocoder outage or busy fallback returns HTTP 502 geocoding_unavailable. After a coordinate-assisted retry, an empty result is HTTP 404 not_found; Google retry errors retain their normal status. Google place IDs are never fabricated from OpenStreetMap data.

Photon is a separate provider using OpenStreetMap data. Its public endpoint permits moderate usage without an availability guarantee. Outbound geocoding is serialized and spaced at least one second apart, with private bounded caching (24 hours for coordinates, five minutes for misses, up to 300 entries); each uncached lookup counts against the shared helper quota. Use explicit submitted searches, not polling or keystroke requests. Display © OpenStreetMap contributors when fallback coordinates are used. They may be approximate or ambiguous; verify the address and house number before routing to a precise destination.

id, displayName, formattedAddress, location, googleMapsUri, types, primaryType, businessStatus, rating, userRatingCount, websiteUri, nationalPhoneNumber, internationalPhoneNumber, regularOpeningHours, currentOpeningHours, priceLevel, reviews, attributions.

id and attributions are always requested. Searches with coordinates also request location. Add rating,userRatingCount for ratings, websiteUri for a business website, or reviews for up to five available reviews. Request only the fields your app displays; missing data may be omitted.

GET /api/places.php?action=search&query=milk%20tea%20in%20Saratoga%20CA&limit=5

POST /api/places.php
Content-Type: application/json

{"action":"nearby","lat":37.7937,"lng":-122.3965,"radius":1500,"types":["cafe"],"limit":5,"fields":["displayName","formattedAddress","location","googleMapsUri","rating","userRatingCount"]}

POST /api/places.php
Content-Type: application/json

{"action":"details","place_id":"PLACE_ID_FROM_SEARCH","fields":"displayName,formattedAddress,googleMapsUri,websiteUri,rating,userRatingCount,reviews"}

async function callPlaces(parameters) {
  const response = await fetch('https://www.promptbox.cn/api/places.php', {
    method: 'POST',
    credentials: 'omit',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(parameters)
  });
  const data = await response.json();
  if (!response.ok || !data.success) throw new Error(data.error || 'Places request failed');
  return data;
}
const data = await callPlaces({ action: 'search', query: 'milk tea in Saratoga CA', limit: 5 });
for (const place of data.places) console.log(place.id, place.displayName?.text, place.formattedAddress);

Search/nearby return {success:true, action, provider:"Google Maps", places:[...], rate_limit:{...}}. Search may also return next_page_token. Details return {success:true, action:"details", provider:"Google Maps", place:{...}, rate_limit:{...}}.

Each place uses Google's field names: displayName.text, location.latitude, location.longitude, and reviews[].text.text. Searches with coordinates add distance_meters, the straight-line distance, not driving or walking distance. Empty nearby results and pagination remain places:[]; an initial text search with no match uses the fallback before returning an error.

When displaying results, show Google Maps attribution and any returned third-party attributions. Display review authors using reviews[].authorAttribution, including their links when available. Render returned text as text, not HTML. Follow Google's display, attribution, and storage rules.

Responses that use fallback include fallback:{attempted:true,provider:"Photon / OpenStreetMap",status:"found|no_match|unavailable|busy",retried:boolean}. Successful geocoding adds location:{latitude,longitude}, attribution:{text,url} and cached. The top-level provider and all places remain Google Maps. These fields also accompany fallback-related errors. Check retried to distinguish a completed Google retry from geocoding without a candidate.

All actions share the places rate-limit program: with shared rolling limits configured on the rate-limit dashboard (currently 200 upstream requests per 24 hours and no separate hourly cap). Check current usage with rate-limit.php?program=places&action=check. Each outbound Google call and uncached Photon lookup consumes one request, even on an upstream error. A full fallback can consume three requests (initial Google search, geocoding, Google retry); a cached geocode consumes none. Each step checks quota before dispatch and can return 429 if the remaining budget is exhausted. Invalid local input does not consume quota. Inspect rate_limit.remaining_day and remaining_hour in successful responses.

Errors return {success:false,error:"...",error_code:"..."}. Status codes: 400 invalid parameters/JSON, 403 unsupported browser origin, 404 place not found, 405 unsupported method, 413 oversized body, 415 non-JSON POST, 429 rate limit or upstream quota, 502 upstream failure, 503 service unavailable. A helper rate-limit response includes retry_after seconds; 429 responses include a Retry-After header. Wait for user action before retrying; do not poll.

Publishes static HTML or ZIP web apps, supported documents, and media files to public Promptbox URLs. App deployments use private owner tokens and can be inspected, completely replaced, extended, deleted, or assigned a new token; each app has a renewable 30-day period. App uploads are limited to 25 MiB, file publications to 10 MiB, and static apps cannot run server-side code.

For an app, POST mode=app, a directory name, and either an HTML file, a complete ZIP build, or HTML text. Save the returned private token outside the published files. Use that token for later status, files, replace, extend, delete, or rotate-token operations. Every replacement must contain the complete app. For a document or media file, POST mode=file with one multipart file.

New content returns HTTP 201 with a JSON receipt containing its public url and expires_at. New apps also return the only copy of the private owner token. Successful replacements return HTTP 200. Apps use renewable 30-day periods; published files expire after 30 days and have no management token. Honor Retry-After on HTTP 429, and inspect validation fields such as removed_files, sanitized_files, deleted_files, and stripped_prefix.

App uploads allow up to 25 MiB and 1,000 files. File-mode uploads allow up to 10 MiB for supported binary files and 1 MiB for UTF-8 text formats. Check live capabilities when current limits or availability matter.

curl https://www.promptbox.cn/api/publish.php \
-F 'mode=app' \
-F 'directory=my-app' \
-F 'file=@app.zip'

curl \
-H "Authorization: Bearer $PROMPTBOX_APP_TOKEN" \
"https://www.promptbox.cn/api/publish.php?action=status&mode=app"

Complete publishing guide · Complete publishing contract

Creates a downloadable PNG QR code card for a website, email address, or Wi-Fi network. Output is 600 by 600 pixels without a title and 600 by 800 pixels with one, with medium QR error correction. It has no Promptbox request quota; Wi-Fi passwords should be sent by POST so they do not appear in a URL.

Send a destination or Wi-Fi fields by GET or POST, then display or save the returned image/png. Prefer POST for Wi-Fi passwords so credentials do not appear in a URL.

Returns image/png: 600×600 without a title or 600×800 with one. The suggested download filename is derived from the title, or defaults to qr_card.png. Wi-Fi special characters are escaped automatically. Errors return JSON with ok: false and error. The helper has no Promptbox request quota.

Answers a text or audio question using documents in a Gemini File Search store and returns a concise, document-grounded JSON result. Choose it when answers should come from your uploaded documents. Create and populate the store with rag-management.php. Defaults to gemini-3-flash-preview; voice input is limited to 5 MB.

Send a question and store_id by GET or POST; use the full File Search store resource name when available. For audio, use the documented POST fields. Inspect the JSON answer and HTTP status before retrying.

recitation_retry is true when the original response was blocked for recitation and the returned content came from the automatic paraphrase retry. On error: { "success": false, "error": "...", "code": 400 } or another relevant HTTP status. A retry that is also blocked returns HTTP 502. Rate-limit failures return HTTP 429 and may include a Retry-After header.

Creates, finds, lists, and deletes Gemini File Search stores, and uploads or manages their documents for use with rag.php. Uploads are limited to 20 MB per document; default document chunks contain 512 tokens with a 100-token overlap. Returns resource names for later requests; create, upload, and delete actions change stored data.

Send an action and the fields required below. Use resolve_filestore to find or create a store by exact display name. Save returned resource names and verify resulting state before retrying an uncertain create, upload, or delete request.

Hyphenated action names are accepted. Aliases include create_store, resolve_store, upload_file, list_documents, delete_document, and delete_store.

Returns application/json. Success responses use { "success": true, ... , "code": 200 }; the remaining fields depend on the action as described above. Errors use { "success": false, "error": "...", "code": 400 } or another appropriate HTTP status. HTTP 429 may include Retry-After.

Checks and records rolling daily and optional hourly request usage for a named program. New programs default to 300 requests per rolling day with no hourly limit, while existing programs may have custom limits. Use action=check for a non-consuming inspection and action=record to consume one request; denials return HTTP 429 and Retry-After.

Send a program name and action=check to inspect availability or action=record to consume usage. Read the JSON response, and honor HTTP 429 and its Retry-After value.

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

Retrieves Steam user reviews or searches community discussions for a game identified by name. Discussion search is the default; reviews=true selects reviews. Optional search terms narrow discussions, and unresolved game names return suggestions for a corrected request.

Send game_name by GET or POST. Set reviews=true for reviews or supply search_terms to narrow community discussions. Read the result in the documented response format and use returned suggestions if the game name cannot be resolved.

Returns stock quotes, company profiles, and financial metrics for a ticker symbol, ISIN, or CUSIP. Returns all three sections by default; callers may request selected sections or metric groups. Quotes may be delayed, so check timestamps and warnings before using them.

Send the security identifier by GET or POST. Use sections to select quote, profile, or financials and financial_metric when needed. Inspect the JSON result, including timestamps and warnings.

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

Transcribes uploaded or base64-encoded spoken audio into plain text. Accepts common browser audio formats up to 10 MB. Recordings shorter than 0.5 seconds, silence, or unintelligible audio may return null. Use llm_gemini.php when you need an answer to recorded speech rather than a transcript.

POST an audio file as multipart form data or use the supported base64 audio fields below. Read the successful response as plain text. Supply a custom prompt only when a particular transcript format is needed.

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 existing captions for a public YouTube video in a JSON transcript field. Choose it for captions from one known video; use youtube.php to research a topic across videos or transcribe.php for your own audio. It does not generate missing captions. Cached captions may be up to 30 days old when a refresh fails; check stale and any warning.

Send an 11-character videoId or a YouTube URL by GET or POST and read transcript from the JSON result. Check cache and error fields. If captions are temporarily unavailable, skip the video or offer an explicit later retry rather than polling.

Cached transcripts are fresh for seven days. If a refresh fails, captions up to 30 days old may be returned with stale:true and a warning. Each request makes one retrieval pass; offer an explicit later retry when needed.

Returns an error if the video ID is invalid, the video has no accessible YouTube captions, or the helper hits its rate limit.

Success includes source: promptbox-youtube-captions, cached and stale; cache hits also include cache_age_seconds. Stale recovery includes a warning and does not refresh the saved timestamp. Retrieval failures return HTTP 503 with retryable: true and diagnostics containing stage, HTTP status, response byte count and transport-error flag, without bodies or credentials. Upstream HTTP 429 uses error_code: youtube_rate_limited; HTTP 403 uses youtube_request_rejected; other failures remain caption_fetch_failed and do not prove captions are absent. Shared helper rate limits return HTTP 429 and retry_after. Callers may skip failed videos or offer an explicit later retry while retaining completed work. Invalid input returns HTTP 400.

Uploads temporary files, returns eight-character receipts and download URLs, reports receipt metadata, streams stored files, and supports explicit deletion. Files expire after three days and are deleted after the first API download by default unless auto_delete=0 is supplied. Each upload may be roughly 850 MB, but callers should inspect the JSON receipt before relying on storage.

POST multipart files with action=upload, save the returned receipt, and use its browser or API download URL. Files expire after three days and are deleted after the first API download by default unless auto_delete=0 was supplied.

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.

Converts up to 50,000 characters of text into one MP3 or WAV speech file, or streams complete WAV blocks for earlier playback, with selectable voices and speed. Defaults to shimmer (Katerina), MP3, and normal speed. Supports Chinese, English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, and Korean. Voice aliases are accepted; hear the selected voice before relying on its accent or timbre.

Send text by GET, JSON POST, or form POST, with optional voice, format, and speed. Save or play the returned audio bytes. For earlier playback, set stream=true and decode each WAV audio record from the application/x-ndjson response as it arrives. This is block streaming: the provider synthesizes each block completely. Do not wait for the whole response or automatically repeat a partially played request.

Each legacy alias maps to a distinct Qwen voice. Gender follows Alibaba's voice descriptions; Elias is female and Li is male. Neutral-sounding alloy maps to male Ethan.

By default, HTTP 200 with raw audio/mpeg or audio/wav bytes. With stream=true, HTTP 200 with application/x-ndjson: each line is {"type":"audio","index":0,"format":"wav","data":"BASE64"}, followed by {"type":"done","chunks":1}. An upstream failure after streaming starts produces {"type":"error","error":"..."}; a missing done record means an incomplete stream. Stop queued playback on failure or cancellation. Audio records may span multiple network reads; buffer until a newline. Before streaming begins, validation, configuration and rate-limit errors use the normal JSON and HTTP error contract. Errors return JSON {"success":false,"error":"..."} with HTTP 400, 405, 429, 500 or 502. The request quota counts each helper request once. Native Qwen voice names and legacy aliases are accepted case-insensitively. No caller API key is needed.

Converts up to 50,000 characters of text into one MP3 or WAV speech file using selectable Inworld voices. Defaults to Ashley and MP3. If Inworld is unavailable, a backup voice may sound different and supports only the ten languages documented for tts.php.

Send text by GET or POST with optional voice and format. Save or play the returned audio bytes. Send smaller blocks sequentially for earlier playback.

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 public Twitter/X, Facebook, and Reddit posts or comments and returns a formatted summary plus structured results. Defaults to Twitter/X, Facebook, and Reddit posts; select Reddit comments explicitly. Supports sorting, pagination, and optional Facebook sentiment. Queries are limited to 500 characters.

Send query by GET or POST and choose platforms when needed. Start with one page per platform. Read the structured results to display links, authors, and metadata, and check any warnings.

Compresses an uploaded MP4 into a smaller phone-compatible H.264/AAC MP4 using FFmpeg. The default balanced profile caps the long edge at 1280 pixels; small and quality target roughly 540p and 1080p, respectively. It accepts files up to 600 MB, has no Promptbox request quota, and retains no output unless save is explicitly enabled.

POST the source in the multipart video field with any optional compression settings, then save the returned video/mp4 bytes. Enable save only when a public archived copy is required.

const form = new FormData();
form.append('video', fileInput.files[0]);
form.append('profile', 'balanced');

const response = await fetch('https://www.promptbox.cn/api/video_compress.php', {
  method: 'POST',
  credentials: 'omit',
  body: form
});
if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error);
}

const blob = await response.blob();
const url = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.download = 'video-smaller.mp4';
link.click();
setTimeout(() => URL.revokeObjectURL(url), 30000);

A successful POST returns raw video/mp4 bytes with a downloadable filename. Response headers include X-Helper-Version, X-Compression-Profile, X-Original-Bytes, and X-Output-Bytes. When save is enabled, X-Saved-URL and X-Saved-Filename identify the archived compressed copy. These headers are CORS-exposed. Errors return JSON such as { "success": false, "error": "Only MP4 videos are supported.", "code": 415 }. The helper has no Promptbox request quota. Browser origin restrictions described above still apply.

Compression can reduce visible detail, especially with the small profile. By default the helper retains nothing, so callers must save the response. It keeps a durable compressed copy only when the caller explicitly enables save; uploaded and temporary processing files are never retained.

Searches the live web and returns a number or a plain-text answer. The default returns the first number found; text=true returns prose. Queries are capped at 400 characters, and url can restrict the source domain. Use web_read.php to read a particular page or file.

Send prompt by GET or POST and read plain text. Set text=true for a prose answer, max_sentences for a length cap, or url for a source domain. Use mode=image_prompt_refine only to improve an image prompt; that mode does not search the web.

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.

Extracts text and source metadata from one public URL or uploaded file, including webpages, PDFs, office documents, feeds, images, media, and YouTube captions. Images use llm_chatgpt.php with model=lite (currently gpt-6-luna) at original resolution. JPEG, PNG, and WebP bytes are sent unchanged; other image formats are converted to full-resolution PNG, using the first frame for animated images. Document and text-bearing pictures request every readable word, number, table cell, footnote, and handwritten note in the original language and reading order, with unreadable portions marked [illegible]; scenes receive a description plus all visible text. Search terms return a generated search summary with source links/snippets, answer status and warnings. Search success is not answer verification; insufficient or mismatched-date evidence needs a targeted follow-up. Uploads and supported document downloads are limited to 10 MB; oversized downloads return an error instead of partial file bytes. PDFs are limited to 30 pages per request. Each page is checked separately: usable embedded text is preserved, while pages with images/form objects or unusable text are rendered at 240 dpi (up to 3200 pixels per side, lossless PNG) for OCR in batches of up to three pages. Page boundaries, paragraph breaks, table spacing, and literal characters are retained. OCR responses must finish normally and cover every requested page; failures are errors, never silent partial success. Automatic checks cannot detect every faulty text layer; use pdf_ocr=always to visually transcribe all pages. OCR may misread characters or numbers; verify critical values against the original. Uncertain spans are marked [illegible]. PDF, Office, ebook, plain/structured text, email and feed output defaults to 500,000 characters for URLs and uploads, with explicit caller limits respected. Image output defaults to 500,000 characters, supports an explicit max_chars up to 500,000, and requests up to 32,768 model completion tokens including reasoning; exceptionally dense images may exceed the model output allowance. HTML, media transcripts and search output default to 12,000 characters and are capped at 30,000 for URLs/search or 500,000 for uploads. Direct HTTP reading follows up to 10 redirects, validating each destination. An eleventh redirect returns HTTP 424 with error_kind:"target_redirect_error"; this error does not invoke browser or search fallback. Empty HTML or recognizable JavaScript/loading shells first use browser.php in a new isolated session, with no saved login profile. The reader waits once for 2.5 seconds after navigation and extracts rendered main-page text, then closes its session. Version 3.4 also retries HTTP 403 HTML responses once in an isolated browser, with one 8-second wait for automatic page loading. Successful retries return reader_mode: "browser_text" and browser_fallback.trigger_status: 403. Persistent login or verification challenges return target_access_required; unavailable browser reads preserve the HTTP error. This 403 path does not use search fallback or submit challenges. Short valid pages stay on direct extraction. If browser reading is unavailable or still has no useful text, Tavily is the final search fallback. Search answers may summarize a source rather than reproduce the full page. DOCX preserves paragraphs/tables and includes headers, footers, footnotes, endnotes and comments. PPTX follows presentation slide order and includes speaker notes. XLSX preserves sheet order, cell addresses, shared strings, dates, numeric formatting, booleans, comments, hyperlinks and merged ranges; saved formula results are labeled and never recalculated. EPUB follows the package spine rather than ZIP order. ODT preserves document text, tables and headers/footers. RTF decodes Unicode and escaped text; EML decodes MIME headers and message bodies while listing attachments separately. JSON retains its original values and syntax, including false, null, empty values and large numbers. Plain text and CSV retain line breaks and literal characters; XML is returned as a labeled hierarchy. RSS/Atom include all entries up to the explicit 1,000-entry limit, including Atom link URLs. Office and ebook raster images use embedded-image OCR by default; see document_ocr and coverage warnings below. Legacy binary DOC/XLS/PPT files are explicitly unsupported.

Supply exactly one url containing a public URL or search terms, or one multipart file. Use GET or POST for URLs/search and multipart POST for files. Inspect text, reader_mode, source_type, and truncated. For PDFs also inspect pdf.page_count, pdf.ocr_pages, pdf.blank_pages, and pdf.warnings. Inspect document.extraction_complete and document.warnings for non-PDF documents. Set document_ocr=off when only native Office/ebook text is needed. Submit email attachments separately. Split PDFs exceeding 30 pages into smaller files. OCR can take several minutes; each batch consumes one shared Gemini request and inherits its rate limit. The only automatic HTTP-error retry is the single browser attempt for HTML 403 responses. Set fallback=off to disable both browser and search fallback and use direct extraction only. Search terms still perform a search, with a 400-character query cap. Inspect answer_status and sources before relying on a search answer; for time-sensitive questions match the source date and destination timezone. Search queries do not automatically enter the URL browser-rendering fallback.

Returns application/json. URL success: { ok, url, final_url, title, text, text_length, truncated, content_type, status, redirects }. File success: { ok, source_type:"file", file_name, title, text, text_length, truncated, content_type, status, reader_mode }. Search success: { ok, source_type:"web_search", query, title, text, text_length, truncated, content_type, status, reader_mode:"web_search" }. A search fallback retains url, final_url, and redirects, adds source_type:"web_search", and uses reader_mode:"web_search_fallback". These results are Tavily search answers, not guaranteed full-page extraction. Search terms use the reader’s 400-character query cap and shared web rate limits; unavailable answers return HTTP 502 for search requests, and upstream rate limits propagate HTTP 429 with Retry-After when supplied. Reader modes include html_text, browser_text for rendered webpage text, document_text, pdf_text for embedded PDF text, pdf_ocr for fully OCR-read PDFs, pdf_mixed for combined embedded-text and OCR pages, archive_document_text, feed_text, youtube_transcript, image_description, media_transcript, web_search, web_search_fallback, and msn_article_json. Errors return { ok:false, error, error_kind, target_status? }. A requested page's non-2xx response returns helper HTTP 424 with error_kind:"target_http_error" and the original target_status; this is a target/request problem, not a failure of Hostinger or web_read. Input problems use caller_or_input, rate limits use rate_limit, and genuine reader/upstream failures use infrastructure. JSONP applies only to GET URL/search requests.

PDF success also includes pdf: { page_count, ocr_pages, text_pages, blank_pages, extraction_complete, warnings }. Page numbers are one-based. extraction_complete:true means every page completed extraction before the caller's character limit; it is not a guarantee of recognition accuracy. truncated:true means the returned text was shortened by max_chars. text_length retains its existing UTF-8 byte-count meaning. Blank/non-text pages appear as Page N followed by [No readable text]. PDF errors include HTTP 413 (pdf_page_limit or resource_too_large), 422 (pdf_invalid, pdf_render_failed, pdf_unreadable), 502/504 (pdf_ocr_incomplete), or 503 for unavailable OCR/rendering. Encrypted/damaged PDFs that cannot be read are rejected. No legacy font-blind extraction or unverified whole-document OCR fallback is used.

Office, ebook, email, RTF, text and feed responses add document: { format, extraction_complete, warnings, units?, embedded_images?, entries? }. units counts sheets, slides, EPUB spine sections, or one main DOCX/ODT document. embedded_images counts discovered image references, not necessarily unique images or completed OCR calls. extraction_complete:false indicates known skipped content or missing formula results; true means no known omission was detected, not guaranteed visual fidelity. Shape reading order, automatic list numbering, equation layout, master/layout text, embedded charts/objects and complex RTF font mappings are not fully reconstructed. Email attachments and remote linked resources are not fetched. Some apparently readable text may still be wrong; export complex layouts to PDF for visual reading. Encrypted or damaged archives, invalid JSON/XML/RTF and ambiguous text encodings return HTTP 422 (document_invalid); legacy binary Office formats return 415 (document_unsupported). Text accepts UTF-8, BOM-marked UTF-16/32, and supported declared charsets; undeclared non-UTF-8 text must be converted to UTF-8. XML custom entities and document-type declarations are rejected. Archive limits: 10,000 entries, 20 MB per expanded part, 50 MB expanded total; XLSX permits up to 100,000 stored cells. These limits and the 10-image/1,000-feed-entry limits return HTTP 413 (document_limit), never silent partial output. Embedded-image OCR failures return HTTP 502/504 (document_ocr_incomplete). Native document text is not sent to a model; embedded images are sent only when OCR is enabled.

Browser success retains URL metadata and adds reader_mode:"browser_text", source_type:"url", browser_fallback:{attempted:true,status:"ready"}, and warnings. If search follows an unsuccessful browser attempt, browser_fallback.status is unavailable or no_readable_content. Rendered text honors the normal URL character limit (12,000 default, 30,000 maximum), with Unicode-aware truncated reporting. Rendering captures one snapshot without clicking, scrolling or filling forms; later-loaded and embedded-frame content may be absent. Recognized login/verification pages return HTTP 422 with error_kind:"target_access_required"; they are not bypassed or replaced with search answers. Initial non-2xx target responses and PDF/document extraction errors remain errors. Browser rendering uses the server's existing private credential, shares browser quota/capacity, and normally consumes three operations (create, read, close). No existing session or saved profile is selected. Navigation and cleanup use fixed timeouts; if cleanup cannot be confirmed, idle expiry applies. The browser helper's own bounded navigation recovery policy still applies; web_read does not retry browser calls.

Search and search-fallback responses add answer_type:"generated_search_summary", answer_status:"unverified"|"insufficient_evidence", sources:[{url,title,snippet,published_date}], retrieved_at, query_truncated and warnings. The reader requests one advanced Tavily search with up to five results and retains source snippets of at most 2,000 characters each. It shares the existing web search credentials and rate limits. Advanced search uses two provider credits; it does not guarantee a matching dated forecast. ok:true confirms successful retrieval, not a verified answer. Missing-evidence detection is a conservative text heuristic; all other generated summaries remain unverified. Source timestamps may be absent, and retrieval time must not be treated as the source's date. max_chars limits the answer text; the separately bounded source snippets remain available for follow-up. For weather and other current facts, inspect a dated source matching the requested location and date rather than treating averages or another day's conditions as the answer.

Searches YouTube, reads available captions from up to five relevant videos, and returns an answer based on those transcripts. Choose it to research a question across videos; use transcript.php for captions from one known video. Videos without accessible captions are skipped.

Send a question in prompt by GET or POST and read the JSON content answer. If no usable videos or captions are available, inspect the error and offer an explicit later retry. Do not poll.

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.