Celeste AI

https://github.com/withceleste/docs
Admin
Celeste AI is an AI platform that provides multi-modal capabilities for text, image, video, and...
Tokens:24,551
Snippets:250
Trust Score:4.5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Celeste AI

Source: https://github.com/withceleste/docs/blob/main/content/docs/getting-started/quickstart.mdx

Installs the Celeste AI library using the 'uv' package manager. This is the first step to using Celeste AI in your project.

```bash
uv add celeste-ai
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/withceleste/docs/blob/main/README.md

Installs project dependencies using the Bun package manager. Ensure Bun (v1.0+) is installed before running.

```bash
bun install
```

--------------------------------

### Generate Speech with ElevenLabs (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/elevenlabs.mdx

Example of how to generate speech using the ElevenLabs provider with Celeste. It demonstrates specifying the model, provider, text content, and voice. Requires the Celeste library to be installed.

```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
)
```

--------------------------------

### Start Development Server with Bun

Source: https://github.com/withceleste/docs/blob/main/README.md

Starts the development server for the Celeste AI documentation. This command is used to preview changes locally during development. Open http://localhost:3000 in your browser.

```bash
bun run dev
```

--------------------------------

### Build and Start Production Server with Bun

Source: https://github.com/withceleste/docs/blob/main/README.md

Builds the project for production deployment and then starts the production server. These commands are used to prepare and run the application in a live environment.

```bash
bun run build
bun run start
```

--------------------------------

### Configure Celeste AI Credentials

Source: https://github.com/withceleste/docs/blob/main/content/docs/getting-started/quickstart.mdx

Sets up API keys for Celeste AI by exporting them as environment variables or by creating a .env file. This is necessary for authentication with the Celeste AI service.

```bash
export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."
```

```dotenv
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
```

--------------------------------

### Install Celeste AI Python SDK

Source: https://context7.com/withceleste/docs/llms.txt

Installs the Celeste AI Python SDK using package managers like uv, pip, or poetry. Ensure you have a compatible Python environment.

```bash
# Using uv (recommended)
uv add celeste-ai

# Using pip
pip install celeste-ai

# Using poetry
poetry add celeste-ai
```

--------------------------------

### Multi-Modal Content Generation with Celeste AI

Source: https://github.com/withceleste/docs/blob/main/content/docs/getting-started/quickstart.mdx

Demonstrates Celeste AI's unified interface for generating different types of content, including text, images, and videos. It showcases asynchronous calls for each domain, requiring a model and a prompt specific to the content type.

```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",
)
```

--------------------------------

### Google Cloud OAuth Setup (Bash)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/authentication.mdx

Commands to set up OAuth authentication for Google Cloud services using the gcloud CLI. This includes logging in with Application Default Credentials and setting the active project.

```bash
gcloud auth application-default login
```

```bash
gcloud config set project YOUR_PROJECT_ID
```

--------------------------------

### Generate Text Content (Async)

Source: https://github.com/withceleste/docs/blob/main/content/docs/getting-started/quickstart.mdx

Generates text content using the Celeste AI library's asynchronous text generation method. This is recommended for production applications and notebooks due to its non-blocking nature. It requires specifying a model and a prompt.

```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)
```

```python
response = await celeste.text.generate(
    model="claude-sonnet-4-5",
    prompt="Explain quantum computing in one sentence.",
    temperature=0.7,
)
print(response.content)
```

--------------------------------

### Generate Text with OpenAI (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/openai.mdx

Example of generating text using the Celeste library with OpenAI models like gpt-4o. It requires the 'celeste' library and an active internet connection.

```python
import celeste

response = await celeste.text.generate(
    model="gpt-4o",
    prompt="Hello GPT-4o",
)
```

--------------------------------

### Install Git Hooks with Lefthook

Source: https://github.com/withceleste/docs/blob/main/README.md

Installs pre-commit Git hooks using Lefthook. This ensures code quality checks are performed before committing changes.

```bash
bunx lefthook install
```

--------------------------------

### Image Analysis with Celeste Python Client

Source: https://github.com/withceleste/docs/blob/main/content/docs/modalities/index.mdx

Demonstrates how to use the Celeste Python client to analyze an image and generate a text description. This operation routes through the 'images' domain to produce text output. It requires the 'celeste' library to be installed.

```python
import celeste

