AI

Learn about AI capabilities in the API; generate text and images using Cosmic AI.

Cosmic provides AI-powered text and image generation capabilities through the API and SDK.

Base URL

Use the following endpoint to create AI-generated text and images.

https://workers.cosmicjs.com

POST/v3/buckets/:bucket_slug/ai/text

Generate Text

This endpoint enables you to generate text content using AI models.

Required parameters

You must provide either a prompt or messages parameter.

  • Name
    prompt
    Type
    string
    Description

    A text prompt for the AI to generate content from. Use this for simple, single-prompt text generation.

  • Name
    messages
    Type
    array
    Description

    An array of message objects for chat-based models. Each message object should have a role (either "user" or "assistant") and content (the message text).

Optional parameters

  • Name
    model
    Type
    string
    Description

    The AI model to use for text generation. Options include Claude models (e.g., claude-sonnet-4-5-20250929), Gemini models (e.g., gemini-3-pro-preview), and OpenAI models (e.g., gpt-5). Defaults to claude-sonnet-4-5-20250929. See Available Models section for full list.

  • Name
    max_tokens
    Type
    number
    Description

    The maximum number of tokens to generate in the response. Higher values allow for longer responses but may increase processing time.

  • Name
    media_url
    Type
    string
    Description

    URL of a file to analyze. Can be any file type available in your Bucket including images, PDFs, Excel spreadsheets, Word documents, and more. The AI model will be able to analyze the content when generating text. Can be used with either prompt or messages.

  • Name
    stream
    Type
    boolean
    Description

    When set to true, enables streaming for real-time responses as they're generated, rather than waiting for the complete response. Default is false.

Request Examples

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

// Using a simple prompt
const textResponse = await cosmic.ai.generateText({
  prompt: 'Write a product description for a coffee mug',
  max_tokens: 500
})

console.log(textResponse.text)
console.log(textResponse.usage)

Media Analysis Examples

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

const imageAnalysis = await cosmic.ai.generateText({
  prompt: 'Describe this image in detail and suggest a caption for social media',
  media_url: 'https://cdn.cosmicjs.com/mountain-landscape.jpg',
  max_tokens: 500
})

console.log(imageAnalysis.text)
console.log(imageAnalysis.usage)

cURL Examples

curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/text \
  -d '{"prompt":"Write a product description for a coffee mug","max_tokens":500}' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer {BUCKET_WRITE_KEY}"

Response Examples

{
  "text": "Introducing our Artisan Ceramic Coffee Mug – the perfect companion for your daily brew. Crafted with care from high-quality ceramic, this elegant mug retains heat longer, ensuring your coffee stays at the ideal temperature. The ergonomic handle provides a comfortable grip, while the smooth, glazed interior prevents staining and makes cleaning effortless. Available in a range of sophisticated colors to match any kitchen aesthetic, this 12oz mug strikes the perfect balance between style and functionality.",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 89
  }
}

Streaming Capabilities

Text generation supports real-time streaming responses, allowing you to receive and display content as it's being generated.

Using with the SDK

import { TextStreamingResponse } from '@cosmicjs/sdk';

// Enable streaming with the stream: true parameter
const result = await cosmic.ai.generateText({
  prompt: 'Tell me about coffee mugs',
  // or use messages array format
  max_tokens: 500,
  stream: true // Enable streaming
});

// Cast the result to TextStreamingResponse
const stream = result as TextStreamingResponse;

// Option 1: Event-based approach
let fullResponse = '';
stream.on('text', (text) => {
  fullResponse += text;
  process.stdout.write(text); // Display text as it arrives
});
stream.on('usage', (usage) => console.log('Usage:', usage));
stream.on('end', (data) => console.log('Complete:', fullResponse));
stream.on('error', (error) => console.error('Error:', error));

// Option 2: For-await loop approach
async function processStream() {
  let fullResponse = '';
  try {
    for await (const chunk of stream) {
      if (chunk.text) {
        fullResponse += chunk.text;
        process.stdout.write(chunk.text);
      }
    }
    console.log('\nComplete text:', fullResponse);
  } catch (error) {
    console.error('Error:', error);
  }
}

Using the simplified stream method

// Simplified streaming method
const stream = await cosmic.ai.stream({
  prompt: 'Tell me about coffee mugs',
  max_tokens: 500,
});

// Process stream using events or for-await loop as shown above

Using cURL for streaming

curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/text \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BUCKET_WRITE_KEY}" \
  -d '{"prompt":"Tell me about coffee mugs","stream":true}' \
  --no-buffer

