# Introduction (/) # Celeste AI

The primitive layer for multi-modal AI All modalities. All providers. One interface.

Celeste is a unified interface for multi-modal AI. It provides a consistent, type-safe API across text, image, video, and audio generation from all major providers. > Beta: The v1 public beta is available as `0.9`. The docs below reflect the namespace-first API and the domain → modality mental model. > > LLM-friendly export: [llms-full.txt](/llms-full.txt) for one-page ingestion. ## Why Celeste? * **Primitives, not frameworks**: Celeste gives you raw building blocks, not opinionated chains or agents. * **Unified Interface**: Switch between OpenAI, Anthropic, Google, and others with a single line of code. * **Type-Safe**: Full IDE support with Pydantic models for inputs and outputs. * **Multi-Modal**: First-class support for text, image, video, and audio. ## Supported Providers {/* AUTO-GENERATED:SUPPORTED_PROVIDERS:START */}

Anthropic Black Forest Labs BytePlus Cohere DeepSeek ElevenLabs Google Gradium Groq Mistral Moonshot OpenAI xAI

{/* AUTO-GENERATED:SUPPORTED_PROVIDERS:END */} # Installation (/getting-started/installation) import { InstallSelector } from '@/components/InstallSelector'; # Installation Celeste is available on PyPI. Use the interactive selector below to generate the installation command for your project. # Quick Start (/getting-started/quickstart) import { Step, Steps } from 'fumadocs-ui/components/steps'; # Quick Start This guide will help you make your first generation request with Celeste. ## Install Install Celeste: ```bash uv add celeste-ai ``` ## Configure Credentials Set your API keys as environment variables. Celeste will automatically look for them. ```bash export ANTHROPIC_API_KEY="sk-..." export OPENAI_API_KEY="sk-..." ``` Or create a `.env` file: ```bash title=".env" ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... ``` ## Use a domain namespace (recommended) Import `celeste` and call the domain you work with. Domain is what you work with, not input or output. ```python import celeste # Domain: text response = await celeste.text.generate( model="claude-sonnet-4-5", prompt="Explain quantum computing in one sentence.", ) print(response.content) ``` ## Generate Content import { MethodSelector } from '@/components/MethodSelector';

Non-blocking I/O. Recommended for production apps and notebooks. ```python response = await celeste.text.generate( model="claude-sonnet-4-5", prompt="Explain quantum computing in one sentence.", temperature=0.7, ) print(response.content) ```

Blocking I/O. Suitable for scripts and simple tools. ```python response = celeste.text.sync.generate( model="claude-sonnet-4-5", prompt="Explain quantum computing in one sentence.", temperature=0.7, ) print(response.content) ```

## Multi-Modal Example Celeste uses the same interface for every domain and operation. ```python import celeste # Text domain → text output text = await celeste.text.generate( model="claude-sonnet-4-5", prompt="Write a haiku about AI", ) # Images domain → image output image = await celeste.images.generate( model="gpt-image-1", prompt="A futuristic city at sunset", ) # Videos domain → video output video = await celeste.videos.generate( model="veo-3", prompt="Waves crashing on a beach", ) ``` # Modality & operations (/core-concepts/modality-and-operation) # Architecture & Concepts Celeste v1 is built around a simple mental model: **Domain (what you work with) + Operation → Modality (output)**.

Domain

What you work with

Images, Audio, Video, Text

Namespace API

Modality

What comes out

Output type and client

create\_client(modality=...)

Operation

How input becomes output

Generate Prompt → domain output output = modality

Edit Domain → same domain images client

Analyze Media → text text client

Embed Any domain → vector embeddings client

Namespaces use domains celeste.images.analyze(...)

Clients use modalities create_client(modality="text")

Image generation → domain: images, output modality: images

Image analysis → domain: images, output modality: text