# Domain: images → output: text
result = await celeste.images.analyze(
    model="gpt-4o",
    prompt="Describe this image",
    image=img,
)
```

--------------------------------

### Type Safety Example (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Highlights the type safety benefits of the Celeste client API, where IDEs can provide autocomplete and type checking for parameters and response objects.

```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
```

--------------------------------

### Generate Text Content (Sync)

Source: https://github.com/withceleste/docs/blob/main/content/docs/getting-started/quickstart.mdx

Generates text content using Celeste AI's synchronous text generation method. This is suitable for scripts and simple tools as it uses blocking I/O. It requires specifying a model, a prompt, and optionally a temperature.

```python
response = celeste.text.sync.generate(
    model="claude-sonnet-4-5",
    prompt="Explain quantum computing in one sentence.",
    temperature=0.7,
)
print(response.content)
```

--------------------------------

### Google Cloud Text-to-Speech with Celeste (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/authentication.mdx

Example of using Celeste to generate speech with Google Cloud's TTS models via OAuth. It demonstrates how the library automatically handles authentication when configured.

```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",
)
```

--------------------------------

### Generate Video with Google Veo

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/google.mdx

Generate video content using Google's Veo models through the Celeste SDK. This function requires specifying the model, provider, and a text prompt. An example model is 'veo-3.0-generate-001'.

```python
import celeste

video = await celeste.videos.generate(
    model="veo-3.0-generate-001",
    provider="google",
    prompt="A sunrise over the mountains",
)
```

--------------------------------

### Analyze Video and Get Text Description (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/modalities/video.mdx

Analyzes a video file and returns a text description based on a given prompt. Requires the 'celeste' library, 'VideoArtifact', and an async context. Takes a video file path and a text prompt as input, returning a text response.

```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)

```

--------------------------------

### Generate Text with Mistral AI using Celeste

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/mistral.mdx

This Python code demonstrates how to generate text using Mistral AI models through the Celeste library. It requires the 'celeste' library to be installed. The function takes a model name, provider, and prompt as input, and returns a response object.

```python
import celeste

response = await celeste.text.generate(
    model="mistral-large-latest",
    provider="mistral",
    prompt="Hello Mistral",
)
```

--------------------------------

### Generate Image using Celeste

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/modality-and-operation.mdx

Demonstrates how to generate an image using the Celeste library. It requires the 'celeste' library to be imported and uses an asynchronous call to the 'images.generate' function with a specified model and prompt. The output is an image object.

```python
import celeste

response = await celeste.images.generate(
    model="gpt-image-1",
    prompt="A red apple",
)
image = response.content
```

--------------------------------

### Analyze Image using Celeste

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/modality-and-operation.mdx

Shows how to analyze an image using the Celeste library. This involves importing 'celeste' and 'ImageArtifact'. An 'ImageArtifact' is created from a file path, and then passed to the 'celeste.images.analyze' function along with a model and prompt. The output is text describing the image.

```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
```

--------------------------------

### Create Celeste Client (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Demonstrates how to create a Celeste client with explicit control over modality, provider, and model. This function is modality-first, allowing specification of output type and optional operations.

```python
import celeste

client = celeste.create_client(
    modality="text",
    provider="openai",
    model="gpt-4o",
)
```

--------------------------------

### Set ElevenLabs API Key (Bash)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/elevenlabs.mdx

Instructions to set the ELEVENLABS_API_KEY environment variable for authentication with the ElevenLabs API. This is a prerequisite for using the ElevenLabs provider.

```bash
export ELEVENLABS_API_KEY="..."
```

--------------------------------

### Create Configured Client for Text Generation (Async)

Source: https://context7.com/withceleste/docs/llms.txt

Creates a reusable client with explicit provider and model configuration for text generation. Supports asynchronous execution. Requires modality, provider, and model.

```python
import celeste
from celeste import Provider, APIKey

# Create a configured client (modality-first approach)
client = celeste.create_client(
    modality="text",
    provider="openai",
    model="gpt-4o",
)

# Use the client with different execution modes
# Async (default)
response = await client.generate(prompt="Hello world", temperature=0.7)
print(response.content)
```

--------------------------------

### Generate Video from Prompt (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/modalities/video.mdx

Generates a video from a text prompt using the Celeste library. Requires the 'celeste' library and an async context. Outputs video content that can be saved to a file.

```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())

```

--------------------------------

### Generate Video from Text Prompt using Ray-2

Source: https://context7.com/withceleste/docs/llms.txt

Generates a video based on a text description. Requires a model, prompt, and desired duration. Saves the generated video to a file.

```python
import celeste

# Generate a video from text prompt
video = await celeste.videos.generate(
    model="ray-2",
    prompt="A drone shot of a beautiful coastline at sunset",
    duration=8,
)

# Save the generated video
with open("coastline.mp4", "wb") as f:
    f.write(video.content.get_bytes())