The TextStreamingResponse supports two usage patterns:

  1. Event-based: Extends EventEmitter with these events:

    • text: New text fragments
    • usage: Token usage information
    • end: Final data when stream completes
    • error: Stream errors
  2. AsyncIterator: For for-await loops, with chunk objects containing:

    • text: Text fragments
    • usage: Token usage information
    • end: Set to true for the final chunk
    • error: Error information

POST/v3/buckets/:bucket_slug/ai/image

Generate Image

This endpoint enables you to create AI-generated images based on text prompts.

Required parameters

  • Name
    prompt
    Type
    string
    Description

    A text description of the image you want to generate. More detailed prompts typically yield better results.

Optional parameters

  • Name
    model
    Type
    string
    Description

    The image generation model to use. Options: dall-e-3 (default) or gemini-3-pro-image-preview. Defaults to dall-e-3.

  • Name
    size
    Type
    string
    Description

    The size of the generated image. For DALL-E 3: 1024x1024, 1792x1024, or 1024x1792. For Gemini 3 Pro Image: 1024x1024, 2048x2048, or 4096x4096. Defaults to 1024x1024.

  • Name
    quality
    Type
    string
    Description

    The quality of the generated image. Options: standard or hd. Defaults to standard. HD quality provides more detailed images but costs more. (DALL-E 3 only)

  • Name
    reference_images
    Type
    array
    Description

    Array of reference image URLs to provide context for image generation. The AI will analyze these images and use them to inform the generated image. Only supported with gemini-3-pro-image-preview model.

  • Name
    folder
    Type
    string
    Description

    Media folder to store the generated image in.

  • Name
    alt_text
    Type
    string
    Description

    Alt text for the generated image.

  • Name
    metadata
    Type
    object
    Description

    User-added JSON metadata for the generated image.

Request Examples

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

const imageResponse = await cosmic.ai.generateImage({
  prompt: 'A serene mountain landscape at sunset',
  folder: 'ai-generated',
  alt_text: 'AI-generated mountain landscape at sunset',
  metadata: {
    caption: 'Beautiful mountain vista',
    generated_by: 'Cosmic AI'
  }
})

console.log(imageResponse.media.url)
console.log(imageResponse.media.imgix_url)

Response Example

{
  "media": {
    "id": "65f3a2c8853cca45f4c9fd96",
    "name": "c20391e0-b8a4-11e6-8836-fbdfd6956b31-mountain-sunset.png",
    "original_name": "mountain-sunset.png",
    "size": 457307,
    "folder": "ai-generated",
    "type": "image/png",
    "bucket": "5839c67f0d3201c114000004",
    "created_at": "2024-03-14T15:34:05.054Z",
    "url": "https://cdn.cosmicjs.com/c20391e0-b8a4-11e6-8836-fbdfd6956b31-mountain-sunset.png",
    "imgix_url": "https://imgix.cosmicjs.com/c20391e0-b8a4-11e6-8836-fbdfd6956b31-mountain-sunset.png",
    "alt_text": "AI-generated mountain landscape at sunset",
    "metadata": {
      "caption": "Beautiful mountain vista",
      "generated_by": "Cosmic AI"
    }
  },
  "revised_prompt": "A serene mountain landscape at sunset with golden light illuminating the peaks, reflecting in a calm lake below, and wispy clouds catching the last rays of sunlight."
}

Available Models

Cosmic supports a variety of AI models from Anthropic, Google Gemini, and OpenAI for both text and image generation.

Text Generation Models

Anthropic Claude Models

ModelAPI Model IDDescription
Claude Opus 4.5claude-opus-4-5-20251101Latest flagship model with improved performance
Claude Opus 4.1claude-opus-4-1-20250805Most powerful and capable model
Claude Opus 4claude-opus-4-20250514Previous flagship model
Claude Sonnet 4.5claude-sonnet-4-5-20250929High-performance model (recommended)
Claude Sonnet 4claude-sonnet-4-20250514High-performance model with exceptional reasoning
Claude Haiku 3.5claude-3-5-haiku-20241022Fastest model for simple tasks

Google Gemini Models

ModelAPI Model IDDescription
Gemini 3 Pro 🍌gemini-3-pro-previewGoogle's most intelligent model with state-of-the-art reasoning, built for agentic workflows
Gemini 3 Pro Image 🍌gemini-3-pro-image-previewNative image generation with contextual understanding, supports up to 4K images

OpenAI GPT Models