## The Core Trinity ### 1. Modality (The output) **What comes out.** Modality defines the output type you receive: text, images, audio, video, or embeddings. ### 2. Domain (What you work with) **The resource you operate on.** Domain is not input vs output; it is the thing you are working with. That resource can be input or output depending on the operation. * Image generation: domain = images, output modality = images. * Image analysis: domain = images, output modality = text. ### 3. Operation (The transformation) **The method you call.** Operations describe how the domain is transformed into the output modality. ## Operation Matrix (Namespace-first) This matrix explains where to find every operation in Celeste. | What you work with (Domain) | Operation | Output (Modality) | Namespace call | | :-------------------------- | :--------- | :---------------- | :----------------------------------- | | Text | `generate` | Text | `await celeste.text.generate(...)` | | Text | `embed` | Embeddings | `await celeste.text.embed(...)` | | Images | `generate` | Images | `await celeste.images.generate(...)` | | Images | `edit` | Images | `await celeste.images.edit(...)` | | Images | `analyze` | Text | `await celeste.images.analyze(...)` | | Audio | `speak` | Audio | `await celeste.audio.speak(...)` | | Audio | `analyze` | Text | `await celeste.audio.analyze(...)` | | Videos | `generate` | Videos | `await celeste.videos.generate(...)` | | Videos | `analyze` | Text | `await celeste.videos.analyze(...)` | ### Operations by Domain | Action | text | images | videos | audio | | ------------ | ---- | ------ | ------ | ----- | | `generate` | ✓ | ✓ | ✓ | ○ | | `edit` | · | ✓ | · | · | | `analyze` | · | ✓ | ✓ | ✓ | | `upscale` | · | ○ | ○ | · | | `speak` | · | · | · | ✓ | | `transcribe` | · | · | · | ○ | | `embed` | ✓ | ○ | ○ | · | **Legend:** ✓ = Available · ○ = Planned · · = Not applicable **Note:** This table is by **domain (what you work with)**. **Embeddings** is a **modality** (vector output) produced by the `embed` operation, so it is not listed as a domain. ## Examples ### Image Generation (Image domain → Image output) ```python import celeste response = await celeste.images.generate( model="gpt-image-1", prompt="A red apple", ) image = response.content ``` ### Image Analysis (Image domain → Text output) ```python import celeste from celeste.artifacts import ImageArtifact image = ImageArtifact(path="apple.png") response = await celeste.images.analyze( model="gpt-4o", prompt="Describe this image", image=image, ) text = response.content ``` ## Why this design? Celeste keeps outputs predictable: a text response always returns `TextOutput`, an image response always returns `ImageOutput`, and so on. The namespace-first API mirrors how people think (“I have an image; I want to analyze it”) while the modality system keeps output types consistent and type-safe. # The client (/core-concepts/client) # The client Celeste v1 is **namespace-first**, but this page focuses on the **client** pattern. The client API is **modality-first**, meaning you choose the output type you want. ## Create a client (advanced) Use `create_client` when you want explicit control or reuse a configured client. This is **modality-first**, so you specify the output type and (optionally) the operation. ```python import celeste client = celeste.create_client( modality="text", provider="openai", model="gpt-4o", ) ``` ### Arguments * **`modality`** (`str | Modality`): The modality to use (e.g., `"text"`, `"images"`). * **`operation`** (`str | Operation`, optional): Optional operation filter. * **`provider`** (`str | Provider`, optional): The provider to use (e.g., `"openai"`, `"anthropic"`). * **`model`** (`str | Model`, optional): Specific model to use. * **`api_key`** (`str`, optional): API key override. * **`auth`** (`Authentication`, optional): Custom authentication override (advanced). ## Execution modes Celeste supports three execution modes to handle different use cases: | Mode | Pattern | Return Type | Use Case | | ------------- | -------------------------- | ---------------------- | ---------------------------- | | **Async** | `await client.generate()` | `Output` | Production, async apps | | **Streaming** | `client.stream.generate()` | `AsyncIterator[Chunk]` | Chat UIs, real-time feedback | | **Sync** | `client.sync.generate()` | `Output` | Scripts, notebooks, testing | ### Async (default) Async operation methods return a complete typed output object. Best for production applications. ```python response = await client.generate(prompt="Hello world", temperature=0.7) print(response.content) ``` ### Streaming (`client.stream.()`) Streaming returns chunks as they are generated. Best for UIs requiring real-time feedback. ```python stream = client.stream.generate(prompt="Count from 1 to 5") async for chunk in stream: print(chunk.content, end="") final_response = stream.output print(final_response.content) ``` ### Sync (`client.sync.()`) Sync methods are blocking calls. Best for scripts, notebooks, and testing. ```python response = client.sync.generate(prompt="Hello world") print(response.content) ``` Sync streaming is also supported: ```python stream = client.sync.stream.generate(prompt="Hello world") for chunk in stream: print(chunk.content, end="") print(stream.output.content) ``` ## Type Safety Clients are generic over their Input, Output, and Parameters. This means your IDE can provide autocomplete and type checking for: * **Parameters**: `temperature`, `max_tokens`, etc. * **Response**: `response.content`, `response.usage`, etc. ```python # IDE knows this is a TextOutput (for text modality) response = await client.generate(prompt="...") # IDE knows this is int tokens = response.usage.total_tokens ``` # Providers (/core-concepts/providers) # Providers Celeste supports multiple AI providers through a unified interface. ## Available Providers Import `Provider` from `celeste`. ```python from celeste import Provider ``` * **`Provider.OPENAI`**: GPT-4o, GPT-Image, DALL·E. * **`Provider.ANTHROPIC`**: Claude. * **`Provider.GOOGLE`**: Gemini, Imagen. * **`Provider.MISTRAL`**: Mistral. * **`Provider.COHERE`**: Command. * **`Provider.DEEPSEEK`**: DeepSeek. * **`Provider.GROQ`**: Groq. * **`Provider.MOONSHOT`**: Moonshot. * **`Provider.XAI`**: Grok. * **`Provider.BYTEPLUS`**: BytePlus. * **`Provider.BFL`**: BFL. * **`Provider.ELEVENLABS`**: ElevenLabs. * **`Provider.GRADIUM`**: Gradium. ## Credentials Celeste automatically loads API keys from environment variables. | Provider | Environment Variable | | :--------- | :------------------- | | OpenAI | `OPENAI_API_KEY` | | Anthropic | `ANTHROPIC_API_KEY` | | Google | `GOOGLE_API_KEY` | | Mistral | `MISTRAL_API_KEY` | | Cohere | `COHERE_API_KEY` | | DeepSeek | `DEEPSEEK_API_KEY` | | Groq | `GROQ_API_KEY` | | Moonshot | `MOONSHOT_API_KEY` | | xAI | `XAI_API_KEY` | | BytePlus | `BYTEPLUS_API_KEY` | | BFL | `BFL_API_KEY` | | ElevenLabs | `ELEVENLABS_API_KEY` | | Gradium | `GRADIUM_API_KEY` | You can also pass keys explicitly when creating a client: ```python from celeste import Provider import celeste response = await celeste.text.generate( model="gpt-4o", provider=Provider.OPENAI, api_key="sk-...", prompt="Hello from OpenAI", ) ``` # Domains (/domains) # Domains Domains are **what you work with**. The namespace API is domain-first, so you start from the resource and pick an operation. **Rule of thumb** * **Namespaces use domains**: `celeste.images.analyze(...)` * **Clients use modalities**: `create_client(modality="text")` ## Available Domains * **Text**: prompts, documents, structured outputs. * **Images**: image generation, editing, and image analysis. * **Audio**: text-to-speech and audio analysis. * **Video**: video generation and video analysis. ## Domain vs Modality Modality is the **output type** (and the client you create). Domain is the **resource you work with**. The same domain can map to different output modalities depending on the operation. Example: * `celeste.images.generate(...)` → **images** output * `celeste.images.analyze(...)` → **text** output ## Quick Example ```python import celeste # Domain: images → output: text response = await celeste.images.analyze( model="gpt-4o", prompt="Describe this image", image=img, ) print(response.content) ``` # Text (/domains/text) # Text Domain The **text domain** is for prompts, documents, and structured outputs. It supports **text generation** and **embeddings**. ## Operations | Operation | Output Modality | Namespace call | | :--------- | :-------------- | :--------------------------------- | | `generate` | Text | `await celeste.text.generate(...)` | | `embed` | Embeddings | `await celeste.text.embed(...)` | ## Examples ```python import celeste # Text generation → text output story = await celeste.text.generate( model="gpt-4o", prompt="Write a short story about a lighthouse.", ) print(story.content) # Embeddings → embeddings output embeddings = await celeste.text.embed( model="text-embedding-3-large", text="The quick brown fox jumps over the lazy dog", ) print(len(embeddings.content)) ``` # Images (/domains/images) # Images Domain The **images domain** covers image generation, editing, and analysis. Analysis returns **text output** because the modality is text. ## Operations | Operation | Output Modality | Namespace call | | :--------- | :-------------- | :----------------------------------- | | `generate` | Images | `await celeste.images.generate(...)` | | `edit` | Images | `await celeste.images.edit(...)` | | `analyze` | Text | `await celeste.images.analyze(...)` | ## Examples ```python import celeste from celeste.artifacts import ImageArtifact # Generate → images output image = await celeste.images.generate( model="gpt-image-1", prompt="A futuristic city at sunset", ) # Analyze → text output photo = ImageArtifact(path="photo.png") description = await celeste.images.analyze( model="gpt-4o", prompt="Describe the scene", image=photo, ) print(description.content) ``` # Audio (/domains/audio) # Audio Domain The **audio domain** covers text-to-speech and audio analysis. Analysis returns **text output** because the modality is text. ## Operations | Operation | Output Modality | Namespace call | | :-------- | :-------------- | :--------------------------------- | | `speak` | Audio | `await celeste.audio.speak(...)` | | `analyze` | Text | `await celeste.audio.analyze(...)` | ## Examples ```python import celeste from celeste.artifacts import AudioArtifact # Speak → audio output audio = await celeste.audio.speak( model="eleven_multilingual_v2", text="Hello from Celeste", voice="Rachel", ) # Analyze → text output recording = AudioArtifact(path="recording.mp3") summary = await celeste.audio.analyze( model="gpt-4o", prompt="Summarize this audio", audio=recording, ) print(summary.content) ``` # Video (/domains/video) # Video Domain The **video domain** covers video generation and analysis. Analysis returns **text output** because the modality is text. ## Operations | Operation | Output Modality | Namespace call | | :--------- | :-------------- | :----------------------------------- | | `generate` | Videos | `await celeste.videos.generate(...)` | | `analyze` | Text | `await celeste.videos.analyze(...)` | ## Examples ```python import celeste from celeste.artifacts import VideoArtifact # Generate → video output video = await celeste.videos.generate( model="veo-3.0-generate-001", prompt="Waves crashing on a rocky shore", ) # Analyze → text output clip = VideoArtifact(path="clip.mp4") description = await celeste.videos.analyze( model="gpt-4o", prompt="Describe what happens in this video", video=clip, ) print(description.content) ``` # Modalities (/modalities) # Modalities Modalities are **output types** (text, images, audio, video, embeddings). The public API is **namespace-first**, so you usually start from the domain you work with and let Celeste route to the correct modality. For day-to-day usage, see the [Domains](/docs/domains) section. ```python import celeste # Domain: images → output: text result = await celeste.images.analyze( model="gpt-4o", prompt="Describe this image", image=img, ) ``` Next: * Text (output): `celeste.text.generate(...)`, `celeste.text.embed(...)` * Images (output): `celeste.images.generate(...)`, `celeste.images.edit(...)` # Text (/modalities/text) # Text Modality The **Text** modality is the **output type** for text. Use `celeste.text.generate(...)` when you work with text, and use domain namespaces like `celeste.images.analyze(...)` or `celeste.audio.analyze(...)` when you work with media but want text output. ## Operations | Operation | Description | | :------------- | :-------------------------------------------------------------- | | **`generate`** | Generate text from a text prompt. | | **`analyze`** | Analyze images, video, or audio to generate a text description. | ## Quick Start ```python import celeste # Generate (domain: text) response = await celeste.text.generate( model="claude-sonnet-4-5", prompt="Write a haiku about rust.", ) print(response.content) # Streaming async for chunk in celeste.text.stream.generate( model="claude-sonnet-4-5", prompt="Explain quantum mechanics", ): print(chunk.content, end="") ``` ## Analyze (Multi-Modal) The `analyze` operation on a **Text** client can process images, videos, or audio to generate text descriptions. ### Image Analysis ```python from celeste.artifacts import ImageArtifact image = ImageArtifact(path="screenshot.png") response = await celeste.images.analyze( model="gpt-4o", prompt="What is in this image?", image=image ) print(response.content) ``` ### Video Analysis ```python from celeste.artifacts import VideoArtifact video = VideoArtifact(path="clip.mp4") response = await celeste.videos.analyze( model="gpt-4o", prompt="Describe what happens in this video", video=video ) print(response.content) ``` ### Audio Analysis ```python from celeste.artifacts import AudioArtifact audio = AudioArtifact(path="recording.mp3") response = await celeste.audio.analyze( model="gpt-4o", prompt="What is being said in this audio?", audio=audio ) print(response.content) ``` ## Providers Supported providers for Text: * OpenAI (GPT-4o, etc.) * Anthropic (Claude) * Google (Gemini) * Mistral * Cohere * Meta (Llama via providers) # Images (/modalities/images) # Images Modality The **Images** modality is the **output type** for image generation and editing. When you work with images and want **text output** (analysis), you still use the **images domain** via `celeste.images.analyze(...)`, but the output modality is text. ## Operations | Operation | Description | | :------------- | :------------------------------------------------ | | **`generate`** | Create an image from a text prompt. | | **`edit`** | Modify an existing image using a prompt and mask. | | **`upscale`** | Increase the resolution of an image. (Planned) | ## Quick Start ```python import celeste # Generate (domain: images) response = await celeste.images.generate( model="gpt-image-1", prompt="A cyberpunk city at night", aspect_ratio="1:1" ) with open("cyberpunk.png", "wb") as f: f.write(response.content.get_bytes()) ``` ## Editing ```python from celeste.artifacts import ImageArtifact base_image = ImageArtifact(path="photo.png") response = await celeste.images.edit( model="gpt-image-1", image=base_image, prompt="Add a red hat", mask=... # optional mask ) ``` ## Image Analysis (Text Output) ```python from celeste.artifacts import ImageArtifact image = ImageArtifact(path="photo.png") response = await celeste.images.analyze( model="gpt-4o", image=image, prompt="Describe the scene", ) print(response.content) ``` ## Providers Supported providers for Images: * OpenAI (DALL·E 3) * Google (Imagen 3) * BFL (Flux) * BytePlus # Audio (/modalities/audio) # Audio Modality The **Audio** modality is the **output type** for speech synthesis and audio generation. When you work with audio and want **text output** (analysis), use `celeste.audio.analyze(...)` and the response will be text. ## Operations | Operation | Description | | :--------------- | :------------------------------------------------- | | **`speak`** | Convert text to speech (TTS). | | **`transcribe`** | Convert audio to text (STT). (Planned) | | **`generate`** | Generate audio/music from a text prompt. (Planned) | ## Quick Start ```python import celeste # Speak (TTS) audio = await celeste.audio.speak( model="eleven_v3", text="Hello, this is a generated voice.", voice="rachel", ) # Save to file with open("output.mp3", "wb") as f: f.write(audio.content.get_bytes()) ``` ## Streaming Audio ```python stream = celeste.audio.stream.speak( model="eleven_v3", text="Reading a long book...", ) async for chunk in stream: # chunk.content is bytes player.write(chunk.content) ``` ## Audio Analysis (Text Output) ```python from celeste.artifacts import AudioArtifact audio = AudioArtifact(path="recording.mp3") response = await celeste.audio.analyze( model="gpt-4o", audio=audio, prompt="Summarize what is being said", ) print(response.content) ``` ## Providers Supported providers for Audio: * ElevenLabs * OpenAI (TTS) * Google (Cloud TTS) # Video (/modalities/video) # Video Modality The **Video** modality is the **output type** for video generation. For video **analysis**, use the **video domain** (`celeste.videos.analyze(...)`) and you will receive **text output**. ## Operations | Operation | Description | | :------------- | :------------------------------------------ | | **`generate`** | Create a video from a text or image prompt. | ## Quick Start ```python import celeste # Generate video = await celeste.videos.generate( model="ray-2", prompt="A drone shot of a beautiful coastline at sunset", duration=8, ) with open("coast.mp4", "wb") as f: f.write(video.content.get_bytes()) ``` ## Video Analysis (Text Output) ```python from celeste.artifacts import VideoArtifact video = VideoArtifact(path="clip.mp4") response = await celeste.videos.analyze( model="gpt-4o", video=video, prompt="Describe what happens in this video", ) print(response.content) ``` ## Providers Supported providers for Video: * Luma (Ray) * BytePlus (PixelDance) * Google (Veo) # Embeddings (/modalities/embeddings) # Embeddings Modality The **Embeddings** modality is the **output type** for vector representations. You typically work with the **text domain** and call `celeste.text.embed(...)` to get embeddings. ## Operations | Operation | Description | | :---------- | :------------------------------------ | | **`embed`** | Convert text into a vector embedding. | ## Quick Start ```python import celeste # Generate embedding (domain: text → modality: embeddings) response = await celeste.text.embed( model="text-embedding-3-large", text="The quick brown fox jumps over the lazy dog", ) # Access the vector vector = response.content print(f"Vector length: {len(vector)}") ``` ## Batch Processing You can embed multiple texts in a single request for efficiency. ```python response = await celeste.text.embed( model="text-embedding-3-large", text=[ "First document", "Second document", "Third document" ] ) for vector in response.content: print(vector[:5]) # Print first 5 dimensions ``` ## Sync Usage For scripts or notebooks where async is not needed: ```python response = celeste.text.sync.embed( model="text-embedding-3-large", text="Hello world", ) print(response.content) ``` ## Providers Supported providers for Embeddings: * OpenAI (`text-embedding-3-small`, `text-embedding-3-large`, etc.) * Google (Gecko) * Cohere (`embed-english-v3.0`, etc.) # Anthropic (/providers/anthropic)

