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.

The data request payload will need to be sent in JSON format with the Content-Type: application/json header set. A bucket write key is required for all AI operations.

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

Event-based: Extends EventEmitter with these events:
- text: New text fragments
- usage: Token usage information
- end: Final data when stream completes
- error: Stream errors
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.

The data request payload will need to be sent in JSON format with the Content-Type: application/json header set.

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. Defaults to dall-e-3. Currently, only DALL-E 3 is supported.
Name
size
Type
string
Description
The size of the generated image. Options: 1024x1024, 1792x1024, or 1024x1792. 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.
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 and OpenAI for both text and image generation.

Text Generation Models

Anthropic Claude Models

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

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:

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

Or using cURL:

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}"

Image Generation Models

OpenAI DALL-E Models

Model	API Model ID	Description
DALL-E 3	`dall-e-3`	Latest image generation model (recommended)

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:

const imageResponse = await cosmic.ai.generateImage({
  prompt: 'A futuristic cityscape at night',
  model: 'dall-e-3', // Optional: defaults to dall-e-3
  size: '1792x1024',
  quality: 'hd'
})

Or using cURL:

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}"

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.