> For the complete documentation index, see [llms.txt](https://developers.raycast.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.raycast.com/api-reference/ai.md). # AI The AI API provides developers with seamless access to AI functionality without requiring API keys, configuration, or extra dependencies. {% hint style="info" %} Some users might not have access to this API. If a user doesn't have access to Raycast Pro, they will be asked if they want to get access when your extension calls the AI API. If the user doesn't wish to get access, the API call will throw an error. You can check if a user has access to the API using [`environment.canAccess(AI)`](/api-reference/environment.md). {% endhint %} ## API Reference ### AI.ask Ask AI anything you want. Use this in “no-view” Commands, effects, or callbacks. In a React component, you might want to use the [useAI util hook](/utilities/react-hooks/useai.md) instead. #### Signature ```typescript async function ask(prompt: string, options?: AskOptions): Promise & EventEmitter; ``` #### Example {% tabs %} {% tab title="Basic Usage" %} ```typescript import { AI, Clipboard } from "@raycast/api"; export default async function command() { const answer = await AI.ask("Suggest 5 jazz songs"); await Clipboard.copy(answer); } ``` {% endtab %} {% tab title="Error handling" %} ```typescript import { AI, showToast, Toast } from "@raycast/api"; export default async function command() { try { await AI.ask("Suggest 5 jazz songs"); } catch (error) { // Handle error here, eg: by showing a Toast await showToast({ style: Toast.Style.Failure, title: "Failed to generate answer", }); } } ``` {% endtab %} {% tab title="Stream answer" %} ```typescript import { AI, getSelectedFinderItems, showHUD } from "@raycast/api"; import fs from "fs"; export default async function main() { let allData = ""; const [file] = await getSelectedFinderItems(); const answer = AI.ask("Suggest 5 jazz songs"); // Listen to "data" event to stream the answer answer.on("data", async (data) => { allData += data; await fs.promises.writeFile(`${file.path}`, allData.trim(), "utf-8"); }); await answer; await showHUD("Done!"); } ``` {% endtab %} {% tab title="User Feedback" %} ```typescript import { AI, getSelectedFinderItems, showHUD } from "@raycast/api"; import fs from "fs"; export default async function main() { let allData = ""; const [file] = await getSelectedFinderItems(); // If you're doing something that happens in the background // Consider showing a HUD or a Toast as the first step // To give users feedback about what's happening await showHUD("Generating answer..."); const answer = await AI.ask("Suggest 5 jazz songs"); await fs.promises.writeFile(`${file.path}`, allData.trim(), "utf-8"); // Then, when everythig is done, notify the user again await showHUD("Done!"); } ``` {% endtab %} {% tab title="Check for access" %} ```typescript import { AI, getSelectedFinderItems, showHUD, environment } from "@raycast/api"; import fs from "fs"; export default async function main() { if (environment.canAccess(AI)) { const answer = await AI.ask("Suggest 5 jazz songs"); await Clipboard.copy(answer); } else { await showHUD("You don't have access :("); } } ``` {% endtab %} {% endtabs %} #### Parameters | Name | Description | Type | | ---------------------------------------- | ------------------------------------------------------------ | --------------------------------- | | prompt\* | The prompt to ask the AI. | `string` | | options | Options to control which and how the AI model should behave. | [`AI.AskOptions`](#ai.askoptions) | #### Return A Promise that resolves with a prompt completion. ### AI.refreshModels Refreshes the models provided by this extension. Only relevant for extensions that [provide AI models](/ai/provide-ai-models.md): call it after changing locally available models, for example from a Manage Models command. #### Signature ```typescript async function refreshModels(): Promise; ``` #### Example ```typescript import { AI, showHUD } from "@raycast/api"; export default async function command() { await downloadModel("llama-3.3-70b"); await AI.refreshModels(); await showHUD("Model installed"); } ``` #### Return A Promise that resolves when Raycast has re-run your extension's `getModels` export. ### AI.experimental\_decide Answer typed questions about a shared state in one request. Use a `noul` question for a yes/no probability, a `choice` question to select from named options, or a `score` question to rate against ordered levels. {% hint style="warning" %} This API is experimental. Its signature, question types, and response format may change in future releases. {% endhint %} Pass `{ state, questions }` as the first argument and an optional `{ signal }` as the second. Answer types are inferred from the questions you pass. #### Example ```typescript import { AI, showHUD } from "@raycast/api"; export default async function command() { const answers = await AI.experimental_decide({ state: { message: "The app crashes whenever I open the billing page. Please fix it today!", page: "billing", }, questions: { urgent: { type: "noul", instructions: "Does this need urgent attention?" }, severity: { type: "score", instructions: "How severe is the issue?", criteria: ["Cosmetic", "Workaround available", "Blocking"], }, category: { type: "choice", instructions: "Classify the request.", criteria: { bug: "A defect or crash in the product", billing: "A question about charges or subscriptions", other: null, }, }, }, }); // Typed as "bug" | "billing" | "other" when questions are passed as a literal. await showHUD(`${answers.category.choice}: severity ${answers.severity.score}`); } ``` `input.state` is the JSON-serializable value all questions are evaluated against. Strings are passed as is; other values are serialized with `JSON.stringify`. Values that cannot be serialized, such as circular objects, BigInts, or top-level `undefined`, reject the promise. `input.questions` maps your question names to one of these shapes: * `{ type: "noul", instructions: string }`: returns `{ type: "noul", noul: number }`, where `noul` is a probability between 0 and 1. * `{ type: "choice", instructions: string, criteria: Record }`: returns `{ type: "choice", choice, confidence: number, probabilities }`. Each criteria key is an allowed choice; its value describes that choice, or is `null` when the name is sufficient. `probabilities` contains a probability between 0 and 1 for each offered choice. * `{ type: "score", instructions: string, criteria: readonly string[] }`: `criteria` contains 2–10 non-empty descriptions in order from low to high. Returns `{ type: "score", score: number, confidence: number, legend, probabilities }`. The score ranges from `0` to `criteria.length - 1` and can be fractional. `legend` maps level indices (string keys such as `"0"`) to descriptions; `probabilities` maps those indices to probabilities between 0 and 1. The result is the answers object, keyed directly by your question names. Unlike `AI.ask`, this method returns a single result and does not stream text. Pass `options.signal` to stop waiting for a result, for example `{ signal: AbortSignal.timeout(10_000) }`. The backend may finish a request that has already been submitted. ## Types ### AI.Creativity Concrete tasks, such as fixing grammar, require less creativity while open-ended questions, such as generating ideas, require more. ```typescript type Creativity = "none" | "low" | "medium" | "high" | "maximum" | number; ``` If a number is passed, it needs to be in the range 0-2. For larger values, 2 will be used. For lower values, 0 will be used. ### AI.Model The AI model to use to answer to the prompt. Defaults to `AI.Model["OpenAI_GPT-5.6_Luna"]`. | Model | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | OpenAI\_GPT-5\_mini | OpenAI's compact model, great for well-defined tasks and precise prompts. | | OpenAI\_GPT-5\_nano | OpenAI's lightweight model, great for summarization and classification tasks. | | OpenAI\_GPT-4.1 | OpenAI's previous generation flagship model optimized for complex problem solving. | | OpenAI\_GPT-4.1\_mini | Balanced GPT-4.1 variant optimized for speed and cost efficiency. | | OpenAI\_GPT-4.1\_nano | Fastest and most cost-effective GPT-4.1 variant. | | OpenAI\_GPT-4 | Previous generation GPT-4 model with broad knowledge and complex instruction handling. | | OpenAI\_GPT-4o | Advanced OpenAI model optimized for speed and complex problem solving. | | OpenAI\_GPT-4o\_mini | Fast and intelligent model for everyday tasks. | | OpenAI\_GPT-5.1 | OpenAI's model with adaptive reasoning, great for coding and agentic tasks across domains. | | OpenAI\_GPT-5.2 | OpenAI's GPT-5.2-class model for professional work and long-running agents with strong tool-calling. | | OpenAI\_GPT-5.3\_Instant | OpenAI's fast, capable GPT-5.3-class model for everyday work with improved info-seeking, how-tos, and technical writing. | | OpenAI\_GPT-5.3\_Codex | A version of GPT-5.3 optimized for agentic coding tasks in Codex or similar environments. | | OpenAI\_GPT-5.4 | OpenAI's high-performance GPT-5.4-class model for professional work and long-running agents with state-of-the-art tool-calling. | | OpenAI\_GPT-5.4\_mini | OpenAI's strongest mini model yet for coding and agentic workflows. | | OpenAI\_GPT-5.4\_nano | OpenAI's cheapest GPT-5.4-class model for simpler tasks. | | OpenAI\_GPT-5.5 | OpenAI's high-performance GPT-5.5-class model for complex reasoning and long-running agentic work. | | OpenAI\_GPT-5.5\_Instant | OpenAI's fast, capable model for everyday work with improved info-seeking, how-tos, and technical writing. | | OpenAI\_GPT-5.6\_Sol | OpenAI's frontier GPT-5.6 model for complex, professional-grade reasoning and long-running agentic work. | | OpenAI\_GPT-5.6\_Terra | OpenAI's balanced GPT-5.6 model for everyday work across writing, analysis, and coding. | | OpenAI\_GPT-5.6\_Luna | OpenAI's fastest GPT-5.6 model for responsive everyday tasks. | | OpenAI\_GPT-6\_Astra | OpenAI's frontier GPT-6 model for the hardest end-to-end reasoning, coding, and agentic work. | | OpenAI\_GPT-6\_Sol | OpenAI's GPT-6 model for complex coding and agentic workflows. | | OpenAI\_GPT-6\_Luna | OpenAI's efficient GPT-6 model for focused, high-volume tasks. | | OpenAI\_o4-mini | Fast, efficient model optimized for coding and visual tasks. | | OpenAI\_o3-mini | Fast reasoning model optimized for STEM tasks. | | Groq\_GPT-OSS\_20b | OpenAI's first open-source model, 20b variant. | | Groq\_GPT-OSS\_120b | OpenAI's first open-source model, 120b variant. | | Anthropic\_Claude\_Haiku\_4.5 | Anthropic's offering focusing on being the best combination of performance and speed. | | Anthropic\_Claude\_Sonnet\_4.6 | Anthropic's previous generation Sonnet model with high intelligence across most tasks. | | Anthropic\_Claude\_Sonnet\_5 | Anthropic's best combination of speed and intelligence, with combined reasoning and non-reasoning capabilities. | | Anthropic\_Claude\_Opus\_4.7 | Anthropic's previous generation Opus model with combined reasoning and non-reasoning capabilities. | | Anthropic\_Claude\_Opus\_4.8 | Anthropic's previous generation Opus model with combined reasoning and non-reasoning capabilities. | | Anthropic\_Claude\_Opus\_5 | Anthropic's previous flagship Opus model with combined reasoning and non-reasoning capabilities. | | Anthropic\_Claude\_Opus\_5.5 | Anthropic's most powerful model with combined reasoning and non-reasoning capabilities. | | Anthropic\_Claude\_Fable\_5.1 | Anthropic's Mythos-class model for complex tasks, with safeguards for general use. | | Perplexity\_Sonar | Fast Perplexity model with integrated search capabilities. | | Perplexity\_Sonar\_Pro | Advanced Perplexity model for complex queries with search integration. | | Mistral\_Nemo | Small, Apache-licensed model built with NVIDIA. | | Mistral\_Large | Top-tier reasoning model with strong multilingual support. | | Mistral\_Medium | A powerful, cost-effective, frontier-class multimodal model. | | Mistral\_Small | Latest enterprise-grade small model with improved reasoning. | | Mistral\_Codestral | Specialized model for code-related tasks and testing. | | Google\_Gemini\_3.8\_Flash | Balances speed with intelligence for agentic and multimodal tasks. | | Google\_Gemini\_3.7\_Flash | Balances speed with intelligence for agentic and multimodal tasks. | | Google\_Gemini\_3.6\_Flash | Balances speed with intelligence for agentic and multimodal tasks. | | Google\_Gemini\_3.5\_Flash | Near-Pro intelligence with Flash-tier speed and cost for agentic workflows. | | Google\_Gemini\_3.5\_Flash\_Lite | Fast, cost-effective model for high-throughput agentic workflows and data processing. | | Google\_Gemini\_3.1\_Flash\_Lite | Ultra-fast, cost-effective model for high-volume tasks and lightweight agentic workflows. | | Google\_Gemini\_3\_Flash | Fast thinking model with strong balance of speed, performance, and value. | | Google\_Gemini\_3.1\_Pro | Next generation thinking model for complex problem solving. | | Google\_Gemini\_2.5\_Pro | Previous generation thinking model for complex problem solving. | | Google\_Gemini\_2.5\_Flash | Fast, well-rounded thinking model. | | Google\_Gemini\_2.5\_Flash\_Lite | Fast model optimized for large-scale text output. | | xAI\_Grok-4.7 | xAI's latest flagship Grok model, delivering frontier reasoning, stronger coding, and multimodal understanding. | | xAI\_Grok-4.6 | xAI's previous flagship Grok model with frontier reasoning, strong coding, and multimodal understanding. | | xAI\_Grok-4.5 | xAI's earlier flagship Grok model with strong reasoning, coding, and multimodal understanding. | | xAI\_Grok-4.3 | xAI's advanced reasoning model with enhanced capabilities. | | Vercel\_GLM-5.2 | Z.AI's previous flagship model with MoE + DSA architecture for efficient long-context coding, agentic, and reasoning tasks. | | Vercel\_GLM-5.3 | Z.AI's flagship model with stronger coding and agent capabilities than GLM-5.2, driven by post-training on the same base. | | Vercel\_GLM-5.3\_Flash | Z.AI's native multimodal coding model with hybrid attention, visual coding, and agentic tool use. | | Vercel\_Kimi\_K2.7\_Code | Moonshot AI's code-optimized trillion-parameter multimodal model with enhanced coding capabilities and agentic tool-calling. | | Vercel\_Kimi\_K3 | Moonshot AI's trillion-parameter multimodal model with strong reasoning and agentic tool-calling. | | Vercel\_Gemma\_4\_31B | Google's open-weight dense model with vision and 140+ language support, tuned for output quality over throughput. | | Vercel\_Inkling | Thinking Machines' open-weights multimodal MoE model with controllable thinking effort for reasoning, coding, and tool use. | | Vercel\_Inkling\_Small | Thinking Machines' smaller, faster open-weights multimodal MoE model with controllable thinking effort for reasoning, coding, and tool use. | | Vercel\_DeepSeek\_V4\_Flash | DeepSeek's lightweight V4 MoE model tuned for fast, low-cost coding, reasoning, and agentic tasks. | | Vercel\_DeepSeek\_V4.1\_Flash | DeepSeek's lightweight V4.1 MoE model tuned for fast, low-cost coding, reasoning, and agentic tasks. | | Vercel\_DeepSeek\_V4\_Pro | DeepSeek's 1.6T parameter MoE model optimized for coding, reasoning, and agentic tasks with a 1M token context window. | | Vercel\_Qwen3.8\_Max | Alibaba's 2.4-trillion-parameter MoE flagship with native visual understanding for long-horizon coding and professional work. | If a model isn't available to the user (or has been disabled by the user), Raycast will fallback to a similar one. ### AI.ModelSelector The AI model to use to answer the prompt. ```typescript type ModelSelector = AI.Model | { id: string }; ``` Pass an [`AI.Model`](#ai.model) value to use a Raycast-hosted model, or `{ id: "..." }` to use a model [provided by this extension](/ai/provide-ai-models.md) through `ai.modelProvider`. The ID is the local model `id` returned by `getModels()`. ### AI.AskOptions #### Properties | Property | Description | Type | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | creativity | Concrete tasks, such as fixing grammar, require less creativity while open-ended questions, such as generating ideas, require more. If a number is passed, it needs to be in the range 0-2. For larger values, 2 will be used. For lower values, 0 will be used. | [`AI.Creativity`](#ai.creativity) | | model | The AI model to use to answer to the prompt. Pass an `AI.Model` value to use a Raycast-hosted model, or `{ id: "..." }` to use a model provided by this extension through `ai.modelProvider`. The ID is the local model `id` returned by `getModels()`. | [`AI.ModelSelector`](#ai.modelselector) | | signal | Abort signal to cancel the request. | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | ## Rate Limit To prevent accidental programmatic over-usage of AI quota, Raycast enforces rate limits on AI requests made from extensions. | Limit per minute | Limit per hour | | ---------------- | -------------- | | 10/minute | 100/hour | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.raycast.com/api-reference/ai.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.