Celeste supports Anthropic's Claude models for text generation. ## Credentials Set the `ANTHROPIC_API_KEY` environment variable. ```bash export ANTHROPIC_API_KEY="sk-ant-..." ``` ## Text Generation ### Models * `claude-3-5-sonnet-20240620` (Default) * `claude-3-opus-20240229` * `claude-3-sonnet-20240229` * `claude-3-haiku-20240307` ### Usage ```python import celeste response = await celeste.text.generate( model="claude-3-5-sonnet-20240620", prompt="Hello Claude", ) ``` ### Thinking Anthropic models support extended thinking parameters. ```python response = await celeste.text.generate( model="claude-3-5-sonnet-20240620", prompt="Solve this complex logic puzzle...", thinking_budget=4096 ) ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `analyze`, `generate` ### Text | Model ID | Display name | Operations | Streaming | | :------------------------- | :---------------- | :-------------------- | :-------- | | `claude-haiku-4-5` | Claude Haiku 4.5 | `analyze`, `generate` | Yes | | `claude-opus-4-20250514` | Claude Opus 4 | `analyze`, `generate` | Yes | | `claude-opus-4-1` | Claude Opus 4.1 | `analyze`, `generate` | Yes | | `claude-opus-4-5` | Claude Opus 4.5 | `analyze`, `generate` | Yes | | `claude-sonnet-4-20250514` | Claude Sonnet 4 | `analyze`, `generate` | Yes | | `claude-sonnet-4-5` | Claude Sonnet 4.5 | `analyze`, `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} # Black Forest Labs (/providers/bfl)

