---
title: "useAiStream"
description: "useAiStream, auto-imported in the app: its options, return value and types."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/use-ai-stream"
---
# useAiStream

## Interfaces

### AiStreamApi

Defined in: [src/runtime/vue/composables/use-ai-stream.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts)

The `{ start, body }` pair an `ai.stream(...)` definition exports.

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="start">
        
      </a>
      
       <code>
        start
      </code>
    </td>
    
    <td>
      <code>
        unknown
      </code>
    </td>
    
    <td>
      The start action — reserves credits and returns <code>
        { streamId }
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="body">
        
      </a>
      
       <code>
        body
      </code>
    </td>
    
    <td>
      <code>
        unknown
      </code>
    </td>
    
    <td>
      The reactive persisted-body query.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseAiStreamOptions

Defined in: [src/runtime/vue/composables/use-ai-stream.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="streamid">
        
      </a>
      
       <code>
        streamId?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Attach to an existing stream (viewer mode — e.g. after a reload) instead of driving a new one. The persisted body streams in reactively.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="url">
        
      </a>
      
       <code>
        url?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Override the stream endpoint. Default <code>
        <convex site url>/ai/stream
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="headers">
        
      </a>
      
       <code>
        headers?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        Record
      </code>
      
      <<code>
        string
      </code>
      
      , <code>
        string
      </code>
      
      > | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Extra headers for the driving fetch.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseAiStreamReturn

Defined in: [src/runtime/vue/composables/use-ai-stream.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="text">
        
      </a>
      
       <code>
        text
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      The streamed text so far (live while driving; persisted otherwise).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="status">
        
      </a>
      
       <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<a href="#aistreamstatus">
        <code>
          AiStreamStatus
        </code>
      </a>
      
      >
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isstreaming">
        
      </a>
      
       <code>
        isStreaming
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="streamid-1">
        
      </a>
      
       <code>
        streamId
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The active stream's id — hand it to another client to watch along.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      < | <a href="https://nuxt-backend.dev/docs/reference/api/functions#backenderror">
        <code>
          BackendError
        </code>
      </a>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      Why the last <code>
        start
      </code>
      
       was refused — <code>
        insufficient_credits
      </code>
      
      , <code>
        rate_limited
      </code>
      
      , <code>
        unauthenticated
      </code>
      
      , … (see <code>
        getBackendError
      </code>
      
      ) — or <code>
        null
      </code>
      
      . Cleared when the next <code>
        start
      </code>
      
       begins.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="start-1">
        
      </a>
      
       <code>
        start
      </code>
    </td>
    
    <td>
      (<code>
        args?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      Start a new metered stream: runs the <code>
        start
      </code>
      
       action (credits reserve, rate limit), then drives the HTTP stream. Resolves with the stream id as soon as driving begins. A refused start ends in <code>
        status: 'error'
      </code>
      
       with the refusal in <code>
        error
      </code>
      
      , and rejects.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="stop">
        
      </a>
      
       <code>
        stop
      </code>
    </td>
    
    <td>
      () => <code>
        void
      </code>
    </td>
    
    <td>
      Abort the driving fetch (the server releases the unfinished spend).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts" rel="nofollow">
        src/runtime/vue/composables/use-ai-stream.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

## Type Aliases

### AiStreamStatus

```ts
type AiStreamStatus = "idle" | "pending" | "streaming" | "done" | "error" | "timeout";
```

Defined in: [src/runtime/vue/composables/use-ai-stream.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts)

## Functions

### useAiStream()

```ts
function useAiStream(stream, options?): UseAiStreamReturn;
```

Defined in: [src/runtime/vue/composables/use-ai-stream.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-ai-stream.ts)

**Experimental**

Drive a metered, persisted AI text stream (an `ai.stream(...)` definition
from `nuxt-backend/ai`). Streams over HTTP while the text also persists
server-side — reload mid-stream (or pass `streamId`) and the persisted body
continues reactively. A failed or aborted stream releases its credits.

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        stream
      </code>
    </td>
    
    <td>
      <a href="#aistreamapi">
        <code>
          AiStreamApi
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="#useaistreamoptions">
        <code>
          UseAiStreamOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`UseAiStreamReturn`](#useaistreamreturn)

#### Example

```vue
<script setup lang="ts">
import { api } from '#backend/_generated/api'
const echo = useAiStream({ start: api.ai.startEcho, body: api.ai.echoBody })
</script>
<template>
  <button @click="echo.start({ prompt: 'hello' })">Generate</button>
  <pre>{{ echo.text.value }}</pre>
</template>
```

Paired with the `nuxt-backend/ai` entry — its return shape
may change in a minor release (see STABILITY.md).


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.