@cartanova/qgrid-ai-sdk 2.9.4 → 2.9.6

package/README.ko.md

@@ -211,7 +211,7 @@ const { text } = await generateText({
 | `serviceTier` | `string` | OpenAI 전용 | OpenAI/codex service tier |
 | `timeoutMs` | 양의 정수, 최대 `1_800_000` | Anthropic 전용 | 서버의 Claude Code 프로세스 제한시간(ms). SDK의 non-stream HTTP 제한은 이 값보다 60초 길게 설정. 기본값은 240초 |
 | `imageGeneration` | `boolean` | OpenAI 전용, non-stream | codex 내장 `image_generation` tool 활성화 ([아래](#image-generation) 참조) |
-| `imageGenerationOptions` | `{ quality?, size? }` | OpenAI 전용 | 이미지 품질/크기 힌트. `quality: "low" \| "medium" \| "high"`, `size: "1024x1024" \| "1024x1536" \| "1536x1024"` (기본: `medium` / `1536x1024`) |
+| `imageGenerationOptions` | `{ quality?, size?, background? }` | OpenAI 전용 | 이미지 생성 옵션. `background: "transparent"`는 전용 경로 사용. 실제 크기·품질은 응답 metadata 확인 ([아래](#image-generation)). |
 | `fallbackModels` | `string[]` | 예약 | 향후 qgrid 서버 fallback routing용 예약 필드. 현재 동작하지 않으며 Claude Code의 Fable refusal fallback과 무관 |
 
 ```typescript
@@ -252,7 +252,7 @@ const { text } = await generateText({
 
 ### Image Generation
 
-OpenAI/codex 경로 전용, `generateText` 전용입니다. 해당 요청에만 codex 내장 `image_generation` tool을 켜고, 결과 이미지를 AI SDK `files`로 받습니다.
+OpenAI/codex 경로 전용, `generateText` 전용입니다. 요청별로 이미지 생성을 활성화하고 결과를 AI SDK `files`로 받습니다. 투명 배경은 Codex 전용 Images 경로를, 그 외에는 내장 `image_generation` 도구를 사용합니다.
 
 ```typescript
 const result = await generateText({
@@ -291,6 +291,12 @@ const result = await generateText({
 - 이미지 생성 요청은 provider 대화 상태를 보관하지 않고 전체 input을 직접 전송합니다.
 - 레퍼런스 이미지는 JSON data URL로 전송됩니다. 큰 사진은 압축하거나 리사이즈해서 전달하세요. 과도하게 큰 base64 입력은 SDK가 거부하며, 사진에는 WebP/JPEG를 권장합니다.
 - 이미지 비용은 `gpt-image-2` 공개 단가표 기반 **추정치**로 request log의 `image_cost_usd`에 별도 기록됩니다 (codex가 정확한 이미지 tool 사용량을 노출하지 않음).
+- `imageGenerationOptions.background`는 `"auto" | "opaque" | "transparent"`를 지원합니다. `"transparent"` 요청만 기존 ChatGPT 구독 토큰으로 Codex 전용 `images/generations` 또는 `images/edits` 경로를 사용합니다. 나머지는 기존 Responses 도구 경로를 유지합니다. 투명 경로는 텍스트 모델 없이 `gpt-image-2`를 직접 실행하며, tools·structured output은 지원하지 않습니다. 레퍼런스는 최대 5장입니다. 불투명·완전 빈 이미지·손상된 PNG는 오류로 처리하고, 별도 배경 제거로 대체하지 않습니다.
+- 실제 출력 정보는 `result.providerMetadata.qgrid.imageGeneration` 배열에 있습니다(`contentIndex`, `model`, `route`, `size`, `quality`, `background`, 이미지 `usage`). `result.content` 파일 파트에도 metadata가 있지만 `result.files[]`에는 없습니다. 실호출에서 `1024x1024`/`high` 요청이 `1254x1254`/`medium`으로 반환됐으므로, 요청값을 최종 출력값으로 간주하면 안 됩니다. qgrid는 실제 PNG 크기를 보고하며 리사이즈하지 않습니다.
+- 투명 경로는 텍스트 모델을 실행하지 않아 일반 토큰 usage·비용이 0입니다. 이미지 usage는 별도로 보존하고, `image_cost_usd`는 보고된 토큰과 공개 API 단가로 추정합니다. 알려진 text/image input은 구분하고 불명확한 input은 보수적으로 계산하며, 캐시 할인은 반영하지 않습니다. 구독 청구액을 뜻하지 않습니다.
+- 명시한 이미지 옵션은 이미지 도구 로그의 `requestedOptions`에 기록하며 `pricingAssumption`과 구분합니다. 옵션 생략 시 비용 추정에 쓰는 `1536x1024`/`medium`은 실제 출력 크기·품질의 기본값을 보장하지 않습니다.
+
+투명 생성은 위 `imageGenerationOptions`에 `background: "transparent"`를 추가하고, 프롬프트에도 피사체 밖의 투명 배경을 명시하세요. 크로마키·배경색 지시는 제거해야 합니다. 이 기능이 포함된 서버와 SDK가 모두 필요하며, 저장 시 PNG 알파를 유지하세요. 정확한 최종 크기는 소비 앱의 명시적인 crop/resize 정책으로 처리합니다.
 
 ## Telemetry Logger
 

package/README.md

@@ -220,7 +220,7 @@ const { text } = await generateText({
 | `serviceTier` | `string` | OpenAI only | OpenAI/codex service tier |
 | `timeoutMs` | positive integer, max `1_800_000` | Anthropic only | Server-side Claude Code process timeout in milliseconds. The SDK's non-stream HTTP budget is 60 seconds longer. Defaults to 240 seconds |
 | `imageGeneration` | `boolean` | OpenAI only, non-stream | Enables codex's built-in `image_generation` tool (see [below](#image-generation)) |
-| `imageGenerationOptions` | `{ quality?, size? }` | OpenAI only | Image quality/size hints. `quality: "low" \| "medium" \| "high"`, `size: "1024x1024" \| "1024x1536" \| "1536x1024"` (defaults: `medium` / `1536x1024`) |
+| `imageGenerationOptions` | `{ quality?, size?, background?, outputFormat? }` | OpenAI only | Image controls; `outputFormat` selects PNG/JPEG/WebP on Responses. `background: "transparent"` selects standalone Images (PNG only). Read actual size/quality from response metadata ([below](#image-generation)). |
 | `fallbackModels` | `string[]` | reserved | Reserved for future qgrid server-side fallback routing. Not functional yet and unrelated to Claude Code's Fable refusal fallback |
 
 ```typescript
@@ -261,7 +261,7 @@ const { text } = await generateText({
 
 ### Image Generation
 
-OpenAI/codex route only, `generateText` only. Enables codex's built-in `image_generation` tool for that single request and returns the image through the AI SDK `files`.
+OpenAI/codex route only, `generateText` only. Enables image generation for that single request and returns the image through AI SDK `files`. Transparent backgrounds use standalone Codex Images; other requests use the hosted `image_generation` tool.
 
 ```typescript
 const result = await generateText({
@@ -270,14 +270,16 @@ const result = await generateText({
   providerOptions: {
     qgrid: {
       imageGeneration: true,
-      imageGenerationOptions: { quality: "medium", size: "1536x1024" },
+      imageGenerationOptions: { quality: "medium", size: "1536x1024", outputFormat: "webp" },
     },
   },
 });
 
-const image = result.files[0]; // mediaType: "image/png", base64
+const image = result.files[0]; // mediaType: "image/webp", base64
 ```
 
+Since 2.9.6, `imageGenerationOptions.outputFormat` accepts `"png" | "jpeg" | "webp"`; omission keeps PNG. qgrid preserves the returned image format in `mediaType` rather than converting the image. Save files with the matching extension. Transparent background requests only support PNG and reject JPEG/WebP before generation. `result.files[].mediaType` retains the AI SDK standard `string` type; no qgrid-specific wrapper or type assertion is needed.
+
 Reference images can be passed through normal AI SDK multimodal message parts:
 
 ```typescript
@@ -300,6 +302,36 @@ const result = await generateText({
 - Image-generation requests do not retain provider conversation state. Their full input is sent directly.
 - Reference images are sent as JSON data URLs. Compress or resize large photos before passing them in; oversized base64 inputs are rejected by the SDK. WebP/JPEG is recommended for photos.
 - The image cost is an **estimate** based on the public `gpt-image-2` price table, recorded separately as `image_cost_usd` on the request log (codex does not expose exact image-tool usage).
+- `imageGenerationOptions.background` accepts `"auto" | "opaque" | "transparent"`. Only `"transparent"` uses Codex's standalone `images/generations` or `images/edits` endpoint with the existing ChatGPT subscription token. Other image requests keep the hosted Responses tool. The transparent route runs `gpt-image-2` directly, without a text driver; it rejects tools and structured output. It accepts up to five reference images and preserves PNG bytes. Fully opaque, entirely empty, or invalid PNG results fail explicitly; there is no background-removal fallback.
+- Transparent image output metadata is available in `result.providerMetadata.qgrid.imageGeneration` (an array containing `contentIndex`, `model`, `route`, `size`, `quality`, `background`, and optional image `usage`). Per-file metadata also appears on `result.content` file parts, not on `result.files[]`. Request options are hints: a live `1024x1024`/`high` request returned `1254x1254`/`medium`. qgrid reports the actual PNG dimensions and does not resize it.
+- On the transparent route, regular token usage/cost is zero because no text driver ran. Image usage is preserved separately and `image_cost_usd` is an API-price estimate from reported usage, with known text/image input splits and conservative pricing for unknown input. It omits cache discounts and is not subscription billing.
+- Explicit image options are recorded as `requestedOptions` in the synthetic image tool log, separately from `pricingAssumption`. When size/quality are omitted, the `1536x1024`/`medium` pricing defaults do not establish actual output dimensions or quality.
+
+Transparent generation example (requires a server and SDK containing this feature):
+
+```typescript
+import { generateText } from "ai";
+import { qgrid, type QgridProviderOptions } from "@cartanova/qgrid-ai-sdk";
+
+const result = await generateText({
+  model: qgrid("openai/gpt-5.5", { projectName: "deti" }),
+  prompt: "An isolated character. Everything outside the character must be transparent, with no backdrop or checkerboard.",
+  providerOptions: {
+    qgrid: {
+      imageGeneration: true,
+      imageGenerationOptions: {
+        background: "transparent",
+        quality: "high",
+        size: "1024x1536",
+      },
+    } satisfies QgridProviderOptions,
+  },
+});
+const png = result.files[0];
+const observed = result.providerMetadata?.qgrid?.imageGeneration;
+```
+
+Remove green-screen or other background instructions when requesting transparency. Preserve the returned PNG alpha when saving; exact final dimensions require an explicit downstream crop/resize policy.
 
 ## Telemetry Logger
 

package/dist/index.d.ts

@@ -66,13 +66,16 @@ type QgridOpenAIProviderOptions = QgridCommonProviderOptions & {
    */
   imageGeneration?: boolean;
   /**
-   * Image generation hint and cost-estimation basis. The image model is fixed
-   * to gpt-image-2; qgrid accepts supported quality/size pairs from OpenAI's
-   * public calculator table.
+   * Image generation controls. The Responses backend selects the image model;
+   * quality/size cost estimates use the GPT Image 2 public calculator table.
    */
   imageGenerationOptions?: {
+    /** Responses output format. Defaults to PNG; transparent output only supports PNG. */
+    outputFormat?: "png" | "jpeg" | "webp";
     quality?: "low" | "medium" | "high";
     size?: "1024x1024" | "1024x1536" | "1536x1024";
+    /** Transparent uses Codex standalone Images and validates PNG alpha. See README for limits. */
+    background?: "auto" | "opaque" | "transparent";
   };
 };
 /** `providerOptions.qgrid` — Anthropic(Claude Code) 모델용. */
@@ -94,6 +97,28 @@ type QgridAnthropicProviderOptions = QgridCommonProviderOptions & {
  */
 type QgridProviderOptions = QgridOpenAIProviderOptions | QgridAnthropicProviderOptions;
 type QgridSupportedModel = "openai/gpt-6-astra" | "openai/gpt-5.6-sol" | "openai/gpt-5.6-terra" | "openai/gpt-5.6-luna" | "openai/gpt-5.5" | "openai/gpt-5.4" | "openai/gpt-5.2" | "openai/gpt-5.4-mini" | "openai/gpt-5.3-codex" | "openai/gpt-5.3-codex-spark" | "anthropic/claude-fable-5-1" | "anthropic/claude-fable-5" | "anthropic/claude-haiku-4-5" | "anthropic/claude-sonnet-4" | "anthropic/claude-sonnet-4-5" | "anthropic/claude-sonnet-4-6" | "anthropic/claude-sonnet-4-7" | "anthropic/claude-sonnet-5" | "anthropic/claude-opus-4" | "anthropic/claude-opus-4-1" | "anthropic/claude-opus-4-5" | "anthropic/claude-opus-4-6" | "anthropic/claude-opus-4-7" | "anthropic/claude-opus-4-8" | "anthropic/claude-opus-5";
+/** Observed image response values. Usage is response-level and appears on the first image only. */
+type QgridImageGenerationMetadata = {
+  route: "codex-images";
+  model: "gpt-image-2";
+  background?: string;
+  quality?: string;
+  size?: string;
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    input_tokens_details?: {
+      image_tokens: number;
+      text_tokens: number;
+      cached_tokens?: number;
+    };
+    output_tokens_details?: {
+      image_tokens: number;
+      text_tokens: number;
+    };
+  };
+};
 type QgridLoggerConfig = {
   /** qgrid 서버 주소. default: process.env.QGRID_URL, 없으면 기본값은 "http://localhost:44900" */
   serverUrl?: string;
@@ -129,4 +154,4 @@ declare function createQgridLogger(config?: QgridLoggerConfig): TelemetrySetting
 declare function qgrid(modelId: QgridOpenAIModel, config?: QgridOpenAIProviderConfig): LanguageModelV3;
 declare function qgrid(modelId: QgridAnthropicModel, config?: QgridAnthropicProviderConfig): LanguageModelV3;
 //#endregion
-export { type QgridAnthropicEffort, type QgridAnthropicModel, type QgridAnthropicProviderConfig, type QgridAnthropicProviderOptions, type QgridLoggerConfig, type QgridOpenAIEffort, type QgridOpenAIModel, type QgridOpenAIProviderConfig, type QgridOpenAIProviderOptions, type QgridProviderConfig, type QgridProviderOptions, type QgridSupportedModel, createQgridLogger, qgrid as default, qgrid };
+export { type QgridAnthropicEffort, type QgridAnthropicModel, type QgridAnthropicProviderConfig, type QgridAnthropicProviderOptions, type QgridImageGenerationMetadata, type QgridLoggerConfig, type QgridOpenAIEffort, type QgridOpenAIModel, type QgridOpenAIProviderConfig, type QgridOpenAIProviderOptions, type QgridProviderConfig, type QgridProviderOptions, type QgridSupportedModel, createQgridLogger, qgrid as default, qgrid };

package/dist/index.js

@@ -475,22 +475,36 @@ function extractPromptAndHistory(messages, options = {}) {
 					text: extracted.text
 				}]
 			});
-		} else if (msg.role === "assistant") {
-			for (const part of msg.content) if ("text" in part && typeof part.text === "string") history.push({
-				type: "message",
-				role: "assistant",
-				content: [{
-					type: "output_text",
-					text: part.text
-				}]
-			});
-			else if ("toolName" in part && part.type === "tool-call") history.push({
-				type: "function_call",
-				name: part.toolName,
-				arguments: typeof part.input === "string" ? part.input : JSON.stringify(part.input),
-				call_id: part.toolCallId
-			});
-		} else if (msg.role === "tool") {
+		} else if (msg.role === "assistant") for (const part of msg.content) if ("text" in part && typeof part.text === "string") history.push({
+			type: "message",
+			role: "assistant",
+			content: [{
+				type: "output_text",
+				text: part.text
+			}]
+		});
+		else if ("toolName" in part && part.type === "tool-call") history.push({
+			type: "function_call",
+			name: part.toolName,
+			arguments: typeof part.input === "string" ? part.input : JSON.stringify(part.input),
+			call_id: part.toolCallId
+		});
+		else {
+			const url = extractImageUrl(part);
+			if (!url) continue;
+			if (includeImages) {
+				imageUrls.push(url);
+				history.push({
+					type: "message",
+					role: "assistant",
+					content: [{
+						type: "input_image",
+						image_url: url
+					}]
+				});
+			} else droppedImageCount++;
+		}
+		else if (msg.role === "tool") {
 			for (const part of msg.content) if ("toolName" in part && part.type === "tool-result") {
 				const output = part.output;
 				const text = "value" in output ? typeof output.value === "string" ? output.value : JSON.stringify(output.value) : JSON.stringify(output);
@@ -1062,6 +1076,10 @@ async function deriveCacheAffinityKey(modelId, sessionKey) {
 	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 function qgridProviderMetadata(data) {
+	const imageGeneration = data.content?.flatMap((item, contentIndex) => item.type === "image" && item.generation ? [{
+		contentIndex,
+		...item.generation
+	}] : []);
 	return { qgrid: {
 		model: data.model,
 		requestedModel: data.requestedModel ?? data.model,
@@ -1071,7 +1089,8 @@ function qgridProviderMetadata(data) {
 		costUsd: data.costUsd,
 		costSource: data.costSource,
 		cacheCreation5mInputTokens: data.usage.cache_creation_5m_input_tokens ?? null,
-		cacheCreation1hInputTokens: data.usage.cache_creation_1h_input_tokens ?? null
+		cacheCreation1hInputTokens: data.usage.cache_creation_1h_input_tokens ?? null,
+		...imageGeneration?.length ? { imageGeneration } : {}
 	} };
 }
 function getQgridProviderOptions(options) {
@@ -1218,8 +1237,9 @@ function qgrid(modelId, config) {
 				});
 				else if (item.type === "image") content.push({
 					type: "file",
-					mediaType: "image/png",
-					data: item.data
+					mediaType: item.mediaType ?? "image/png",
+					data: item.data,
+					...item.generation ? { providerMetadata: { qgrid: { imageGeneration: item.generation } } } : {}
 				});
 				else if (item.type === "tool-call") content.push({
 					type: "tool-call",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-ai-sdk",
-  "version": "2.9.4",
+  "version": "2.9.6",
   "description": "AI SDK LanguageModelV3 provider for qgrid",
   "repository": {
     "type": "git",