Celeste supports the **Black Forest Labs** provider. ## Credentials Set the `BFL_API_KEY` environment variable. ```bash export BFL_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `images`: `edit`, `generate` ### Images | Model ID | Display name | Operations | Streaming | | :------------ | :------------- | :----------------- | :-------- | | `flux-2-flex` | FLUX.2 \[flex] | `edit`, `generate` | No | | `flux-2-max` | FLUX.2 \[max] | `edit`, `generate` | No | | `flux-2-pro` | FLUX.2 \[pro] | `edit`, `generate` | No | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # BytePlus (/providers/byteplus)

Celeste supports the **BytePlus** provider. ## Credentials Set the `BYTEPLUS_API_KEY` environment variable. ```bash export BYTEPLUS_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `images`: `generate` * `videos`: `generate` ### Images | Model ID | Display name | Operations | Streaming | | :-------------------- | :----------- | :--------- | :-------- | | `seedream-4-0-250828` | Seedream 4.0 | `generate` | Yes | | `seedream-4-5-251128` | Seedream 4.5 | `generate` | Yes | ### Videos | Model ID | Display name | Operations | Streaming | | :----------------------------- | :--------------------------------- | :--------- | :-------- | | `seedance-1-0-lite-i2v-250428` | Seedance 1.0 Lite (Image-to-Video) | `generate` | No | | `seedance-1-0-lite-t2v-250428` | Seedance 1.0 Lite (Text-to-Video) | `generate` | No | | `seedance-1-0-pro-250528` | Seedance 1.0 Pro | `generate` | No | | `seedance-1-0-pro-fast-251015` | Seedance 1.0 Pro Fast | `generate` | No | | `seedance-1-5-pro-251215` | Seedance 1.5 Pro | `generate` | No | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # Cohere (/providers/cohere) Cohere

Celeste supports Cohere's Command R series models. ## Credentials Set the `COHERE_API_KEY` environment variable. ```bash export COHERE_API_KEY="..." ``` ## Text Generation ### Models * `command-a-03-2025` (Default) * `command-r7b-12-2024` ### Usage ```python import celeste response = await celeste.text.generate( model="command-a-03-2025", prompt="Hello Command R", ) ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `analyze`, `generate` ### Text | Model ID | Display name | Operations | Streaming | | :------------------------- | :----------------------- | :-------------------- | :-------- | | `command-a-03-2025` | Command A 03-2025 | `generate` | Yes | | `command-a-vision-07-2025` | Command A Vision 07-2025 | `analyze`, `generate` | Yes | | `command-r7b-12-2024` | Command R7B | `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} # DeepSeek (/providers/deepseek)

Celeste supports the **DeepSeek** provider. ## Credentials Set the `DEEPSEEK_API_KEY` environment variable. ```bash export DEEPSEEK_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `generate` ### Text | Model ID | Display name | Operations | Streaming | | :------------------ | :---------------- | :--------- | :-------- | | `deepseek-chat` | DeepSeek Chat | `generate` | Yes | | `deepseek-reasoner` | DeepSeek Reasoner | `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # ElevenLabs (/providers/elevenlabs)