ModelAPI Model IDDescription
GPT-5.2gpt-5.2Latest GPT-5 model with improved performance
GPT-5gpt-5OpenAI's most advanced multimodal model
GPT-5 Minigpt-5-miniCost-effective GPT-5 variant
GPT-5 Nanogpt-5-nanoUltra-fast and cost-effective for simple tasks
GPT-4.1gpt-4.1Enhanced coding and reasoning capabilities
GPT-4ogpt-4oFlagship multimodal model
o1o1Advanced reasoning model for complex problems
o3o3Latest reasoning model with improved performance

Text Generation Model Selection

By default, Cosmic uses Claude Sonnet 4.5 for text generation. You can specify a different model by including the model parameter in your request:

// Using Claude
const response = await cosmic.ai.generateText({
  prompt: 'Write a product description',
  model: 'claude-opus-4-5-20251101', // Optional: specify model
  max_tokens: 500
})

// Using Gemini for agentic workflows
const geminiResponse = await cosmic.ai.generateText({
  prompt: 'Analyze this content and suggest improvements',
  model: 'gemini-3-pro-preview', // Use Gemini 3 Pro
  max_tokens: 500
})

Or using cURL:

# Using Claude
curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/text \
  -d '{"prompt":"Write a product description","model":"claude-opus-4-5-20251101","max_tokens":500}' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer {BUCKET_WRITE_KEY}"

# Using Gemini
curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/text \
  -d '{"prompt":"Analyze this content and suggest improvements","model":"gemini-3-pro-preview","max_tokens":500}' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer {BUCKET_WRITE_KEY}"

Image Generation Models

OpenAI DALL-E Models

ModelAPI Model IDDescription
DALL-E 3dall-e-3Latest image generation model (recommended)

Google Gemini Image Models

ModelAPI Model IDDescriptionSupported Sizes
Gemini 3 Pro Image 🍌gemini-3-pro-image-previewNative image generation with contextual understanding1024x1024, 2048x2048, 4096x4096

Image Generation Model Selection

By default, Cosmic uses DALL-E 3 for image generation. You can explicitly specify the model by including the model parameter in your request.

Gemini 3 Pro Image supports reference images for contextual generation. You can provide URLs to existing images, and Gemini will analyze their style, composition, and content to inform the generated image. This is perfect for:

  • Maintaining consistent visual styles across generated images
  • Creating variations based on existing artwork
  • Applying the aesthetic of one image to a new scene
  • Combining elements from multiple reference images
// Using DALL-E 3
const dalleResponse = await cosmic.ai.generateImage({
  prompt: 'A futuristic cityscape at night',
  model: 'dall-e-3', // Optional: defaults to dall-e-3
  size: '1792x1024',
  quality: 'hd'
})

// Using Gemini 3 Pro Image for 4K generation
const geminiResponse = await cosmic.ai.generateImage({
  prompt: 'A futuristic cityscape at night with neon lights',
  model: 'gemini-3-pro-image-preview', // Use Gemini for higher resolution
  size: '4096x4096', // 4K image support
  quality: 'hd'
})

// Using Gemini with reference images for style consistency
const styledResponse = await cosmic.ai.generateImage({
  prompt: 'A mountain landscape in the same artistic style',
  model: 'gemini-3-pro-image-preview',
  reference_images: [
    'https://cdn.cosmicjs.com/your-style-reference.jpg'
  ],
  size: '2048x2048'
})

Or using cURL:

# Using DALL-E 3
curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/image \
  -d '{"prompt":"A futuristic cityscape at night","model":"dall-e-3","size":"1792x1024","quality":"hd"}' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer {BUCKET_WRITE_KEY}"

# Using Gemini 3 Pro Image
curl https://workers.cosmicjs.com/v3/buckets/${BUCKET_SLUG}/ai/image \
  -d '{"prompt":"A futuristic cityscape at night","model":"gemini-3-pro-image-preview","size":"4096x4096","quality":"hd"}' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer {BUCKET_WRITE_KEY}"

Usage and Limitations

AI capabilities in Cosmic are subject to the following considerations:

  • Rate Limits: AI generation requests may be subject to rate limiting based on your plan.
  • Token Usage: Text generation consumes tokens based on both input and output length.
  • Image Storage: Generated images are stored in your Cosmic Bucket's media library and count toward your storage quota.
  • Content Policy: Generated content must comply with Cosmic's terms of service and content policies.

For more information about AI capabilities and pricing, please refer to the Cosmic pricing page or contact Cosmic support.