```

--------------------------------

### Celeste AI Text Generation (Async and Sync)

Source: https://context7.com/withceleste/docs/llms.txt

Demonstrates text generation using Celeste AI. Supports asynchronous (recommended for production) and synchronous execution modes. Requires API key configuration.

```python
import celeste

# Automatic credential loading from environment
response = await celeste.text.generate(
    model="gpt-4o",
    prompt="Hello world",
)

# Explicit API key override
response = await celeste.text.generate(
    model="gpt-4o",
    api_key="sk-your-key-here",
    prompt="Hello world",
)

# Basic text generation (async - recommended for production)
response = await celeste.text.generate(
    model="claude-sonnet-4-5",
    prompt="Explain quantum computing in one sentence.",
    temperature=0.7,
)
print(response.content)
# Output: "Quantum computing harnesses quantum mechanical phenomena..."

# Synchronous generation (for scripts and notebooks)
response = celeste.text.sync.generate(
    model="gpt-4o",
    prompt="Write a haiku about AI",
    max_tokens=100,
)
print(response.content)
print(f"Tokens used: {response.usage.total_tokens}")
```

--------------------------------

### Create Configured Client for Text Generation (Streaming)

Source: https://context7.com/withceleste/docs/llms.txt

Creates a reusable client with explicit provider and model configuration for text generation. Supports streaming output for real-time processing. Requires modality, provider, and model.

```python
import celeste
from celeste import Provider, APIKey

# Create a configured client (modality-first approach)
client = celeste.create_client(
    modality="text",
    provider="openai",
    model="gpt-4o",
)

# Streaming
stream = client.stream.generate(prompt="Count from 1 to 5")
async for chunk in stream:
    print(chunk.content, end="")
final_response = stream.output
```

--------------------------------

### Generate Video with ByteDance (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/bytedance.mdx

This Python code demonstrates how to generate a video using the BytePlus provider and the 'pixeldance' model. It takes a prompt and aspect ratio as input and returns a video generation response.

```python
import celeste

response = await celeste.videos.generate(
    model="pixeldance",
    provider="byteplus",
    prompt="A panda eating bamboo",
    aspect_ratio="16:9",
)
```

--------------------------------

### Set xAI API Key

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/xai.mdx

Configure the XAI_API_KEY environment variable to authenticate with the xAI provider. This is a prerequisite for making any API calls.

```bash
export XAI_API_KEY="..."
```

--------------------------------

### Create Client (Advanced)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Use `create_client` for explicit control and reuse of configured clients. This function is modality-first, allowing you to specify the output type and optionally the operation.

```APIDOC
## POST /client/create

### Description
Creates a new Celeste client with specified modality, provider, and model.

### Method
POST

### Endpoint
/client/create

### Parameters
#### Request Body
- **`modality`** (string) - Required - The modality to use (e.g., "text", "images").
- **`operation`** (string) - Optional - Operation filter.
- **`provider`** (string) - Optional - The provider to use (e.g., "openai", "anthropic").
- **`model`** (string) - Optional - Specific model to use.
- **`api_key`** (string) - Optional - API key override.
- **`auth`** (object) - Optional - Custom authentication override (advanced).

### Request Example
```json
{
  "modality": "text",
  "provider": "openai",
  "model": "gpt-4o"
}
```

### Response
#### Success Response (200)
- **`client_id`** (string) - Unique identifier for the created client.

#### Response Example
```json
{
  "client_id": "clt_abc123xyz"
}
```
```

--------------------------------

### Basic Streaming Text Generation with Celeste (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/streaming.mdx

Demonstrates how to initiate a streaming text generation request using Celeste and iterate over the response chunks. Requires the 'celeste' library.

```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)
```

--------------------------------

### Generate and Analyze Video with Python

Source: https://github.com/withceleste/docs/blob/main/content/docs/domains/video.mdx

Demonstrates video generation using a specified model and prompt, followed by video analysis to extract textual descriptions. Requires the 'celeste' library and 'VideoArtifact' for handling video files.

```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)
```

--------------------------------

### Speak and Analyze Audio with Celeste (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/domains/audio.mdx

Demonstrates how to use the Celeste library to convert text to speech and analyze audio content. The 'speak' operation generates audio output, while 'analyze' processes audio and returns a text summary. Requires the 'celeste' library and potentially artifact classes like AudioArtifact.

```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)
```

--------------------------------

### Generate Video from Text Prompt using Veo-3

Source: https://context7.com/withceleste/docs/llms.txt

Generates a video from a text prompt using Google's Veo model. Requires a model and prompt. Saves the generated video to a file.

```python
import celeste