Celeste supports ElevenLabs for high-quality speech generation. ## Credentials Set the `ELEVENLABS_API_KEY` environment variable. ```bash export ELEVENLABS_API_KEY="..." ``` ## Speech Generation ### Models * `eleven_multilingual_v2` (Default) * `eleven_turbo_v2` ### Usage ```python import celeste response = await celeste.audio.speak( model="eleven_multilingual_v2", provider="elevenlabs", text="This voice is AI generated.", voice="Rachel" # Use voice ID or name ) ``` ## Models{/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `audio`: `speak` ### Audio | Model ID | Display name | Operations | Streaming | | :----------------------- | :--------------------- | :--------- | :-------- | | `eleven_monolingual_v1` | Eleven English v1 | `speak` | Yes | | `eleven_flash_v2` | Eleven Flash v2 | `speak` | Yes | | `eleven_flash_v2_5` | Eleven Flash v2.5 | `speak` | Yes | | `eleven_multilingual_v1` | Eleven Multilingual v1 | `speak` | Yes | | `eleven_multilingual_v2` | Eleven Multilingual v2 | `speak` | No | | `eleven_turbo_v2` | Eleven Turbo v2 | `speak` | Yes | | `eleven_turbo_v2_5` | Eleven Turbo v2.5 | `speak` | Yes | | `eleven_v3` | Eleven v3 (Alpha) | `speak` | No | {/* AUTO-GENERATED:MODELS:END */} # Google (/providers/google) Google

Celeste supports Google's Gemini models for text and multimodal tasks, and Imagen for image generation. ## Credentials Set the `GOOGLE_API_KEY` environment variable. ```bash export GOOGLE_API_KEY="AIza..." ``` ## Text Generation ### Models * `gemini-1.5-pro` (Default) * `gemini-1.5-flash` ### Usage ```python import celeste response = await celeste.text.generate( model="gemini-1.5-pro", provider="google", prompt="Hello Gemini", ) ``` ## Image Generation ### Models * `imagen-3.0-generate-001` (Default) ### Usage ```python import celeste response = await celeste.images.generate( model="imagen-3.0-generate-001", provider="google", prompt="A futuristic landscape", ) ``` ## Video Generation Google also supports video generation via specific models. ```python import celeste video = await celeste.videos.generate( model="veo-3.0-generate-001", provider="google", prompt="A sunrise over the mountains", ) ``` ## Models{/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `audio`: `speak` * `embeddings`: `embed` * `images`: `edit`, `generate` * `text`: `analyze`, `generate` * `videos`: `generate` ### Text | Model ID | Display name | Operations | Streaming | | :----------------------- | :-------------------- | :-------------------- | :-------- | | `gemini-2.5-flash` | Gemini 2.5 Flash | `analyze`, `generate` | Yes | | `gemini-2.5-flash-lite` | Gemini 2.5 Flash Lite | `analyze`, `generate` | Yes | | `gemini-2.5-pro` | Gemini 2.5 Pro | `analyze`, `generate` | Yes | | `gemini-3-flash-preview` | Gemini 3 Flash | `analyze`, `generate` | Yes | | `gemini-3-pro-preview` | Gemini 3 Pro | `analyze`, `generate` | Yes | ### Images | Model ID | Display name | Operations | Streaming | | :------------------------------ | :--------------------------- | :----------------- | :-------- | | `gemini-2.5-flash-image` | Gemini 2.5 Flash Image | `edit`, `generate` | No | | `gemini-3-pro-image-preview` | Gemini 3 Pro Image (Preview) | `edit`, `generate` | No | | `imagen-4.0-generate-001` | Imagen 4 | `generate` | No | | `imagen-4.0-fast-generate-001` | Imagen 4 Fast | `generate` | No | | `imagen-4.0-ultra-generate-001` | Imagen 4 Ultra | `generate` | No | ### Audio | Model ID | Display name | Operations | Streaming | | :--------------------- | :-------------------------- | :--------- | :-------- | | `gemini-2.5-flash-tts` | Google TTS Gemini 2.5 Flash | `speak` | No | | `gemini-2.5-pro-tts` | Google TTS Gemini 2.5 Pro | `speak` | No | ### Videos | Model ID | Display name | Operations | Streaming | | :------------------------------ | :--------------------- | :--------- | :-------- | | `veo-3.0-generate-001` | Veo 3 | `generate` | No | | `veo-3.0-fast-generate-001` | Veo 3 Fast | `generate` | No | | `veo-3.1-generate-preview` | Veo 3.1 (Preview) | `generate` | No | | `veo-3.1-fast-generate-preview` | Veo 3.1 Fast (Preview) | `generate` | No | ### Embeddings | Model ID | Display name | Operations | Streaming | | :--------------------- | :------------------- | :--------- | :-------- | | `gemini-embedding-001` | Gemini Embedding 001 | `embed` | No | {/* AUTO-GENERATED:MODELS:END */} # Gradium (/providers/gradium) Gradium

Celeste supports the **Gradium** provider. ## Credentials Set the `GRADIUM_API_KEY` environment variable. ```bash export GRADIUM_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `audio`: `speak` ### Audio | Model ID | Display name | Operations | Streaming | | :-------- | :------------------ | :--------- | :-------- | | `default` | Gradium Default TTS | `speak` | Yes | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # Groq (/providers/groq) Groq

Celeste supports the **Groq** provider. ## Credentials Set the `GROQ_API_KEY` environment variable. ```bash export GROQ_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `analyze`, `generate` ### Text | Model ID | Display name | Operations | Streaming | | :---------------------------------------------- | :---------------------- | :-------------------- | :-------- | | `allam-2-7b` | Allam 2 7B | `generate` | Yes | | `openai/gpt-oss-120b` | GPT OSS 120B | `generate` | Yes | | `openai/gpt-oss-20b` | GPT OSS 20B | `generate` | Yes | | `openai/gpt-oss-safeguard-20b` | GPT OSS Safeguard 20B | `generate` | Yes | | `groq/compound` | Groq Compound | `generate` | Yes | | `groq/compound-mini` | Groq Compound Mini | `generate` | Yes | | `moonshotai/kimi-k2-instruct` | Kimi K2 Instruct | `generate` | Yes | | `moonshotai/kimi-k2-instruct-0905` | Kimi K2 Instruct 0905 | `generate` | Yes | | `llama-3.1-8b-instant` | Llama 3.1 8B Instant | `generate` | Yes | | `llama-3.3-70b-versatile` | Llama 3.3 70B Versatile | `generate` | Yes | | `meta-llama/llama-4-maverick-17b-128e-instruct` | Llama 4 Maverick 17B | `analyze`, `generate` | Yes | | `meta-llama/llama-4-scout-17b-16e-instruct` | Llama 4 Scout 17B | `analyze`, `generate` | Yes | | `qwen/qwen3-32b` | Qwen 3 32B | `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # Mistral AI (/providers/mistral) Mistral

