OpenAI - Shanone Documentation

Shanone provides 10 OpenAI tools, independent of the model powering your agent. Register your OpenAI API key in Integrations → OpenAI. Your project must have access to the selected model and sufficient API balance. User calls never fall back to Shanone’s server API key. Use shanone_get_tool_schema for the complete argument schema, then call shanone_execute_tool. Existing role, service, tool and parameter policies apply. Newly registered cancellation tools are disabled by default and require permission; enabling a tool does not bypass job ownership checks. No new Plus-only restriction is introduced for these tools.

Tool reference

Tool	Required arguments	Options and behavior
`openai_generate_image`	`prompt`	`model`, `size`, `quality`, `output_format`, `output_compression`, `n`, `moderation`, `background`
`openai_edit_image`	`prompt`, `image_url`	`mask_url`, up to 15 `reference_image_urls`, `model`, `size`, `quality`, `output_format`, `output_compression`, `n`, `background`
`openai_deep_research`	`query`	`model`, `reasoning_effort`, `max_tool_calls`, `wait_for_completion`, `max_wait_seconds`; starts a background job
`openai_get_research_status`	`response_id`	Returns report text, citations, state and usage
`openai_cancel_research`	`response_id`	Cancels a pending research job; terminal jobs return their current state
`openai_transcribe_audio`	`audio_url`	`model`, `prompt`, `language`; returns text and model-specific segments
`openai_generate_speech`	`text`	`voice`, `output_format`, `speed`, `instructions`; returns an audio artifact
`openai_analyze_file`	`file_url`, `query`	`memory_limit`; starts a background Code Interpreter job
`openai_get_analysis_status`	`response_id`	Returns analysis text, citations and generated artifact URLs
`openai_cancel_analysis`	`response_id`	Cancels a pending analysis job

Images

The existing default is gpt-image-2. You can also select gpt-image-2.5-sunburst or gpt-image-2.5-flare.

All three support quality: auto, low, medium, high. GPT Image 2.5 also supports xhigh and max.
background: auto by default; transparent output requires GPT Image 2.5 and PNG/WebP. JPEG cannot preserve transparency.
size: auto or WIDTHxHEIGHT. Edges must be multiples of 16, at most 3840px, aspect ratio at most 3:1, and total pixels 655,360–8,294,400. Resolutions above 2560×1440 are experimental.
n: 1–10. prompt: 1–32,000 characters. output_format: png (default), jpeg, webp. Compression 0–100 applies only to JPEG/WebP.
Editing accepts public HTTPS PNG/JPEG/WebP files. Each must be below 50 MB and at most 20 megapixels; combined downloaded and normalized inputs are each limited to 100 MB. Input downloads have a shared 60-second budget.
A mask applies to the first image and must match its dimensions. Transparent alpha pixels specify the editing region. Black/white colors alone are insufficient.

The response separates requested parameters from provider-reported actual values. Each stored image has url, width, height, format, size_bytes and expires_at. status: partial means only some artifacts were saved. Base64 data is never used as a fallback. A failed save does not mean OpenAI generation was free.

Background research

openai_deep_research uses o3-deep-research by default; o4-mini-deep-research is also supported. It sends background: true and returns response_id, status, and next_action. max_tool_calls defaults to 20 (Shanone range 1–100) to bound provider tool use. reasoning_effort remains accepted as a deprecated compatibility argument but is not sent: the current Deep Research guide does not establish a model-specific effort contract. Supplying it returns a warning; provider defaults apply. wait_for_completion now defaults to false. If enabled, waiting is capped at 30 seconds, even when a legacy caller supplies a larger max_wait_seconds.

{
  "tool_name": "openai_deep_research",
  "arguments": {
    "query": "Compare battery recycling technologies with cited sources",
    "max_tool_calls": 15
  }
}

Poll openai_get_research_status using the returned ID, normally after 15 seconds. queued/in_progress means accepted, not completed. A completed result contains output, text_blocks, citations, and usage. Citation offsets refer to the text_blocks entry identified by text_index. incomplete preserves partial output and incomplete_details. Cancelling does not refund work already performed. Background mode has provider-side retention; use only where your organization’s data-retention policy permits it.

Audio

openai_transcribe_audio accepts files up to 25 MB. URL paths must end in .mp3, .mp4, .mpeg, .mpga, .m4a, .wav, or .webm.

Model	Response	Constraints
`gpt-transcribe` (default)	Text, detected languages, usage when available	Optional prompt; the ISO-639-1 `language` hint is sent in the provider’s `languages` array
`gpt-4o-transcribe-diarize`	`diarized_json` with speaker/start/end segments	Automatic chunking; `prompt` is rejected
`whisper-1`	`verbose_json` with segments	Optional prompt and language hint

openai_generate_speech uses gpt-4o-mini-tts. Text and optional instructions are each limited to 4096 characters. Speed is 0.25–4 (default 1); the default voice is coral. Supported formats: MP3, Opus, AAC, FLAC, WAV and PCM. PCM is raw 24kHz, 16-bit signed little-endian audio. Inform listeners that the voice is AI-generated. The binary speech endpoint does not return token usage; Shanone reports usage: null.

File analysis

openai_analyze_file accepts public HTTPS CSV/TSV/JSON/TXT/XLSX/PDF files up to 20 MB (Shanone limit). It uploads the file with purpose: user_data and a 24-hour expiration, then starts a background gpt-6-astra response with Code Interpreter. memory_limit is 1g by default; 4g, 16g, and 64g are available at different provider costs. Poll openai_get_analysis_status for text, citations and generated files. Inactive Code Interpreter containers expire after 20 minutes: retrieve results promptly. Files successfully saved by Shanone receive URLs valid for 24 hours. Artifact retrieval warnings mean the report may be available even when a file could not be saved.

Errors, ownership and billing

Input URLs must use public HTTPS on port 443, without embedded credentials or redirects. Private addresses and private DNS results are rejected; connections are pinned to validated addresses.
Job retrieval/cancellation requires the same Shanone user and OpenAI API key used to create it. Legacy jobs without ownership metadata and jobs created before a key rotation cannot be retrieved through these tools; use the original OpenAI project separately.
Failures retain the string error and add error_details with code, message, retryable and provider request IDs when available. Incomplete responses retain usable partial data.
OpenAI tool failures propagate as failures through shanone_execute_tool and Analytics. Worker failures never automatically rerun OpenAI generation locally. A timeout can mean completion is unknown; do not blindly repeat a paid operation.
Shanone Tool Calls and OpenAI API usage are separate charges. Status checks follow Shanone’s existing Tool Call billing rules; there is no new polling exemption. max_tool_calls is an OpenAI-side work limit, not a Shanone billing count.
Stored image/audio/generated-file links now expire after 24 hours, replacing the previous image tool’s seven-day token URLs. Download artifacts before expiry.

API mapping and sources

Verified against official documentation on 2026-09-25:

Capability	API endpoint	Official documentation
Generate/edit images	`POST /v1/images/generations`, `POST /v1/images/edits`	Images
Start/get/cancel background jobs	`POST /v1/responses`, `GET /v1/responses/{id}`, `POST /v1/responses/{id}/cancel`	Background mode, Deep Research
Transcribe/synthesize audio	`POST /v1/audio/transcriptions`, `POST /v1/audio/speech`	Transcription, Speech
Upload analysis input	`POST /v1/files`	Files
Retrieve generated analysis file	`GET /v1/containers/{container_id}/files/{file_id}/content`	Code Interpreter

​Tool reference

​Images

​Background research

​Audio

​File analysis

​Errors, ownership and billing

​API mapping and sources