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
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") andcontent(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 toclaude-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
promptormessages.
- 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 fragmentsusage: Token usage informationend: Final data when stream completeserror: Stream errors
-
AsyncIterator: For for-await loops, with chunk objects containing:
text: Text fragmentsusage: Token usage informationend: Set to true for the final chunkerror: Error information
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. Options:
dall-e-3(default) orgemini-3-pro-image-preview. Defaults todall-e-3.
- Name
size- Type
- string
- Description
The size of the generated image. For DALL-E 3:
1024x1024,1792x1024, or1024x1792. For Gemini 3 Pro Image:1024x1024,2048x2048, or4096x4096. Defaults to1024x1024.
- Name
quality- Type
- string
- Description
The quality of the generated image. Options:
standardorhd. Defaults tostandard. 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-previewmodel.
- 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
| 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 |
Google Gemini Models
| Model | API Model ID | Description |
|---|---|---|
| Gemini 3 Pro 🍌 | gemini-3-pro-preview | Google's most intelligent model with state-of-the-art reasoning, built for agentic workflows |
| Gemini 3 Pro Image 🍌 | gemini-3-pro-image-preview | Native image generation with contextual understanding, supports up to 4K images |
OpenAI GPT Models
| Model | API Model ID | Description |
|---|---|---|
| GPT-5.2 | gpt-5.2 | Latest GPT-5 model with improved performance |
| GPT-5 | gpt-5 | OpenAI's most advanced multimodal model |
| GPT-5 Mini | gpt-5-mini | Cost-effective GPT-5 variant |
| GPT-5 Nano | gpt-5-nano | Ultra-fast and cost-effective for simple tasks |
| GPT-4.1 | gpt-4.1 | Enhanced coding and reasoning capabilities |
| GPT-4o | gpt-4o | Flagship multimodal model |
| o1 | o1 | Advanced reasoning model for complex problems |
| o3 | o3 | Latest 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
| Model | API Model ID | Description |
|---|---|---|
| DALL-E 3 | dall-e-3 | Latest image generation model (recommended) |
Google Gemini Image Models
| Model | API Model ID | Description | Supported Sizes |
|---|---|---|---|
| Gemini 3 Pro Image 🍌 | gemini-3-pro-image-preview | Native image generation with contextual understanding | 1024x1024, 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.