# Using Google's Veo model
video = await celeste.videos.generate(
    model="veo-3",
    prompt="Waves crashing on a beach in slow motion",
)
with open("waves.mp4", "wb") as f:
    f.write(video.content.get_bytes())
```

--------------------------------

### Generate Image with OpenAI (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/openai.mdx

Demonstrates how to generate images using the Celeste library with OpenAI's DALL-E models. This function requires the 'celeste' library and specifies the model, prompt, and quality.

```python
import celeste

response = await celeste.images.generate(
    model="dall-e-3",
    prompt="A cute robot",
    quality="hd",
)
```

--------------------------------

### Video Generation with Google Models

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/google.mdx

Generate videos using Google's video generation models like `veo-3.0-generate-001`.

```APIDOC
## Video Generation with Google Models

### Description
Generate videos based on a text prompt using Google's video generation models. An example model is `veo-3.0-generate-001`.

### Method
`POST` (Assumed, based on typical API patterns for generation)

### Endpoint
`/videos/generate` (Assumed, based on usage example)

### Parameters
#### Query Parameters
- **provider** (string) - Required - Must be set to `"google"`.

#### Request Body
- **model** (string) - Optional - The video generation model to use (e.g., `"veo-3.0-generate-001"`).
- **prompt** (string) - Required - The text prompt describing the video to generate.

### Request Example
```python
import celeste

video = await celeste.videos.generate(
    model="veo-3.0-generate-001",
    provider="google",
    prompt="A sunrise over the mountains",
)
```

### Response
#### Success Response (200)
- **video_url** (string) - The URL of the generated video.

#### Response Example
```json
{
  "video_url": "https://example.com/videos/sunrise.mp4"
}
```
```

--------------------------------

### Set Groq API Key Environment Variable

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/groq.mdx

This snippet shows how to set the GROQ_API_KEY environment variable, which is required for authenticating with the Groq API. Ensure this variable is set before running any Groq-related operations.

```bash
export GROQ_API_KEY="..."
```

--------------------------------

### Custom Authentication Headers with Celeste (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/authentication.mdx

Shows how to create a Celeste client with custom authentication headers using the `APIKey` class. This is useful for providers that require non-standard header names.

```python
import celeste
from celeste import APIKey

client = celeste.create_client(
    modality="text",
    auth=APIKey(
        key="sk-...",
        header="X-Custom-Header",
    ),
)
```

--------------------------------

### Explicit API Key Authentication with Celeste (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/authentication.mdx

Demonstrates how to explicitly pass an API key to the Celeste library for text generation, overriding any environment variable settings.

```python
import celeste

response = await celeste.text.generate(
    model="gpt-4o",
    api_key="sk-...",
    prompt="Hello",
)
```

--------------------------------

### Multi-Modal Workflow: Image Generation and Analysis

Source: https://context7.com/withceleste/docs/llms.txt

Demonstrates a multi-modal workflow involving text-to-image generation, followed by image analysis and audio narration. This showcases combining different Celeste modules for complex tasks.

```python
import celeste
from celeste.artifacts import ImageArtifact

# Workflow: Generate image prompt with LLM, then create image
# Step 1: Generate a creative prompt
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"Generated prompt: {image_prompt}")

# Step 2: Generate image from the prompt
image_response = await celeste.images.generate(
    model="gpt-image-1",
    prompt=image_prompt,
    quality="hd",
)
with open("surreal_landscape.png", "wb") as f:
    f.write(image_response.content.get_bytes())

# Step 3: Analyze the generated image
image = ImageArtifact(path="surreal_landscape.png")
description = await celeste.images.analyze(
    model="gpt-4o",
    image=image,
    prompt="What colors and elements are prominent in this image?",
)
print(f"Image analysis: {description.content}")

# Step 4: Generate narration audio
story = await celeste.text.generate(
    model="gpt-4o",
    prompt=f"Write a short 2-sentence story about: {description.content}",
)
audio = await celeste.audio.speak(
    model="eleven_v3",
    text=story.content,
    voice="rachel",
)
with open("narration.mp3", "wb") as f:
    f.write(audio.content.get_bytes())
