generateText, streamText, embed, generateSpeech, transcribe, and more, that work the same across every model provider, plus typed tool calling, schema-validated structured output, and UI hooks for React, Next.js, Svelte, and Vue. Providers plug in as small packages, so switching models is a one-line change. ZeroGPU ships an official community provider, @zerogpu/ai-sdk-provider, listed in the AI SDK provider docs.
ZeroGPU is a compute-efficient inference provider for apps and agents. We run purpose-built small and nano language models across an edge network for the high-volume tasks you run constantly - classification, extraction, moderation, routing, summarization - at ~10x lower latency and 50%+ lower cost than frontier-model workflows. Auto-scaling, with zero GPU infrastructure to manage. Plug in and you’re live.
Overview
This guide covers@zerogpu/ai-sdk-provider, for TypeScript developers who build with the AI SDK in Node.js, Next.js, or any other JavaScript runtime. You’ll install the provider, make your first generateText call, and then work through every surface it exposes: text generation, streaming, tool calling, structured output, image input, reasoning, ZeroGPU’s classification and extraction models, embeddings, speech generation, and transcription. By the end you’ll be able to send any AI SDK workload to ZeroGPU by changing one model line, and pick the right ZeroGPU model for each step of a pipeline.
Cookbook
For a runnable, real-world example, see Triage Voice Notes with the Vercel AI SDK and ZeroGPU. It transcribes a customer voicemail withwhisper-tiny, turns the transcript into a typed support ticket with Output.object, and speaks an acknowledgment back with chatterbox-nano, all through the AI SDK’s standard functions. Check it out to see the transcription, structured output, and speech surfaces from this guide working together.
For more worked examples, browse the cookbook index for
end-to-end walkthroughs of classification, extraction, and PII workflows on
ZeroGPU’s small models.
Video walkthrough
Video walkthrough coming soon.Quickstart
Prerequisites
- Node.js 22 or newer.
- AI SDK 7 (
ai@7). The provider implements the AI SDK’s V4 model specification, which earlier major versions ofaidon’t accept. - A ZeroGPU API key (starts with
zgpu-api-). - A model from the model catalog. This guide uses
gpt-oss-120bfor its first request.
Get your ZeroGPU API key
- Sign in to the ZeroGPU dashboard.
- Open API Keys and click Create key.
- Copy the key (starts with
zgpu-api-) and export it. The provider readsZEROGPU_API_KEYautomatically.
Install the Vercel AI SDK
Install the AI SDK, the ZeroGPU provider, andzod (used for tool and output schemas):
pnpm add and yarn add work the same way.
Your first request
zerogpu instance reads ZEROGPU_API_KEY and sends requests to https://api.zerogpu.ai/v1. Every call returns the standard AI SDK result, so text, usage, finishReason, and response look the same as they do with any other provider.
Usage
Every section below follows the same shape: what the surface does, which ZeroGPU endpoint it hits, its parameters, a runnable example, and the response you get back.Provider instance and settings
zerogpu is a ready-made provider instance. Use createZeroGPU() when you need a different key, a project scope, a proxy, or custom headers.
The provider exposes one factory per model type. Each has an alias, so you can use whichever name you prefer:
Model IDs are autocompleted in your editor and are case-sensitive:
LFM2.5-1.2B-Instruct works, lfm2.5-1.2b-instruct does not. Any other ZeroGPU model ID also works as a plain string. ZeroGPU has no image generation models, so zerogpu.imageModel() throws NoSuchModelError.
generateText
The core text entry point. Hits ZeroGPU’s POST /v1/chat/completions and returns once the full response is ready. Works with every language model in the capability table, including the classification and extraction models.
GenerateTextResult. text is the reply, finishReason is stop, length, or tool-calls, and usage carries inputTokens, outputTokens, totalTokens, and inputTokenDetails.cacheReadTokens when ZeroGPU reports cached prompt tokens. response.body holds ZeroGPU’s raw chat completion if you need a field the AI SDK doesn’t map.
streamText
Streams the reply as it is generated. Hits the same POST /v1/chat/completions endpoint with stream: true and stream_options.include_usage, so the final usage is always filled in. Supported on every model in the capability table; the classification and extraction models don’t stream. streamText takes the same parameters as generateText, plus onChunk, onFinish, and onError callbacks.
StreamTextResult. Consume textStream for text only, or fullStream for text, tool call, and finish parts. In a Next.js route handler, return result.toUIMessageStreamResponse() to feed the AI SDK’s useChat hook. LFM2.5-1.2B-Instruct, LFM2.5-1.2B-Thinking, and llama-3.2-3b-instruct-fast accept streaming but deliver the reply in a single chunk.
Tool calling
Pass AI SDKtool() definitions and the model decides when to call them. The provider converts them to OpenAI-format function tools on POST /v1/chat/completions. Supported on every model marked for tool usage in the capability table.
steps lists each round trip. The first step has finishReason: 'tool-calls' with the parsed toolCalls and toolResults; the last step holds the final text. Tool calls also stream through streamText as tool-input-start, tool-input-delta, and tool-call parts on fullStream.
Structured output
Output.object() makes the model return JSON that matches your zod schema, and the AI SDK validates and types it for you. The provider sends the schema as a json_schema response_format. Supported on every model marked for object generation in the capability table.
output is a typed object that already passed schema validation. If the model returns something that doesn’t parse, the call throws NoObjectGeneratedError. With streamText, read partialOutputStream to render the object as it fills in.
Image input
Vision models accept images asfile parts in a user message, either as bytes (Buffer, Uint8Array, base64) or as an https URL that ZeroGPU downloads. Supported on every model marked for image input in the capability table.
data: new URL('https://example.com/photo.png'). Response: a normal generateText result; image tokens are counted in usage.inputTokens.
Reasoning
Reasoning models think before they answer. Control how long with the AI SDK’sreasoning option or with providerOptions.zerogpu.reasoningEffort, both sent as reasoning_effort.
usage.outputTokenDetails.reasoningTokens when the model exposes it, but doesn’t return the reasoning text, so reasoningText is undefined. Models without adjustable reasoning, such as gpt-4.1-mini, the Llama models, and the LFM2.5 models, reject reasoning_effort; leave the option off for them.
Classification and extraction models
ZeroGPU’s task models run throughgenerateText like any other model. They return their result as a JSON string in text, so JSON.parse(text) it. They don’t stream, and they don’t take tools or Output.object. Model-specific settings go in providerOptions.zerogpu:
See the model catalog and each model’s page for the full input and output format.
IAB classification
zlm-v1-iab-classify-edge maps text to IAB content (1.0 and 2.2) and audience categories with confidence scores. zlm-v2-iab-classify-edge-enriched adds IAB IDs and tiers, topics, keywords, and user intent. zlm-v1-iab-domain-classifier takes a bare domain name.
Signal extraction
zlm-v1-signal-extract pulls keywords and user intent out of short text such as a search query or a chat message.
GLiNER entity, JSON, and label extraction
gliner2.5-base-v1 (English) and gliner2.5-multi-v1 (multilingual) take the task in metadata. Use usecase: 'ner' with labels for entities, usecase: 'json' with a schema of field::type::description entries for structured records, and usecase: 'classification' with a schema that maps each axis to its labels.
gliner2.5-multi-v1 takes the same metadata on non-English text: Marie Dupont travaille chez Airbus à Toulouse. with labels person, company, and city returns {"entities":{"person":["Marie Dupont"],"company":["Airbus"],"city":["Toulouse"]}}.
GLiNER decisions
gliner2.5-decide-v1 makes routing and handoff decisions over several heads in one call. Pass usecase: 'decide' and a labels object that maps each decision to its options.
DeBERTa zero-shot classification
deberta-v3-small scores text against labels you choose. Pass the labels in instructions as a bracketed, comma-separated list.
Embeddings with embed and embedMany
zerogpu.embeddingModel() creates an embedding model for the AI SDK’s embed (one value) and embedMany (a batch). Hits POST /v1/embeddings.
Response:
embedding (or embeddings) is an array of numbers per input, in input order, and usage.tokens is the token count.
Speech with generateSpeech
zerogpu.speech('chatterbox-nano') turns English text into audio. Hits POST /v1/audio/speech.
instructions, speed, and language aren’t supported; the provider ignores them and adds a warning.
audio is a generated file with uint8Array, base64, and mediaType, plus any warnings. Voice cloning from a reference clip isn’t available through the provider; call /v1/audio/speech directly with a voice_sample for that.
Transcription with transcribe
zerogpu.transcription('whisper-tiny') turns speech into text. Hits POST /v1/audio/transcriptions and asks for the verbose result, so you get segments, language, and duration too.
text is the transcript, segments is a list of { text, startSecond, endSecond }, language is the detected or supplied language, and durationInSeconds is the audio length.
Model capabilities
Text generation models, all with streaming:
Classification and extraction models, called with
generateText only:
The moderation models (
zlm-v1-moderation-edge, llama-guard-4-12b) only run on /v1/moderations, which the AI SDK has no function for; call them with the JavaScript SDK instead.
Patterns and recipes
A cheap classifier in front of a chat model. Rungliner2.5-decide-v1 first to label the request, then send only the requests that need a written answer to a chat model. The decision call costs a fraction of a chat call, so spam and other dead ends never reach the expensive step:
gliner2.5-decide-v1 labeled “CLICK HERE to win a free iPhone!!!” as spam, while deberta-v3-small with [question,complaint,spam] scored the same text as a question. DeBERTa is better at topical labels such as [Sports,Technology,Finance].
Tool routing on the 0.6B decision model. zlm-v1-tool-decisions picks a tool and fills its arguments in one fast step. Define tools without execute, read toolCalls, and run the chosen tool yourself. Asked “Where is my order 7731?” with searchOrders and createTicket tools, it returns [{ toolName: 'searchOrders', input: { orderId: '7731' } }] with finishReason: 'tool-calls'.
Typed extraction instead of parsing prose. For “pull these fields out of this text” jobs, use Output.object with a zod schema on gpt-6-luna or gpt-5.4-nano, or GLiNER’s usecase: 'json' when the fields are short spans. Both give you data you can store directly, with no regex over free text.
Swap providers per step. Because every AI SDK provider shares the same functions, you can mix ZeroGPU with another provider in one pipeline: transcribe, classify, and extract on ZeroGPU, and pass only the hard cases to a frontier model by changing the model line. The voice-note cookbook chains transcribe, Output.object, and generateSpeech this way.
At a glance
Troubleshooting
LoadAPIKeyError: ZeroGPU API key is missing. ZEROGPU_API_KEY isn’t set in the process making the call. Export it in that shell, add it to .env.local in Next.js, or pass createZeroGPU({ apiKey }). In serverless deployments, add it to the project’s environment variables and redeploy.
AI_UnsupportedModelVersionError: Unsupported model version v4, or a type error on model. Your ai package is older than version 7. The provider implements the V4 model specification, which only AI SDK 7 accepts. Run npm i ai@7.
Install fails or the provider won’t load on an older Node.js. The provider requires Node.js 22 or newer. Check with node -v and upgrade.
AI_APICallError with status 403 Forbidden. The API key is wrong or revoked. ZeroGPU returns 403, not 401, for an invalid key. Copy a fresh key from the dashboard.
404 Model not found. The model ID has a typo or the wrong case. IDs are case-sensitive, so check them against the model catalog.
stream is not supported for this model. Classification and extraction models don’t stream. streamText doesn’t throw: it reports the error through onError (logged to the console by default) and textStream ends empty. Use generateText for these models.
400 Tool calling is not supported for model, or NoObjectGeneratedError. llama-3.2-3b-instruct-fast and the LFM2.5 models don’t support tools or structured output. Switch to a model with those marks in the capability table, such as gpt-6-luna.
JSON.parse fails, or you get [object Object], on a task model. Task models return their result as a JSON string in text, not in output. Call JSON.parse(text) and don’t combine them with Output.object.
reasoning_effort rejected with a 400. The model doesn’t support adjustable reasoning. Drop reasoning and reasoningEffort for gpt-4.1-mini, the Llama models, and the LFM2.5 models.
Error while downloading file on an image URL. ZeroGPU fetches https image URLs itself, and some hosts block that download. Read the image yourself and pass the bytes as data instead.
400 on generateSpeech mentioning the 2,000 character limit. chatterbox-nano accepts up to 2,000 characters per call. Split long text into sentences or paragraphs and concatenate the audio. If you see unsupported warnings for instructions or speed, remove those options; use inline tags like [laugh] to shape delivery.
429 responses under load. You’re being rate limited. The AI SDK retries 429s with backoff (maxRetries, default 2); raise it for bursty workloads, cap maxParallelCalls on embedMany, and move offline work to the Batch API.
Conclusion
The AI SDK gives your TypeScript app one set of functions for every model, and@zerogpu/ai-sdk-provider puts ZeroGPU’s whole lineup behind them: text models for chat and agents, task models for classification and extraction, plus embeddings, speech, and transcription. Point each step of your pipeline at the smallest ZeroGPU model that does the job, keep the same code, and pay a fraction of what a frontier model would cost for the high-volume work.
Model Catalog
Browse every model available on ZeroGPU and pick the best fit.
API Reference
Explore the OpenAI-compatible endpoints the provider calls.
Cookbook
Worked examples for classification, extraction, and batch jobs.
Join Discord
Ask questions and share what you’re building.