Celeste supports Mistral's open-weights and commercial models. ## Credentials Set the `MISTRAL_API_KEY` environment variable. ```bash export MISTRAL_API_KEY="..." ``` ## Text Generation ### Models * `mistral-large-latest` (Default) * `mistral-small-latest` * `codestral-latest` ### Usage ```python import celeste response = await celeste.text.generate( model="mistral-large-latest", provider="mistral", prompt="Hello Mistral", ) ``` ## Models{/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `analyze`, `generate` ### Text | Model ID | Display name | Operations | Streaming | | :------------------------- | :--------------- | :-------------------- | :-------- | | `codestral-latest` | Codestral | `generate` | Yes | | `devstral-2512` | Devstral 2 | `generate` | Yes | | `labs-devstral-small-2512` | Devstral 2 Small | `generate` | Yes | | `devstral-medium-latest` | Devstral Medium | `generate` | Yes | | `magistral-medium-latest` | Magistral Medium | `analyze`, `generate` | Yes | | `magistral-small-latest` | Magistral Small | `analyze`, `generate` | Yes | | `ministral-14b-latest` | Ministral 14B | `generate` | Yes | | `ministral-3b-latest` | Ministral 3B | `generate` | Yes | | `ministral-8b-latest` | Ministral 8B | `generate` | Yes | | `mistral-large-latest` | Mistral Large | `generate` | Yes | | `mistral-medium-latest` | Mistral Medium | `analyze`, `generate` | Yes | | `mistral-small-latest` | Mistral Small | `analyze`, `generate` | Yes | | `mistral-tiny` | Mistral Tiny | `generate` | Yes | | `open-mistral-7b` | Open Mistral 7B | `generate` | Yes | | `pixtral-12b-2409` | Pixtral 12B | `analyze`, `generate` | Yes | | `pixtral-12b-latest` | Pixtral 12B | `analyze`, `generate` | Yes | | `pixtral-large-latest` | Pixtral Large | `analyze`, `generate` | Yes | | `voxtral-mini-2507` | Voxtral Mini | `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} # Moonshot (/providers/moonshot)

Celeste supports the **Moonshot** provider. ## Credentials Set the `MOONSHOT_API_KEY` environment variable. ```bash export MOONSHOT_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `analyze`, `generate` ### Text | Model ID | Display name | Operations | Streaming | | :------------------------------ | :------------------------------ | :-------------------- | :-------- | | `kimi-k2-0711-preview` | Kimi K2 (0711 Preview) | `generate` | Yes | | `kimi-k2-0905-preview` | Kimi K2 (0905 Preview) | `generate` | Yes | | `kimi-k2-thinking` | Kimi K2 Thinking | `generate` | Yes | | `kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo | `generate` | Yes | | `kimi-k2-turbo-preview` | Kimi K2 Turbo Preview | `generate` | Yes | | `moonshot-v1-8k-vision-preview` | Moonshot v1 8K Vision (Preview) | `analyze`, `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # OpenAI (/providers/openai) OpenAI

Celeste supports OpenAI's full suite of models, including GPT-4o for text, DALL-E 3 for images, and TTS for speech. ## Credentials Set the `OPENAI_API_KEY` environment variable. ```bash export OPENAI_API_KEY="sk-..." ``` ## Text Generation ### Models * `gpt-4o` (Default) * `gpt-4o-mini` * `gpt-4-turbo` * `gpt-3.5-turbo` ### Usage ```python import celeste response = await celeste.text.generate( model="gpt-4o", prompt="Hello GPT-4o", ) ``` ## Image Generation ### Models * `dall-e-3` (Default) * `dall-e-2` ### Usage ```python import celeste response = await celeste.images.generate( model="dall-e-3", prompt="A cute robot", quality="hd", ) ``` ## Speech Generation ### Models * `tts-1` (Default) * `tts-1-hd` ### Usage ```python import celeste response = await celeste.audio.speak( model="tts-1", text="Hello world", voice="alloy", ) ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `audio`: `speak` * `images`: `edit`, `generate` * `text`: `analyze`, `generate` * `videos`: `generate` ### Text | Model ID | Display name | Operations | Streaming | | :-------------------- | :-------------- | :-------------------- | :-------- | | `gpt-3.5-turbo` | GPT-3.5 Turbo | `generate` | Yes | | `gpt-4` | GPT-4 | `generate` | Yes | | `gpt-4-turbo` | GPT-4 Turbo | `analyze`, `generate` | Yes | | `gpt-4.1` | GPT-4.1 | `analyze`, `generate` | Yes | | `gpt-4o` | GPT-4o | `analyze`, `generate` | Yes | | `gpt-4o-mini` | GPT-4o Mini | `analyze`, `generate` | Yes | | `gpt-5` | GPT-5 | `analyze`, `generate` | Yes | | `gpt-5-mini` | GPT-5 Mini | `analyze`, `generate` | Yes | | `gpt-5-nano` | GPT-5 Nano | `analyze`, `generate` | Yes | | `gpt-5.1` | GPT-5.1 | `analyze`, `generate` | Yes | | `gpt-5.1-codex` | GPT-5.1 Codex | `analyze`, `generate` | Yes | | `gpt-5.2` | GPT-5.2 | `analyze`, `generate` | Yes | | `gpt-5.2-codex` | GPT-5.2 Codex | `analyze`, `generate` | Yes | | `gpt-5.2-chat-latest` | GPT-5.2 Instant | `analyze`, `generate` | Yes | | `gpt-5.2-pro` | GPT-5.2 Pro | `analyze`, `generate` | Yes | ### Images | Model ID | Display name | Operations | Streaming | | :----------------- | :--------------- | :----------------- | :-------- | | `dall-e-2` | DALL-E 2 | `edit`, `generate` | No | | `dall-e-3` | DALL-E 3 | `generate` | No | | `gpt-image-1` | GPT Image 1 | `edit`, `generate` | Yes | | `gpt-image-1-mini` | GPT Image 1 Mini | `edit`, `generate` | Yes | | `gpt-image-1.5` | GPT Image 1.5 | `edit`, `generate` | No | ### Audio | Model ID | Display name | Operations | Streaming | | :---------------- | :-------------- | :--------- | :-------- | | `gpt-4o-mini-tts` | GPT-4o Mini TTS | `speak` | No | | `tts-1` | TTS-1 | `speak` | No | | `tts-1-hd` | TTS-1 HD | `speak` | No | ### Videos | Model ID | Display name | Operations | Streaming | | :------------------ | :--------------------- | :--------- | :-------- | | `sora-2` | Sora 2 | `generate` | No | | `sora-2-2025-12-08` | Sora 2 (December 2025) | `generate` | No | | `sora-2-pro` | Sora 2 Pro | `generate` | No | {/* AUTO-GENERATED:MODELS:END */} # xAI (/providers/xai) xAI