```

--------------------------------

### Code Quality Commands with Bun

Source: https://github.com/withceleste/docs/blob/main/README.md

Executes code quality checks including formatting, linting, and type checking using Bun. The 'make ci' command runs the full Continuous Integration pipeline.

```bash
bun run format
bun run lint
bun run typecheck
make ci
```

--------------------------------

### Custom Authentication Headers with Celeste

Source: https://context7.com/withceleste/docs/llms.txt

Shows how to configure the Celeste client with custom authentication headers. This is useful when the API key needs to be sent in a non-standard header.

```python
client = celeste.create_client(
    modality="text",
    auth=APIKey(
        key="sk-custom-key",
        header="X-Custom-Header",
    ),
)
```

--------------------------------

### Error Handling in Celeste AI

Source: https://context7.com/withceleste/docs/llms.txt

Illustrates robust error handling for AI operations using Celeste's exception hierarchy. It covers common issues like missing credentials, model not found, constraint violations, and HTTP errors.

```python
import celeste
from celeste.exceptions import (
    MissingCredentialsError,
    ModelNotFoundError,
    StreamNotExhaustedError,
    ConstraintViolationError,
)
import httpx

try:
    response = await celeste.text.generate(
        model="gpt-4o",
        prompt="Hello",
        temperature=0.7,
    )
    print(response.content)

except MissingCredentialsError:
    print("Error: Please set your OPENAI_API_KEY environment variable.")

except ModelNotFoundError:
    print("Error: The requested model is not available.")

except ConstraintViolationError as e:
    print(f"Error: Parameter constraint violated - {e}")

except httpx.HTTPStatusError as e:
    if e.response.status_code == 429:
        print("Rate limited. Please wait and retry.")
    elif e.response.status_code == 401:
        print("Invalid API key.")
    else:
        print(f"API error: {e.response.status_code} - {e.response.text}")
```

--------------------------------

### Set Google API Key

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/google.mdx

Configure the GOOGLE_API_KEY environment variable to authenticate with Google services. This is a prerequisite for using any Google provider functionalities within Celeste.

```bash
export GOOGLE_API_KEY="AIza..."
```

--------------------------------

### Google Provider Credentials

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/google.mdx

To use the Google provider, you need to set the GOOGLE_API_KEY environment variable with your Google API key.

```APIDOC
## Google Provider Credentials

### Description
Set the `GOOGLE_API_KEY` environment variable with your Google API key to authenticate requests.

### Method
Environment Variable Configuration

### Endpoint
N/A

### Parameters
#### Environment Variables
- **GOOGLE_API_KEY** (string) - Required - Your Google API key.

### Request Example
```bash
export GOOGLE_API_KEY="AIza..."
```

### Response
N/A
```

--------------------------------

### Analyze Video Content with GPT-4o

Source: https://context7.com/withceleste/docs/llms.txt

Analyzes a video file to generate a textual description of its content. Requires a VideoArtifact object and a prompt. Outputs a description of the video.

```python
import celeste
from celeste.artifacts import VideoArtifact

# Load a video for analysis
video = VideoArtifact(path="clip.mp4")

# Analyze the video content
response = await celeste.videos.analyze(
    model="gpt-4o",
    video=video,
    prompt="Describe what happens in this video",
)
print(response.content)
```

--------------------------------

### Analyze Image Content with GPT-4o

Source: https://context7.com/withceleste/docs/llms.txt

Analyzes an image to provide a detailed textual description. Requires an image object and a prompt. Outputs the detailed content of the image.

```python
response = await celeste.images.analyze(
    model="gpt-4o",
    image=image,
    prompt="What is in this image? Describe in detail.",
)
print(response.content)
```

--------------------------------

### Async Client Execution (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Shows how to use the default async execution mode of a Celeste client to generate a response. This mode is suitable for production applications and returns a complete typed output object.

```python
response = await client.generate(prompt="Hello world", temperature=0.7)
print(response.content)
```

--------------------------------

### Celeste AI Image Generation

Source: https://context7.com/withceleste/docs/llms.txt

Generates images from text prompts using various AI models like DALL-E and GPT Image. Requires API key configuration and saves the output to a file.

```python
import celeste

# Generate an image
response = await celeste.images.generate(
    model="gpt-image-1",
    prompt="A cyberpunk city at night with neon lights",
    aspect_ratio="16:9",
    quality="hd",
)

# Save the generated image
with open("cyberpunk_city.png", "wb") as f:
    f.write(response.content.get_bytes())

# Using DALL-E 3
response = await celeste.images.generate(
    model="dall-e-3",
    prompt="A cute robot holding flowers",
    quality="hd",
)
with open("robot.png", "wb") as f:
    f.write(response.content.get_bytes())
```

--------------------------------

### Streaming Client Execution (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Illustrates how to use the streaming execution mode of a Celeste client to receive response chunks as they are generated. This is ideal for UIs that require 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)
```

--------------------------------

### Analyze Image using Celeste Python SDK

Source: https://github.com/withceleste/docs/blob/main/content/docs/domains/index.mdx

