@j-o-r/hello-dave 0.0.10 → 0.1.0

package/lib/API/x.ai/image.md

@@ -0,0 +1,213 @@
+#### Model Capabilities
+
+# Imagine Overview
+
+The Imagine API lets you generate and edit images and videos with Grok Imagine models. Use it for image generation, image editing with up to 3 reference images, video generation from text or still images, video editing, and more.
+
+## Pricing
+
+Image generation uses flat per-image pricing regardless of prompt length. Each generated image incurs a fixed fee. Image edits are billed for both the input image and the generated output image. Video generation uses per-second pricing where both duration and resolution affect the total cost. For full pricing details, see the [models page](/developers/models#imagine-pricing).
+
+## Image Editing
+
+Edit a source image with natural language. Provide a public image URL or base64-encoded data URI, then describe the change you want Grok Imagine to apply. Multi-image editing supports up to 3 source images in a single request for combining subjects, transferring styles, and composing scenes.
+
+```python customLanguage="pythonXAI"
+import base64
+import xai_sdk
+
+client = xai_sdk.Client()
+
+# Load image from file and encode as base64
+with open("photo.png", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode("utf-8")
+
+response = client.image.sample(
+    prompt="Render this as a pencil sketch with detailed shading",
+    model="grok-imagine-image-quality",
+    image_url=f"data:image/png;base64,{image_data}",
+)
+
+print(response.url)
+```
+
+```bash
+# Using a public URL as the source image
+curl -X POST https://api.x.ai/v1/images/edits \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "Render this as a pencil sketch with detailed shading",
+    "image": {
+      "url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png",
+      "type": "image_url"
+    }
+  }'
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+import fs from "fs";
+
+// Load image and encode as base64
+const imageBuffer = fs.readFileSync("photo.png");
+const base64Image = imageBuffer.toString("base64");
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: {
+        text: "Render this as a pencil sketch with detailed shading",
+        images: [`data:image/png;base64,${base64Image}`],
+    },
+});
+
+console.log(image.base64);
+```
+
+## Image Generation
+
+Generate new images from text prompts with Grok Imagine models. Configure output count (up to 10 images per request), aspect ratio, resolution, and response format.
+
+```python customLanguage="pythonXAI"
+import xai_sdk
+
+client = xai_sdk.Client()
+
+response = client.image.sample(
+    prompt="A collage of London landmarks in a stenciled street‑art style",
+    model="grok-imagine-image-quality",
+)
+
+print(response.url)
+```
+
+```bash
+curl -X POST https://api.x.ai/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "A collage of London landmarks in a stenciled street‑art style"
+  }'
+```
+
+```python customLanguage="pythonOpenAISDK"
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.x.ai/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.images.generate(
+    model="grok-imagine-image-quality",
+    prompt="A collage of London landmarks in a stenciled street‑art style",
+)
+
+print(response.data[0].url)
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: "A collage of London landmarks in a stenciled street‑art style",
+});
+
+console.log(image.base64);
+```
+
+## Image-to-Video
+
+Animate a still image with a text prompt. The source image becomes the starting point for the generated video. Video requests are asynchronous: start a request, poll with the returned request ID, and use the completed video URL when ready. The xAI SDK and AI SDK handle polling for you.
+
+```python customLanguage="pythonXAI"
+import os
+import xai_sdk
+
+client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
+
+response = client.video.generate(
+    prompt="Make the water crash down and slowly pan out the camera",
+    model="grok-imagine-video",
+    image_url="https://docs.x.ai/assets/api-examples/video/waterfall-still.png",
+    duration=12,
+)
+
+print(response.url)
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { experimental_generateVideo as generateVideo } from "ai";
+
+const result = await generateVideo({
+    model: xai.video("grok-imagine-video"),
+    prompt: {
+        image: "https://docs.x.ai/assets/api-examples/video/waterfall-still.png",
+        text: "Make the water crash down and slowly pan out the camera",
+    },
+    duration: 12,
+});
+
+const videoUrl = result.providerMetadata?.xai?.videoUrl;
+console.log(videoUrl);
+```
+
+```bash
+# Start the video generation request
+REQUEST_ID=$(curl -s -X POST https://api.x.ai/v1/videos/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-video",
+    "prompt": "Make the water crash down and slowly pan out the camera",
+    "image": {"url": "https://docs.x.ai/assets/api-examples/video/waterfall-still.png"},
+    "duration": 12
+  }' | jq -r '.request_id')
+
+# Poll until the video is ready
+while true; do
+  RESULT=$(curl -s https://api.x.ai/v1/videos/$REQUEST_ID \
+    -H "Authorization: Bearer $XAI_API_KEY")
+  STATUS=$(echo "$RESULT" | jq -r '.status')
+  if [ "$STATUS" = "done" ]; then
+    echo "$RESULT" | jq -r '.video.url'
+    break
+  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ]; then
+    echo "Request $STATUS"; echo "$RESULT" | jq .
+    break
+  fi
+  sleep 5
+done
+```
+
+## More Capabilities
+
+Beyond the top use cases above, the Imagine API supports several additional workflows:
+
+* **[Multi-Image Editing](/developers/model-capabilities/images/multi-image-editing)** — Combine up to 3 source images in a single edit for compositing subjects, transferring styles, and building scenes from multiple references.
+* **[Video Generation](/developers/model-capabilities/video/generation)** — Generate videos from text prompts with configurable duration (up to 15s), aspect ratio, and resolution.
+* **[Video Editing](/developers/model-capabilities/video/editing)** — Modify an existing video with a text prompt while preserving the rest of the scene.
+* **[Reference-to-Video](/developers/model-capabilities/video/reference-to-video)** — Guide a generated video with one or more reference images that influence the output without forcing the first frame.
+* **[Video Extension](/developers/model-capabilities/video/extension)** — Continue an existing video from its last frame, combining the original and extension into one clip.
+
+## Enterprise Compliance & Security
+
+The Imagine APIs are built for production workloads with strict security and compliance requirements. Generated media is subject to content policy review and is not used for training.
+
+* **SOC 2 Type II** — Audited controls for security, availability, and confidentiality
+
+* **HIPAA Eligible** — BAA available for healthcare applications handling PHI
+
+* **GDPR Compliant** — Data processing agreements and EU data residency options
+
+* **Data Residency** — Regional processing for compliance requirements
+
+* **High Availability** — Multi-region infrastructure with custom SLAs for enterprise workloads
+
+* **SSO & RBAC** — SAML SSO, role-based access, and audit logging

package/lib/API/x.ai/image.to.generation.md

@@ -0,0 +1,494 @@
+#### Model Capabilities
+
+# Image Generation
+
+Generate images from text prompts with Grok Imagine models. The API supports batch generation of multiple images, and control over aspect ratio and resolution.
+
+> [!WARNING]
+>
+> **`grok-imagine-image-pro` will be deprecated as of May 15, 2026.** Use `grok-imagine-image-quality` for all new image generation requests. Existing `-pro` requests will continue to work during a transition period, but we recommend migrating promptly.
+
+## Quick Start
+
+Generate an image with a single API call:
+
+```python customLanguage="pythonXAI"
+import xai_sdk
+
+client = xai_sdk.Client()
+
+response = client.image.sample(
+    prompt="A collage of London landmarks in a stenciled street‑art style",
+    model="grok-imagine-image-quality",
+)
+
+print(response.url)
+```
+
+```bash
+curl -X POST https://api.x.ai/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "A collage of London landmarks in a stenciled street‑art style"
+  }'
+```
+
+```python customLanguage="pythonOpenAISDK"
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.x.ai/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.images.generate(
+    model="grok-imagine-image-quality",
+    prompt="A collage of London landmarks in a stenciled street‑art style",
+)
+
+print(response.data[0].url)
+```
+
+```javascript customLanguage="javascriptOpenAISDK"
+import OpenAI from "openai";
+
+const client = new OpenAI({
+    apiKey: process.env.XAI_API_KEY,
+    baseURL: 'https://api.x.ai/v1',
+});
+
+const response = await client.images.generate({
+    model: "grok-imagine-image-quality",
+    prompt: "A collage of London landmarks in a stenciled street‑art style",
+});
+
+console.log(response.data[0].url);
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: "A collage of London landmarks in a stenciled street‑art style",
+});
+
+console.log(image.base64);
+```
+
+Images are returned as URLs by default. URLs are temporary, so download or process promptly. You can also request [base64 output](#base64-output) for embedding images directly.
+
+## Configuration
+
+### Multiple Images
+
+Generate multiple images in a single request using the `sample_batch()` method and the `n` parameter. This returns a list of `ImageResponse` objects.
+
+```python customLanguage="pythonXAI"
+import xai_sdk
+
+client = xai_sdk.Client()
+
+responses = client.image.sample_batch(
+    prompt="A futuristic city skyline at night",
+    model="grok-imagine-image-quality",
+    n=4,
+)
+
+for i, image in enumerate(responses):
+    print(f"Variation {i + 1}: {image.url}")
+```
+
+```python customLanguage="pythonOpenAISDK"
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.x.ai/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.images.generate(
+    model="grok-imagine-image-quality",
+    prompt="A futuristic city skyline at night",
+    n=4,
+)
+
+for i, image in enumerate(response.data):
+    print(f"Variation {i + 1}: {image.url}")
+```
+
+```javascript customLanguage="javascriptOpenAISDK"
+import OpenAI from "openai";
+
+const client = new OpenAI({
+    apiKey: process.env.XAI_API_KEY,
+    baseURL: "https://api.x.ai/v1",
+});
+
+const response = await client.images.generate({
+    model: "grok-imagine-image-quality",
+    prompt: "A futuristic city skyline at night",
+    n: 4,
+});
+
+response.data.forEach((image, i) => {
+    console.log(`Variation ${i + 1}: ${image.url}`);
+});
+
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+
+const { images } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: "A futuristic city skyline at night",
+    n: 4,
+});
+
+images.forEach((image, i) => {
+    console.log(`Variation ${i + 1}: ${image.base64.slice(0, 50)}...`);
+});
+
+```
+
+```bash
+curl -X POST https://api.x.ai/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "A futuristic city skyline at night",
+    "n": 4
+  }'
+```
+
+### Aspect Ratio
+
+Control image dimensions with the `aspect_ratio` parameter. This works for image generation and image editing with multiple images.
+For image editing with a single image, the output aspect ratio respects the input image's aspect ratio.
+
+| Ratio | Use case |
+|-------|----------|
+| `1:1` | Social media, thumbnails |
+| `16:9` / `9:16` | Widescreen, mobile, stories |
+| `4:3` / `3:4` | Presentations, portraits |
+| `3:2` / `2:3` | Photography |
+| `2:1` / `1:2` | Banners, headers |
+| `19.5:9` / `9:19.5` | Modern smartphone displays |
+| `20:9` / `9:20` | Ultra-wide displays |
+| `auto` | Model auto-selects the best ratio for the prompt |
+
+```python customLanguage="pythonXAI"
+import xai_sdk
+
+client = xai_sdk.Client()
+
+response = client.image.sample(
+    prompt="Mountain landscape at sunrise",
+    model="grok-imagine-image-quality",
+    aspect_ratio="16:9",
+)
+
+print(response.url)
+```
+
+```python customLanguage="pythonOpenAISDK"
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.x.ai/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.images.generate(
+    model="grok-imagine-image-quality",
+    prompt="Mountain landscape at sunrise",
+    extra_body={"aspect_ratio": "16:9"},
+)
+
+print(response.data[0].url)
+```
+
+```javascript customLanguage="javascriptOpenAISDK"
+import OpenAI from "openai";
+
+const client = new OpenAI({
+    apiKey: process.env.XAI_API_KEY,
+    baseURL: "https://api.x.ai/v1",
+});
+
+const response = await client.images.generate({
+    model: "grok-imagine-image-quality",
+    prompt: "Mountain landscape at sunrise",
+
+    aspect_ratio: "16:9",
+});
+
+console.log(response.data[0].url);
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: "Mountain landscape at sunrise",
+    aspectRatio: "16:9",
+});
+
+console.log(image.base64);
+```
+
+```bash
+curl -X POST https://api.x.ai/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "Mountain landscape at sunrise",
+    "aspect_ratio": "16:9"
+  }'
+```
+
+### Resolution
+
+You can specify different resolutions of the output image. Currently supported image resolutions are:
+
+* 1k
+* 2k
+
+```python customLanguage="pythonXAI"
+import xai_sdk
+
+client = xai_sdk.Client()
+
+response = client.image.sample(
+    prompt="An astronaut performing EVA in LEO.",
+    model="grok-imagine-image-quality",
+    resolution="2k"
+)
+
+print(response.url)
+```
+
+```python customLanguage="pythonOpenAISDK"
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.x.ai/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.images.generate(
+    model="grok-imagine-image-quality",
+    prompt="An astronaut performing EVA in LEO.",
+    extra_body={"resolution": "2k"},
+)
+
+print(response.data[0].url)
+```
+
+```javascript customLanguage="javascriptOpenAISDK"
+import OpenAI from "openai";
+
+const client = new OpenAI({
+    apiKey: process.env.XAI_API_KEY,
+    baseURL: "https://api.x.ai/v1",
+});
+
+const response = await client.images.generate({
+    model: "grok-imagine-image-quality",
+    prompt: "An astronaut performing EVA in LEO.",
+
+    resolution: "2k",
+});
+
+console.log(response.data[0].url);
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: "An astronaut performing EVA in LEO.",
+    providerOptions: {
+        xai: { resolution: "2k" },
+    },
+});
+
+console.log(image.base64);
+```
+
+```bash
+curl -X POST https://api.x.ai/v1/images/generations \
+-H "Content-Type: application/json" \
+-H "Authorization: Bearer $XAI_API_KEY" \
+-d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "An astronaut performing EVA in LEO.",
+    "resolution": "2k"
+}'
+```
+
+### Base64 Output
+
+For embedding images directly without downloading, request base64:
+
+```python customLanguage="pythonXAI"
+import xai_sdk
+
+client = xai_sdk.Client()
+
+response = client.image.sample(
+    prompt="A serene Japanese garden",
+    model="grok-imagine-image-quality",
+    image_format="base64",
+)
+
+# Save to file
+with open("garden.jpg", "wb") as f:
+    f.write(response.image)
+```
+
+```python customLanguage="pythonOpenAISDK"
+import base64
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.x.ai/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.images.generate(
+    model="grok-imagine-image-quality",
+    prompt="A serene Japanese garden",
+    response_format="b64_json",
+)
+
+# Save to file
+image_bytes = base64.b64decode(response.data[0].b64_json)
+with open("garden.jpg", "wb") as f:
+    f.write(image_bytes)
+```
+
+```javascript customLanguage="javascriptOpenAISDK"
+import OpenAI from "openai";
+import fs from "fs";
+
+const client = new OpenAI({
+    apiKey: process.env.XAI_API_KEY,
+    baseURL: "https://api.x.ai/v1",
+});
+
+const response = await client.images.generate({
+    model: "grok-imagine-image-quality",
+    prompt: "A serene Japanese garden",
+    response_format: "b64_json",
+});
+
+// Save to file
+const imageBuffer = Buffer.from(response.data[0].b64_json, "base64");
+fs.writeFileSync("garden.jpg", imageBuffer);
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+import fs from "fs";
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: "A serene Japanese garden",
+});
+
+// Save to file (AI SDK returns base64 by default)
+const imageBuffer = Buffer.from(image.base64, "base64");
+fs.writeFileSync("garden.jpg", imageBuffer);
+```
+
+```bash
+curl -X POST https://api.x.ai/v1/images/generations \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "A serene Japanese garden",
+    "response_format": "b64_json"
+  }'
+```
+
+### Response Details
+
+The xAI SDK exposes additional metadata on the response object beyond the image URL or base64 data.
+
+**Moderation** — Check whether the generated image passed content moderation:
+
+```python customLanguage="pythonXAI"
+if response.respect_moderation:
+    print(response.url)
+else:
+    print("Image filtered by moderation")
+```
+
+**Model** — Get the actual model used (resolving any aliases):
+
+```python customLanguage="pythonXAI"
+print(f"Model: {response.model}")
+```
+
+## Concurrent Requests
+
+When you need to generate multiple images with **different prompts**, such as generating unrelated images in parallel, use `AsyncClient` with `asyncio.gather` to fire requests concurrently. This is significantly faster than issuing them one at a time.
+
+> [!TIP]
+>
+> If you want multiple variations from the **same prompt**, use [`sample_batch()` with the `n` parameter\`](#multiple-images) instead. That generates all images in a single request and is the most efficient approach for same-prompt generation.
+
+```python customLanguage="pythonXAI"
+import asyncio
+import xai_sdk
+
+async def generate_concurrently():
+    client = xai_sdk.AsyncClient()
+
+    # Each request uses a different prompt
+    prompts = [
+        "A futuristic city skyline at sunset",
+        "A serene Japanese garden in winter",
+        "An astronaut floating above Earth",
+        "A medieval castle on a misty mountain",
+    ]
+
+    # Fire all requests concurrently
+    tasks = [
+        client.image.sample(
+            prompt=prompt,
+            model="grok-imagine-image-quality",
+        )
+        for prompt in prompts
+    ]
+
+    results = await asyncio.gather(*tasks)
+
+    for prompt, result in zip(prompts, results):
+        print(f"{prompt}: {result.url}")
+
+asyncio.run(generate_concurrently())
+```
+
+## Related
+
+* [Models](/developers/models) — Available image models
+* [Image Editing](/developers/model-capabilities/images/editing) — Edit images with natural language
+* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts
+* [API Reference](/developers/rest-api-reference) — Full endpoint documentation
+* [Imagine API Landing Page](https://x.ai/api/imagine) — Showcase of the Imagine API in action
+