Celeste supports the **xAI** provider. ## Credentials Set the `XAI_API_KEY` environment variable. ```bash export XAI_API_KEY="..." ``` ## Models {/* AUTO-GENERATED:MODELS:START */} This section is auto-generated from the Celeste registry. Do not edit manually. Available modalities: * `text`: `analyze`, `generate` ### Text | Model ID | Display name | Operations | Streaming | | :---------------------------- | :-------------------------- | :-------------------- | :-------- | | `grok-2-vision-1212` | Grok 2 Vision | `analyze`, `generate` | Yes | | `grok-3-mini` | Grok 3 Mini | `generate` | Yes | | `grok-4-0709` | Grok 4 | `generate` | Yes | | `grok-4-fast-non-reasoning` | Grok 4 Fast Non-Reasoning | `generate` | Yes | | `grok-4-fast-reasoning` | Grok 4 Fast Reasoning | `generate` | Yes | | `grok-4-1-fast-non-reasoning` | Grok 4.1 Fast Non-Reasoning | `generate` | Yes | | `grok-4-1-fast-reasoning` | Grok 4.1 Fast Reasoning | `generate` | Yes | {/* AUTO-GENERATED:MODELS:END */} ## Notes *Add provider-specific tips, caveats, and examples here.* # Streaming (/guides/streaming) # Streaming Streaming allows you to receive chunks of a response as they are generated, rather than waiting for the entire response to complete. This is essential for creating responsive user experiences. ## Basic Usage Use the domain namespace with `.stream` to access streaming operations. ```python import celeste stream = celeste.text.stream.generate( model="gpt-4o", prompt="Count from 1 to 10", max_tokens=50, ) async for chunk in stream: # chunk is strongly typed based on the modality print(chunk.content, end="", flush=True) ``` ## Handling Chunks Different modalities produce different types of chunks. ### Text Generation Yields `TextChunk`. `chunk.content` is a `str`. ```python async for chunk in stream: print(chunk.content, end="") ``` ### Speech Generation Yields `AudioChunk`. `chunk.content` is `bytes` (raw audio data). ```python # Example: Writing to a file stream or audio player with open("output.mp3", "wb") as f: async for chunk in stream: f.write(chunk.content) ``` ### Image & Video Most image and video models do not support streaming of the content itself during generation, but some providers may support progress updates. Currently, Celeste treats image/video generation as atomic operations mostly, but the interface supports streaming if providers enable it. ## Accessing Final Output After the stream is exhausted, you can access the aggregated `output` property of the stream object. This is equivalent to what `generate()` returns. ```python # Consume stream async for chunk in stream: pass # Access final aggregated result final_response = stream.output print(f"Total tokens: {final_response.usage.total_tokens}") ``` > **Note**: You must consume the stream fully before accessing `.output`. Otherwise, a `StreamNotExhaustedError` is raised. # Authentication (/guides/authentication) # Authentication Celeste supports two authentication methods: API keys for most providers, and OAuth for Google Cloud APIs. ## API Keys (Most Providers) ### Environment Variables Set your API key as an environment variable: ```bash export OPENAI_API_KEY="sk-..." ``` Or use a `.env` file: ```bash title=".env" OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-... ``` ### Provider Reference | Provider | Environment Variable | | --------------- | -------------------- | | OpenAI | `OPENAI_API_KEY` | | Anthropic | `ANTHROPIC_API_KEY` | | Google (Gemini) | `GOOGLE_API_KEY` | | Mistral | `MISTRAL_API_KEY` | | Cohere | `COHERE_API_KEY` | | ElevenLabs | `ELEVENLABS_API_KEY` | | Groq | `GROQ_API_KEY` | | BFL | `BFL_API_KEY` | | DeepSeek | `DEEPSEEK_API_KEY` | | xAI | `XAI_API_KEY` | ## Google Cloud (OAuth) Google Cloud APIs (like Cloud TTS with Gemini voices) require OAuth authentication instead of API keys. ### Setup 1. Install the [gcloud CLI](https://cloud.google.com/sdk/docs/install) 2. Login with Application Default Credentials: ```bash gcloud auth application-default login ``` 3. Set your project (for billing/quota): ```bash gcloud config set project YOUR_PROJECT_ID ``` ### Usage ```python import celeste # No API key needed - uses OAuth automatically response = await celeste.audio.speak( model="gemini-2.5-flash-tts", provider="google", text="Hello from Google Cloud", ) ``` ### Troubleshooting | Error | Solution | | ------------------------------------------ | ----------------------------------------------- | | `RefreshError: Reauthentication is needed` | Run `gcloud auth application-default login` | | Quota/project errors | Run `gcloud config set project YOUR_PROJECT_ID` | ## Explicit Authentication Override environment variables by passing `api_key` directly: ```python import celeste response = await celeste.text.generate( model="gpt-4o", api_key="sk-...", prompt="Hello", ) ``` ### Advanced: custom auth headers For custom headers, use `create_client` with the `auth` parameter: ```python import celeste from celeste import APIKey client = celeste.create_client( modality="text", auth=APIKey( key="sk-...", header="X-Custom-Header", ), ) ``` # Multi-Modal Workflows (/guides/multi-modal) # Multi-Modal Workflows One of Celeste's strengths is the ability to combine different modalities using a consistent interface. ## Text to Image Generate an image based on a detailed description created by an LLM. ```python import celeste # 1. Generate prompt (domain: text) prompt_response = await celeste.text.generate( model="claude-sonnet-4-5", prompt="Describe a surreal landscape with floating islands in 2 sentences.", ) image_prompt = prompt_response.content print(f"Generating image for: {image_prompt}") # 2. Generate image (domain: images) image_response = await celeste.images.generate( model="gpt-image-1", prompt=image_prompt, quality="hd" ) # 4. Save with open("surreal_islands.png", "wb") as f: f.write(image_response.content.get_bytes()) ``` ## Image to Text (Vision) Analyze an image using a vision model. This uses the **images domain**, but the **output modality is text**. ```python from celeste.artifacts import ImageArtifact # Load image image = ImageArtifact(path="surreal_islands.png") # Analyze (domain: images, output: text) description = await celeste.images.analyze( model="gpt-4o", prompt="What colors are dominant in this image?", image=image ) print(description.content) ``` ## Text to Speech Read out generated text. ```python story = await celeste.text.generate( model="gpt-4o", prompt="Tell a very short story.", ) audio = await celeste.audio.speak( model="eleven_v3", text=story.content, voice="rachel" ) with open("story.mp3", "wb") as f: f.write(audio.content.get_bytes()) ``` # Error Handling (/guides/error-handling) # Error Handling Celeste provides a hierarchy of exceptions to help you handle errors gracefully. All exceptions inherit from `celeste.exceptions.Error`. ## Exception Hierarchy * **`Error`**: Base class for all Celeste errors. * **`ModelError`** * **`ModelNotFoundError`**: The requested model (or a default) could not be found. * **`ClientError`** * **`ClientNotFoundError`**: No client implementation exists for the provider/modality. * **`ModalityNotFoundError`**: No client registered for the requested modality. * **`CredentialsError`** * **`MissingCredentialsError`**: API key is missing. * **`UnsupportedProviderError`**: Provider is not configured in the credential system. * **`ValidationError`** * **`ConstraintViolationError`**: A parameter value violates model constraints (e.g., temperature > 2.0). * **`UnsupportedParameterError`**: The model doesn't support a passed parameter. * **`StreamingError`** * **`StreamingNotSupportedError`**: The model doesn't support streaming. * **`StreamNotExhaustedError`**: Accessed `.output` before stream finished. * **`StreamEmptyError`**: Stream produced no chunks. * **`httpx.HTTPStatusError`**: Underlying HTTP errors from providers (400, 401, 429, 500). ## Example ```python import celeste from celeste.exceptions import MissingCredentialsError, ModelNotFoundError import httpx try: response = await celeste.text.generate( model="gpt-4o", prompt="Hello" ) except MissingCredentialsError: print("Please set your OPENAI_API_KEY.") except ModelNotFoundError: print("The requested model isn't available.") except httpx.HTTPStatusError as e: print(f"Provider API error: {e.response.status_code} - {e.response.text}") ``` # Architecture (/contributing/architecture) # Architecture Celeste v1 is designed around a **modality-centric core** with a **namespace-first public API**. Internally, the system is organized by the *output* type (modality), while the external API starts from the domain you work with. ## Core Concepts The architecture is built on three pillars: 1. **Modality (Output)**: The output type returned by an operation (e.g., text, images, audio, embeddings). 2. **Domain (What you work with)**: The resource you operate on (e.g., text, image, audio, video). 3. **Operation (Transformation)**: The method you call (e.g., `generate`, `analyze`). Rule of thumb: * **Namespaces use domains**: start from `celeste.images`, `celeste.audio`, etc. * **Clients use modalities**: use `create_client(modality=...)` when you need explicit control. ## Package Structure The codebase is organized as a monolith, with modalities and providers grouped under `src/celeste`. ``` src/celeste/ ├── modalities/ │ ├── text/ │ │ ├── client.py # TextClient(ModalityClient) │ │ ├── io.py # Inputs, Outputs, Chunks │ │ └── providers/ │ ├── images/ │ ├── audio/ │ ├── videos/ │ └── embeddings/ ├── providers/ # Provider integrations └── namespaces/ # Domain-first namespace API ``` ### Key Components * **`ModalityClient`**: The base class for all modality clients (e.g., `ImagesClient`). It handles shared infrastructure like HTTP clients and authentication. * **Operations as Methods**: Unlike previous versions where operations were separate packages, they are now methods on the client (e.g., `client.generate()`, `client.edit()`). * **Operation-Scoped Types**: Inputs and Parameters are scoped to specific operations to ensure type safety. ## Client Design The namespace API routes **domain + operation → modality client** under the hood. ### Execution Modes Clients support three execution modes to handle different use cases: 1. **Async (Default)**: `await client.generate(...)` - Returns typed Output objects. Best for production applications. 2. **Streaming**: `client.stream.generate(...)` - Returns an `AsyncIterator` of Chunks. Best for UIs requiring real-time feedback. 3. **Sync**: `client.sync.generate(...)` - Blocking calls. Best for scripts, notebooks, and testing. ### Example: Images Domain Namespace The `celeste.images` namespace groups operations by the **image domain**, even when the output is text: * `celeste.images.generate(...)` → image output. * `celeste.images.edit(...)` → image output. * `celeste.images.analyze(...)` → text output. This keeps the public API intuitive while maintaining consistent output types via modality clients. # Adding a Provider (/contributing/adding-a-provider) # Adding a Provider Celeste makes it easy to add support for new AI providers. This guide outlines the steps to implement a new provider within an existing modality package. ## Directory Structure Providers live under the monolith at `src/celeste/modalities//providers/`. For example, to add a provider to the `images` modality: ``` src/celeste/modalities/images/providers/ └── {provider_slug}/ ├── __init__.py ├── client.py ├── models.py └── parameters.py ``` ## Implementation Steps ### 1. Create the Provider Package Create a new directory for your provider using the slug (e.g., `midjourney`, `stability`). You can also start from the templates in `templates/providers/` for a full scaffold. ### 2. Implement the Client (`client.py`) The client implementation handles the communication with the provider's API. * Inherit from the modality's base client or a specific internal interface. * Implement the `_make_request` or equivalent method to send data to the API. * Map the provider's response to the Celeste standard `Output` objects defined in `io.py`. ### 3. Define Models (`models.py`) List the available models supported by this provider for this modality. ```python from celeste.models import Model from celeste.core import Modality, Operation MODELS = [ Model( id="provider-model-v1", provider="new_provider", operations={ Modality.IMAGES: {Operation.GENERATE} } ) ] ``` ### 4. Map Parameters (`parameters.py`) Map Celeste's standard parameters (like `quality`, `size`) to the provider's specific API parameters. * Use `ParameterMapper` classes to handle conversions. * Ensure that provider-specific parameters are handled gracefully. ### 5. Register the Provider (`__init__.py`) Expose the client and models in the provider's `__init__.py` so they can be discovered by the core registry. ## Testing 1. **Unit Tests**: Create tests in `tests/unit_tests/` to verify parameter mapping and response parsing without making network calls. 2. **Integration Tests**: Create tests in `tests/integration_tests/` to verify actual API interaction (requires API keys). ## Best Practices * **Type Safety**: Use full type hints for all methods. * **Error Handling**: Catch provider-specific errors and raise Celeste's standard exceptions where appropriate. * **Documentation**: Add docstrings to your classes and methods explaining any provider-specific behaviors. # ByteDance (/providers/bytedance)

Celeste supports ByteDance's models via the BytePlus provider for video generation. ## Credentials Set the `BYTEPLUS_API_KEY` environment variable. ```bash export BYTEPLUS_API_KEY="..." ``` ## Video Generation ### Models * `pixeldance` (Default) ### Usage ```python import celeste response = await celeste.videos.generate( model="pixeldance", provider="byteplus", prompt="A panda eating bamboo", aspect_ratio="16:9", ) ```