This Python code snippet demonstrates how to use the Celeste SDK to analyze an image. It specifies the domain as 'images' and the output modality as 'text', using the 'gpt-4o' model to describe the image provided by the 'img' variable. The response content, which is the textual description, is then printed.

```python
import celeste

# Domain: images → output: text
response = await celeste.images.analyze(
    model="gpt-4o",
    prompt="Describe this image",
    image=img,
)
print(response.content)
```

--------------------------------

### Stream Audio Generation with ElevenLabs

Source: https://context7.com/withceleste/docs/llms.txt

Streams audio generation in real-time using ElevenLabs TTS. Processes audio chunks as they arrive for immediate playback or saving. Requires model, text, and voice.

```python
import celeste

# Stream audio generation
stream = celeste.audio.stream.speak(
    model="eleven_v3",
    text="This is a long text that will be streamed as audio...",
    voice="rachel",
)

# Process audio chunks as they arrive
with open("streamed_output.mp3", "wb") as f:
    async for chunk in stream:
        # chunk.content is bytes (raw audio data)
        f.write(chunk.content)
        # Or: player.write(chunk.content) for real-time playback
```

--------------------------------

### Set BytePlus API Key Environment Variable

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/byteplus.mdx

This snippet shows how to set the BYTEPLUS_API_KEY environment variable, which is required for authenticating with the BytePlus provider. Ensure this variable is exported in your shell environment before running any BytePlus operations.

```bash
export BYTEPLUS_API_KEY="..."
```

--------------------------------

### Celeste AI Streaming Text Generation (Async and Sync)

Source: https://context7.com/withceleste/docs/llms.txt

Shows how to stream text responses in real-time using Celeste AI for interactive applications. Supports both asynchronous and synchronous streaming.

```python
import celeste

# Streaming text generation
stream = celeste.text.stream.generate(
    model="gpt-4o",
    prompt="Count from 1 to 10 slowly",
    max_tokens=50,
)

async for chunk in stream:
    print(chunk.content, end="", flush=True)

# Access final aggregated response after streaming
final_response = stream.output
print(f"\nTotal tokens: {final_response.usage.total_tokens}")

# Synchronous streaming
stream = celeste.text.sync.stream.generate(
    model="claude-sonnet-4-5",
    prompt="Tell me a story",
)
for chunk in stream:
    print(chunk.content, end="")
print(stream.output.content)
```

--------------------------------

### Analyze Image using Python

Source: https://github.com/withceleste/docs/blob/main/content/docs/domains/images.mdx

Analyzes an image and returns a text description based on the provided prompt and model. Requires the 'celeste' library and an ImageArtifact object.

```python
import celeste
from celeste.artifacts import ImageArtifact

# 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)
```

--------------------------------

### Generate Image from Text Prompt using Celeste

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/multi-modal.mdx

This snippet shows how to generate an image from a text description. It first uses a text generation model to create a detailed prompt and then uses an image generation model to create the image. The output image is saved to a file. Dependencies: celeste library.

```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())

```

--------------------------------

### Sync Streaming Client Execution (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Shows how to use the synchronous streaming execution mode of a Celeste client. This allows for receiving response chunks in a blocking manner, suitable for certain script-based scenarios.

```python
stream = client.sync.stream.generate(prompt="Hello world")
for chunk in stream:
    print(chunk.content, end="")
print(stream.output.content)
```

--------------------------------

### Sync Client Execution (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/client.mdx

Demonstrates the synchronous execution mode of a Celeste client, which performs blocking calls. This mode is useful for scripts, notebooks, and testing purposes.

```python
response = client.sync.generate(prompt="Hello world")
print(response.content)
```

--------------------------------

### Generate Text with Cohere Models using Python

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/cohere.mdx

Demonstrates how to generate text using Cohere's Command R series models via the Celeste Python SDK. It specifies the model and provides a prompt as input.

```python
import celeste

response = await celeste.text.generate(
    model="command-a-03-2025",
    prompt="Hello Command R",
)
```

--------------------------------

### API Key Configuration in .env File

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/authentication.mdx

Defines API keys for multiple providers within a `.env` file. This approach centralizes API key management for different services used by the application.

```dotenv
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-...
```

--------------------------------

### Text Generation with Gemini

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/google.mdx

Generate text using Google's Gemini models. Supports `gemini-1.5-pro` and `gemini-1.5-flash`.

