insforge 1.2.10 → 1.4.8

package/docs/core-concepts/ai/sdk.mdx

@@ -1,213 +1,238 @@
----
-title: AI SDK Reference
-description: AI chat completions and image generation with the InsForge SDK
----
-
-import Installation from '/snippets/sdk-installation.mdx';
-
-<Installation />
-
-## chat.completions.create()
-
-Create AI chat completions with streaming support.
-
-### Parameters
-
-- `model` (string, required) - AI model (e.g., 'anthropic/claude-3.5-haiku', 'openai/gpt-4'), call `mcp__insforge__get-backend-metadata` tool to get available models
-- `messages` (array, required) - Array of message objects: `{role: "user"|"system"|"assistant", content: string}`
-- `temperature` (number, optional) - Sampling temperature 0-2
-- `maxTokens` (number, optional) - Max tokens to generate
-- `topP` (number, optional) - Top-p sampling 0-1
-- `stream` (boolean, optional) - Enable streaming mode
-
-### Returns (non-streaming)
-
-```typescript
-{
-  id: string,
-  object: 'chat.completion',
-  created: number,
-  model: string,
-  choices: [{
-    index: number,
-    message: { role: "system"|"user"|"assistant", content: string },
-    finish_reason: string
-  }],
-  usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number }
-}
-```
-
-### Returns (streaming)
-
-```typescript
-AsyncIterableIterator<{
-  id: string;
-  object: 'chat.completion.chunk';
-  choices: [
-    {
-      delta: { content: string };
-      finish_reason: string | null;
-    },
-  ];
-}>;
-```
-
-### Example (non-streaming)
-
-```javascript
-const completion = await insforge.ai.chat.completions.create({
-  model: 'anthropic/claude-3.5-haiku',
-  messages: [
-    {
-      role: 'user',
-      content: [
-        { type: 'text', text: 'What do you see in this image?' },
-        {
-          type: 'image_url',
-          image_url: {
-            url: 'https://example.com/photo.jpg', // or base64: 'data:image/jpeg;base64,...'
-          },
-        },
-      ],
-    },
-  ],
-});
-
-console.log(completion.choices[0].message.content);
-```
-
-### Output (non-streaming)
-
-```json
-{
-  "id": "chatcmpl-1705315200000",
-  "object": "chat.completion",
-  "created": 1705315200,
-  "model": "anthropic/claude-3.5-haiku",
-  "choices": [
-    {
-      "index": 0,
-      "message": {
-        "role": "assistant",
-        "content": "The capital of France is Paris."
-      },
-      "finish_reason": "stop"
-    }
-  ],
-  "usage": {
-    "prompt_tokens": 15,
-    "completion_tokens": 8,
-    "total_tokens": 23
-  }
-}
-```
-
-### Example (streaming)
-
-```javascript
-const stream = await insforge.ai.chat.completions.create({
-  model: 'openai/gpt-4',
-  messages: [{ role: 'user', content: 'Tell me a story' }],
-  stream: true,
-});
-
-for await (const chunk of stream) {
-  if (chunk.choices[0]?.delta?.content) {
-    process.stdout.write(chunk.choices[0].delta.content);
-  }
-}
-```
-
-### Output (streaming)
-
-```json
-{
-  "id": "chatcmpl-1705315200000",
-  "object": "chat.completion.chunk",
-  "choices": [
-    {
-      "delta": { "content": "Once upon" },
-      "finish_reason": null
-    }
-  ]
-}
-```
-
----
-
-## images.generate()
-
-Generate images using AI models.
-
-### Parameters
-
-- `model` (string, required) - Image model (e.g., 'google/gemini-2.5-flash-image-preview')
-- `prompt` (string, required) - Text description of image
-- `images` (array, optional) - Input images for image-to-image (url or base64)
-- `width` (number, optional) - Image width in pixels
-- `height` (number, optional) - Image height in pixels
-- `size` (string, optional) - Predefined size ('1024x1024', '512x512')
-- `numImages` (number, optional) - Number of images to generate
-- `quality` ('standard' | 'hd', optional) - Image quality
-- `style` ('vivid' | 'natural', optional) - Image style
-
-### Returns
-
-```typescript
-{
-  created: number,
-  data: Array<{
-    b64_json?: string,  // Base64 encoded image
-    content?: string    // Text response from model
-  }>,
-  usage?: {
-    total_tokens: number,
-    input_tokens: number,
-    output_tokens: number
-  }
-}
-```
-
-### Example
-
-```javascript
-const response = await insforge.ai.images.generate({
-  model: 'google/gemini-2.5-flash-image-preview',
-  prompt: 'A serene mountain landscape at sunset',
-  size: '1024x1024',
-});
-
-// Get base64 image and upload to storage
-const base64Image = response.data[0].b64_json;
-const buffer = Buffer.from(base64Image, 'base64');
-const blob = new Blob([buffer], { type: 'image/png' });
-
-const { data: uploadData } = await insforge.storage.from('ai-images').uploadAuto(blob);
-
-// Save URL to database
-await insforge.database.from('generated_images').insert([
-  {
-    prompt: 'A serene mountain landscape',
-    image_url: uploadData.url,
-  },
-]);
-```
-
-### Output
-
-```json
-{
-  "created": 1705315200,
-  "data": [
-    {
-      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
-      "content": "A beautiful mountain landscape at sunset with orange and purple hues."
-    }
-  ],
-  "usage": {
-    "total_tokens": 150,
-    "input_tokens": 20,
-    "output_tokens": 130
-  }
-}
-```
+---
+title: AI SDK Reference
+description: AI chat completions and image generation with the InsForge SDK
+---
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## chat.completions.create()
+
+Create AI chat completions with streaming support.
+
+### Parameters
+
+- `model` (string, required) - AI model (e.g., 'anthropic/claude-3.5-haiku', 'openai/gpt-4'), call `mcp__insforge__get-backend-metadata` tool to get available models
+- `messages` (array, required) - Array of message objects with text, image, or audio content
+- `temperature` (number, optional) - Sampling temperature 0-2
+- `maxTokens` (number, optional) - Max tokens to generate
+- `topP` (number, optional) - Top-p sampling 0-1
+- `stream` (boolean, optional) - Enable streaming mode
+
+### Returns (non-streaming)
+
+```typescript
+{
+  id: string,
+  object: 'chat.completion',
+  created: number,
+  model: string,
+  choices: [{
+    index: number,
+    message: { role: "system"|"user"|"assistant", content: string },
+    finish_reason: string
+  }],
+  usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number }
+}
+```
+
+### Returns (streaming)
+
+```typescript
+AsyncIterableIterator<{
+  id: string;
+  object: 'chat.completion.chunk';
+  choices: [
+    {
+      delta: { content: string };
+      finish_reason: string | null;
+    },
+  ];
+}>;
+```
+
+### Example (non-streaming)
+
+```javascript
+const completion = await insforge.ai.chat.completions.create({
+  model: 'anthropic/claude-3.5-haiku',
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What do you see in this image?' },
+        {
+          type: 'image_url',
+          image_url: {
+            url: 'https://example.com/photo.jpg', // or base64: 'data:image/jpeg;base64,...'
+          },
+        },
+      ],
+    },
+  ],
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+### Example (with audio)
+
+```javascript
+const completion = await insforge.ai.chat.completions.create({
+  model: 'openai/gpt-4o-audio-preview',
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Transcribe this audio and summarize it' },
+        {
+          type: 'input_audio',
+          input_audio: {
+            data: audioBase64, // base64-encoded audio
+            format: 'wav',     // wav, mp3, aiff, aac, ogg, flac, m4a
+          },
+        },
+      ],
+    },
+  ],
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+### Output (non-streaming)
+
+```json
+{
+  "id": "chatcmpl-1705315200000",
+  "object": "chat.completion",
+  "created": 1705315200,
+  "model": "anthropic/claude-3.5-haiku",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "The capital of France is Paris."
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 15,
+    "completion_tokens": 8,
+    "total_tokens": 23
+  }
+}
+```
+
+### Example (streaming)
+
+```javascript
+const stream = await insforge.ai.chat.completions.create({
+  model: 'openai/gpt-4',
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  if (chunk.choices[0]?.delta?.content) {
+    process.stdout.write(chunk.choices[0].delta.content);
+  }
+}
+```
+
+### Output (streaming)
+
+```json
+{
+  "id": "chatcmpl-1705315200000",
+  "object": "chat.completion.chunk",
+  "choices": [
+    {
+      "delta": { "content": "Once upon" },
+      "finish_reason": null
+    }
+  ]
+}
+```
+
+---
+
+## images.generate()
+
+Generate images using AI models.
+
+### Parameters
+
+- `model` (string, required) - Image model (e.g., 'google/gemini-2.5-flash-image-preview')
+- `prompt` (string, required) - Text description of image
+- `images` (array, optional) - Input images for image-to-image (url or base64)
+- `width` (number, optional) - Image width in pixels
+- `height` (number, optional) - Image height in pixels
+- `size` (string, optional) - Predefined size ('1024x1024', '512x512')
+- `numImages` (number, optional) - Number of images to generate
+- `quality` ('standard' | 'hd', optional) - Image quality
+- `style` ('vivid' | 'natural', optional) - Image style
+
+### Returns
+
+```typescript
+{
+  created: number,
+  data: Array<{
+    b64_json?: string,  // Base64 encoded image
+    content?: string    // Text response from model
+  }>,
+  usage?: {
+    total_tokens: number,
+    input_tokens: number,
+    output_tokens: number
+  }
+}
+```
+
+### Example
+
+```javascript
+const response = await insforge.ai.images.generate({
+  model: 'google/gemini-2.5-flash-image-preview',
+  prompt: 'A serene mountain landscape at sunset',
+  size: '1024x1024',
+});
+
+// Get base64 image and upload to storage
+const base64Image = response.data[0].b64_json;
+const buffer = Buffer.from(base64Image, 'base64');
+const blob = new Blob([buffer], { type: 'image/png' });
+
+const { data: uploadData } = await insforge.storage.from('ai-images').uploadAuto(blob);
+
+// Save URL to database
+await insforge.database.from('generated_images').insert([
+  {
+    prompt: 'A serene mountain landscape',
+    image_url: uploadData.url,
+  },
+]);
+```
+
+### Output
+
+```json
+{
+  "created": 1705315200,
+  "data": [
+    {
+      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
+      "content": "A beautiful mountain landscape at sunset with orange and purple hues."
+    }
+  ],
+  "usage": {
+    "total_tokens": 150,
+    "input_tokens": 20,
+    "output_tokens": 130
+  }
+}
+```