```APIDOC
## Text Generation with Gemini

### Description
Generate text responses using Google's Gemini models. The default model is `gemini-1.5-pro`.

### Method
`POST` (Assumed, based on typical API patterns for generation)

### Endpoint
`/text/generate` (Assumed, based on usage example)

### Parameters
#### Query Parameters
- **provider** (string) - Required - Must be set to `"google"`.

#### Request Body
- **model** (string) - Optional - The Gemini model to use (e.g., `"gemini-1.5-pro"`, `"gemini-1.5-flash"`). Defaults to `"gemini-1.5-pro"`.
- **prompt** (string) - Required - The input prompt for text generation.

### Request Example
```python
import celeste

response = await celeste.text.generate(
    model="gemini-1.5-pro",
    provider="google",
    prompt="Hello Gemini",
)
```

### Response
#### Success Response (200)
- **response** (object) - The generated text response from the model.

#### Response Example
```json
{
  "response": "Hello! How can I help you today?"
}
```
```

--------------------------------

### Generate Text with Explicit API Key in Python

Source: https://github.com/withceleste/docs/blob/main/content/docs/core-concepts/providers.mdx

Demonstrates how to generate text using a specific AI model and provider (OpenAI in this case) by explicitly passing the API key. It utilizes the `celeste.text.generate` function and requires the `celeste` library and the `Provider` enum.

```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",
)
```

--------------------------------

### Cohere Credentials

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/cohere.mdx

To use the Cohere provider, you need to set the COHERE_API_KEY environment variable with your Cohere API key.

```APIDOC
## Credentials

Set the `COHERE_API_KEY` environment variable.

```bash
export COHERE_API_KEY="..."
```
```

--------------------------------

### Set Moonshot API Key (Bash)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/moonshot.mdx

Configure the necessary API key for the Moonshot provider by setting the MOONSHOT_API_KEY environment variable. This is a prerequisite for authenticating with the Moonshot service.

```bash
export MOONSHOT_API_KEY="..."
```

--------------------------------

### Synthesize Speech with OpenAI TTS

Source: https://context7.com/withceleste/docs/llms.txt

Converts text into natural-sounding speech using OpenAI's TTS model. Requires a model, text, and voice. Saves the generated audio to an MP3 file.

```python
import celeste

# Using OpenAI TTS
audio = await celeste.audio.speak(
    model="tts-1-hd",
    text="Welcome to our application!",
    voice="alloy",
)
with open("welcome.mp3", "wb") as f:
    f.write(audio.content.get_bytes())
```

--------------------------------

### Analyze Audio Content with GPT-4o

Source: https://context7.com/withceleste/docs/llms.txt

Analyzes an audio file to generate text transcriptions or summaries. Requires an AudioArtifact object and a prompt. Outputs the transcription or summary of the audio.

```python
import celeste
from celeste.artifacts import AudioArtifact

# Load an audio file for analysis
audio = AudioArtifact(path="recording.mp3")

# Analyze the audio content
response = await celeste.audio.analyze(
    model="gpt-4o",
    audio=audio,
    prompt="Summarize what is being said in this audio",
)
print(response.content)
```

--------------------------------

### Available Models

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/cohere.mdx

Lists the available Cohere models supported by Celeste, including their ID, display name, operations, and streaming capabilities.

```APIDOC
## Models

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 |
```

--------------------------------

### Analyze Audio Content with Celeste Python SDK

Source: https://github.com/withceleste/docs/blob/main/content/docs/modalities/audio.mdx

Analyzes audio content from a file and returns a text summary using the 'gpt-4o' model. Requires the Celeste library and the 'celeste.artifacts.AudioArtifact' class.

```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)

```

--------------------------------

### Generate Text with Anthropic Claude (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/anthropic.mdx

Demonstrates basic text generation using Celeste's Python client with an Anthropic Claude model. It requires the 'celeste' library and an active API key. The function takes a model name and a prompt as input and returns the generated text.

```python
import celeste

response = await celeste.text.generate(
    model="claude-3-5-sonnet-20240620",
    prompt="Hello Claude",
)
```

--------------------------------

### Set BFL API Key Environment Variable

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/bfl.mdx

Configure the necessary API key for authentication with the Black Forest Labs provider. This environment variable is required for all subsequent operations.

```bash
export BFL_API_KEY="..."
```

--------------------------------

### Generate Speech with OpenAI (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/openai.mdx

This Python code snippet shows how to use the Celeste library to generate speech using OpenAI's TTS models. It requires the 'celeste' library and specifies the model, text, and voice.

```python
import celeste

response = await celeste.audio.speak(
    model="tts-1",
    text="Hello world",
    voice="alloy",
)
```

--------------------------------

### Image Generation with Imagen

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/google.mdx

Generate images using Google's Imagen models. Supports `imagen-3.0-generate-001`.

```APIDOC
## Image Generation with Imagen

### Description
Generate images based on a text prompt using Google's Imagen models. The default model is `imagen-3.0-generate-001`.

### Method
`POST` (Assumed, based on typical API patterns for generation)

### Endpoint
`/images/generate` (Assumed, based on usage example)

### Parameters
#### Query Parameters
- **provider** (string) - Required - Must be set to `"google"`.

#### Request Body
- **model** (string) - Optional - The Imagen model to use (e.g., `"imagen-3.0-generate-001"`). Defaults to `"imagen-3.0-generate-001"`.
- **prompt** (string) - Required - The text prompt describing the image to generate.

### Request Example
```python
import celeste

response = await celeste.images.generate(
    model="imagen-3.0-generate-001",
    provider="google",
    prompt="A futuristic landscape",
)
```

### Response
#### Success Response (200)
- **image_url** (string) - The URL of the generated image.

#### Response Example
```json
{
  "image_url": "https://example.com/images/futuristic_landscape.png"
}
```
```

--------------------------------

### Generate Text with Extended Thinking Budget (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/anthropic.mdx

This Python code snippet illustrates how to leverage Anthropic models for more complex tasks by utilizing the 'thinking_budget' parameter. This allows the model to spend more computational resources on solving intricate problems. It requires the 'celeste' library and a valid API key.

```python
response = await celeste.text.generate(
    model="claude-3-5-sonnet-20240620",
    prompt="Solve this complex logic puzzle...",
    thinking_budget=4096
)
```

--------------------------------

### Handling Audio Chunks in Streaming Responses (Python)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/streaming.mdx

Illustrates how to handle audio chunks received during a streaming speech generation response, saving the raw audio data to a file. Assumes a 'stream' object from a previous speech generation call.

```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)
```

--------------------------------

### Synthesize Speech with ElevenLabs TTS

Source: https://context7.com/withceleste/docs/llms.txt

Converts text into natural-sounding speech using ElevenLabs' TTS model. Requires a model, text, and voice. Saves the generated audio to an MP3 file.

```python
import celeste

# Generate speech with ElevenLabs
audio = await celeste.audio.speak(
    model="eleven_v3",
    text="Hello, this is a generated voice.",
    voice="rachel",
)

# Save the audio file
with open("output.mp3", "wb") as f:
    f.write(audio.content.get_bytes())
```

--------------------------------

### Celeste Package Structure

Source: https://github.com/withceleste/docs/blob/main/content/docs/contributing/architecture.mdx

Illustrates the directory layout of the Celeste v1 codebase, highlighting the organization of modalities, providers, and namespaces.

```tree
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
```

--------------------------------

### Convert Text to Speech using Celeste

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/multi-modal.mdx

This snippet shows how to convert generated text into speech. It first generates a short story using a text model and then uses the celeste.audio.speak function to convert the text to an MP3 audio file. Dependencies: celeste library.

```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())

```

--------------------------------

### Set Mistral API Key Environment Variable

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/mistral.mdx

This snippet shows how to set the MISTRAL_API_KEY environment variable, which is required for authenticating with the Mistral API. No specific inputs or outputs are defined, as it's a shell command.

```bash
export MISTRAL_API_KEY="..."
```

--------------------------------

### Set API Key Environment Variable (Bash)

Source: https://github.com/withceleste/docs/blob/main/content/docs/guides/authentication.mdx

Sets an API key for a provider as an environment variable in the bash shell. This is a common method for configuring API access for various services.

```bash
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Celeste AI Image Editing

Source: https://context7.com/withceleste/docs/llms.txt

Edits existing images using AI prompts and optional masks. Loads an image, applies modifications, and saves the result. Requires API key configuration.

```python
import celeste
from celeste.artifacts import ImageArtifact

# Load an existing image
base_image = ImageArtifact(path="photo.png")

# Edit the image with a prompt
response = await celeste.images.edit(
    model="gpt-image-1",
    image=base_image,
    prompt="Add a red hat to the person",
    # mask=mask_artifact  # Optional: specify areas to edit
)

# Save the edited image
with open("photo_with_hat.png", "wb") as f:
    f.write(response.content.get_bytes())
```

--------------------------------

### Set DeepSeek API Key Environment Variable

Source: https://github.com/withceleste/docs/blob/main/content/docs/providers/deepseek.mdx

This snippet shows how to set the DEEPSEEK_API_KEY environment variable, which is required for authenticating with the DeepSeek API. Ensure this variable is set in your environment before making API calls.

```bash
export DEEPSEEK_API_KEY="..."
```
Tokens:
Raw