ugcinc 4.24.0 → 4.26.0

package/README.md

@@ -281,6 +281,41 @@ status/logs to inspect failures and the returned video for preview.
 Server integrations can also call `submitRemotionCompositionRenderJob` and
 `getRenderJobStatus` with the configured render-worker origin.
 
+### Native text stickers
+
+`submitNativeTextStickerRenderJob` submits the native classic text/emoji renderer
+and returns the normal render job ID. Poll with `getRenderJobStatus`; the completed
+`download_url` is a transparent PNG usable as an image layer in UGC compositions.
+Server calls require `UGC_RENDER_URL`.
+
+```ts
+import {submitNativeTextStickerRenderJob, getRenderJobStatus} from 'ugcinc';
+
+const submitted = await submitNativeTextStickerRenderJob({
+  text: 'Hello World 😭🙏', fontSizePt: 28,
+  canvasWidthPt: 360, canvasHeightPt: 120,
+  containerWidthPt: 320, originPt: [20, 18],
+});
+if (submitted.ok && submitted.data) {
+  const status = await getRenderJobStatus(submitted.data.job_id);
+  // Poll until completed/failed; use status.data.download_url when completed.
+}
+```
+
+The versioned `tiktok-classic-ios-47` profile uses centered white text, a black
+outline, TikTokDisplay-Medium and AppleColorEmoji. All dimensions are **native
+points**, with fixed 3× output: the example produces 1080×360 pixels. Fractional
+coordinates are preserved. Sizes are 11–72pt; canvas/container sides are 1–1365pt;
+text is limited to 2048 UTF-16 code units. `containerHeightPt` limits visible
+lines; omitted or zero means unlimited lines clipped by the canvas. Optional
+`viewFontSizePt` reproduces a native editor whose view font differs from its text
+run; normally omit it. Defaults are 28pt, a 600×180pt canvas, 560pt container width
+and origin `[20,18]`.
+
+Unsupported fallback fonts, bidi, styles and empty paragraphs fail explicitly.
+The profile's recorded native PNG fixtures match exactly; this does not promise
+pixel parity after resizing, browser composition or lossy video encoding.
+
 ## Social reference acquisition
 
 Quick reference:
@@ -419,3 +454,33 @@ const layout = await client.media.measureLayout({url: imageUrl, elements: [
 Masks for either tool are `{width, height, counts}` matching the full display-oriented image dimensions. `counts` is **row-major** binary run-length encoding, alternating background/foreground starting with background; only the first count may be zero. Runs sum to width×height; maximum 100,000 runs total per request. This is not COCO's column-major encoding. Mask pixel centers determine centroids; each included pixel contributes one square pixel of area, regardless of source alpha.
 
 Both tools accept single-frame PNG (up to 8-bit channels), JPEG and WebP, at most 4096 pixels per side and the shared 100MiB download limit. Embedded ICC profiles convert to sRGB using relative-colorimetric intent; untagged RGB/grayscale assumes sRGB. Unsupported/invalid profiles, untagged CMYK, unsupported bit depth/mode, animation, mismatched masks and out-of-bounds geometry fail explicitly. No resizing precedes measurement. Results include source byte hash, color/coordinate policies, a bounded annotated preview and JSON manifest. No model or hosted inference is used.
+
+### Match text style
+
+Quick reference: `client.media.matchTextStyle({url, box, text?})`; agent tool `match_text_style`. `POST /media/analysis/match-text-style` submits the same authenticated analysis-job flow. Poll `getMediaAnalysis` if the SDK returns a pending/processing job.
+
+```typescript
+const match = await client.media.matchTextStyle({
+  url: referenceImageUrl,
+  box: {x: 20, y: 30, width: 700, height: 200},
+  text: 'Build better habits\nSleep well tonight', // optional; preserves intended line breaks
+});
+if (match.ok && match.data.result?.operation === 'match_text_style') {
+  const candidate = match.data.result.candidates[0];
+  if (candidate) {
+    // candidate.element uses original source coordinates.
+    // candidate.previewConfig is a complete crop-sized ImageEditorNodeConfig.
+    const rendered = await submitImageRenderJob({
+      config: candidate.previewConfig, imageUrls: {}, textValues: {},
+    });
+  }
+}
+```
+
+The existing `submitImageRenderJob` server SDK function requires your configured `UGC_RENDER_URL`; matching itself uses the authenticated public API. Returned `surface: 'image-editor-element'` settings use the real `font`, `outlineWidth`, `textAlign` and positioning properties, with a compatible `previewConfig` ready for the supported image renderer. `element` coordinates refer to the source image; preview-config coordinates refer to the selected crop. Do not mix these coordinate spaces.
+
+Inputs: HTTPS image URL and integer display-oriented pixel `box` with a small plain-background margin around one text block. Crop width16–1536, height16–512. Optional exact `text` supports 1–160 printable ASCII characters and up to four lines. Without text, local English OCR supplies the text and line breaks; unreadable/unsupported recognition returns `status: 'unavailable'` with a reason. Source-image size/type/color constraints match color/layout analysis. Transparency is composited over white for fitting.
+
+Fitting runs locally through the installed UGC ImageEditorComposition, searching the supported TikTok Sans, SF Pro and Arial-stack choices, weight, size, spacing, line height, alignment and outline. Fill/background/outline colors are estimated from the crop. Arial may use a system fallback; original font identity is always `unverified`. No custom font upload, gradients, perspective, mixed styles, emoji or shadow setting is inferred. Busy borders, blank crops and clipped foreground return explicit unavailable results. These checks do not prove that every remaining crop is suitable: inspect residuals and preview.
+
+Returns up to three candidates, renderable settings, `maskIoU`, `foregroundMae` (mean absolute RGB error on the union of reference/rendered ink, scaled0–1), and an owned reference/render/difference preview plus JSON manifest. `quality: 'close'` means IoU>=0.9 and foreground MAE<=0.1; otherwise `approximate`. These are image-fit measures, not font-recognition probabilities or content-quality scores. Single-line alignment/padding cannot be uniquely recovered; returned geometry reproduces visible positioning. Render count, installed UGC version and bundled font hashes are included. Search is capped at320 renders and a480-second search budget within existing job limits; resource failures are explicit failed jobs. The renderer bundle is reused unchanged, with no hosted inference or new font downloads.

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { AutomationsClient } from './automations';
 export { MediaClient } from './media';
 export { CommentsClient } from './comments';
 export { BillingClient } from './billing';
-export { submitImageRenderJob, submitVideoRenderJob, getRenderJobStatus, submitDeduplicationJob, submitSceneSplitJob, submitScreenshotAnimationRenderJob, submitRemotionCompositionRenderJob, submitAutoCaptionRenderJob, submitInstagramDmRenderJob, submitIMessageDmRenderJob, } from './render';
+export { submitImageRenderJob, submitVideoRenderJob, getRenderJobStatus, submitDeduplicationJob, submitSceneSplitJob, submitScreenshotAnimationRenderJob, submitRemotionCompositionRenderJob, submitNativeTextStickerRenderJob, nativeTextStickerSchema, submitAutoCaptionRenderJob, submitInstagramDmRenderJob, submitIMessageDmRenderJob, } from './render';
 export { remotionCompositionSchema, remotionCompositionNodeSchema, remotionCompositionPortSchema, REMOTION_COMPOSITION_IMPORTS, parseRemotionPropsJson } from './render/types/remotion-composition';
 export type { RemotionCompositionInput } from './render/types/remotion-composition';
 export type { RemotionCompositionNodeConfig } from './automations/nodes/remotion-composition';
@@ -36,7 +36,7 @@ export type { Org, ApiKey, DeleteApiKeyParams, EditApiKeyParams, IntegrationKey,
 export type { UserMedia, MediaUse, SocialAudio, Media, GetMediaParams, GetSocialAudioParams, UploadMediaParams, UploadMediaResponse, MediaTagUpdate, UpdateMediaTagsParams, MediaTagUpdateResult, UpdateMediaTagsResponse, UpdateMediaTagParams, UpdateMediaNameParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, ImportTextParams, ImportTextResponse, CreateMediaFromUrlParams, GetMediaUseParams, GetMediaUseResponse, FilterMediaParams, FilterMediaResponse, PfpSearchParams, PfpSearchResponse, PfpCandidate, ImageSearchParams, ImageSearchResult, ImageSearchResponse, ImageSearchVideoFormat, } from './media';
 export type { CommentStatus, Comment, CreateCommentParams, CreateCommentResponse, GetCommentsParams, } from './comments';
 export type { BillingInfo, PortalUrlResponse, CancelAccountParams, CancelAccountResponse, ReactivateAccountParams, ReactivateAccountResponse, CancelSubscriptionResponse, RequestReplacementParams, RequestReplacementResponse, RequestRefundParams, RequestRefundResponse, BillingRequestInfo, PortalParams, } from './billing';
-export type { RenderJobResponse, RenderJobStatus, SubmitImageRenderJobParams, SubmitVideoRenderJobParams, SubmitScreenshotAnimationRenderJobParams, SubmitAutoCaptionRenderJobParams, SubmitSceneSplitJobParams, SceneSplitDetectorConfig, SubmitInstagramDmRenderJobParams, SubmitIMessageDmRenderJobParams, IgDmMessage, ImDmMessage, RenderVideoEditorConfig, } from './render';
+export type { RenderJobResponse, RenderJobStatus, SubmitImageRenderJobParams, NativeTextStickerInput, SubmitVideoRenderJobParams, SubmitScreenshotAnimationRenderJobParams, SubmitAutoCaptionRenderJobParams, SubmitSceneSplitJobParams, SceneSplitDetectorConfig, SubmitInstagramDmRenderJobParams, SubmitIMessageDmRenderJobParams, IgDmMessage, ImDmMessage, RenderVideoEditorConfig, } from './render';
 export type { VideoEditorNodeConfig, VideoEditorChannel, VideoEditorSegment, VideoEditorVideoSegment, VideoEditorAudioSegment, VideoEditorImageSegment, VideoEditorTextSegment, VideoEditorImageSequenceSegment, VideoEditorVideoSequenceSegment, TimeValue, TimeMode, SegmentTimelinePosition, DeduplicationLevel, DeduplicationInput, ImageEditorElement, DimensionPresetKey, } from './render/types';
 export type { ImageEditorNodeConfig, ImageComposerNodeConfig, ImageComposerRenderInput } from './automations/nodes/image-composer';
 export { prepareImageComposerInput } from './automations/nodes/image-composer';
@@ -86,5 +86,5 @@ export type { SuccessResponse, ErrorResponse, ApiResponse, } from './types';
 export type { CropBoundary, CropAxisConfig, DynamicCropConfig, BorderRadiusConfig, VerticalAnchor, HorizontalAnchor, HorizontalSelfAnchor, VerticalSelfAnchor, RelativePositionConfigX, RelativePositionConfigY, } from './render/types';
 export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
 export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';
-export type { SampleColorsParams, MeasureLayoutParams, SampleColorsResult, MeasureLayoutResult, TranscribeAudioParams, MeasureAudioLevelsParams, AudioTranscriptResult, AudioLevelsResult, ReadImageTextParams, ReadVideoTextParams, ImageTextResult, VideoTextResult, ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";
-export { sampleColorsSchema, measureLayoutSchema, sampleColorsResultSchema, measureLayoutResultSchema, binaryMaskSchema, transcribeAudioSchema, measureAudioLevelsSchema, audioTranscriptResultSchema, audioLevelsResultSchema, readImageTextSchema, readVideoTextSchema, imageTextResultSchema, videoTextResultSchema, extractFramesSchema, detectScenesSchema, mediaAnalysisStatusSchema, mediaAnalysisResultSchema } from "./media-analysis";
+export type { MatchTextStyleParams, MatchTextStyleResult, SampleColorsParams, MeasureLayoutParams, SampleColorsResult, MeasureLayoutResult, TranscribeAudioParams, MeasureAudioLevelsParams, AudioTranscriptResult, AudioLevelsResult, ReadImageTextParams, ReadVideoTextParams, ImageTextResult, VideoTextResult, ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";
+export { matchTextStyleSchema, matchTextStyleResultSchema, sampleColorsSchema, measureLayoutSchema, sampleColorsResultSchema, measureLayoutResultSchema, binaryMaskSchema, transcribeAudioSchema, measureAudioLevelsSchema, audioTranscriptResultSchema, audioLevelsResultSchema, readImageTextSchema, readVideoTextSchema, imageTextResultSchema, videoTextResultSchema, extractFramesSchema, detectScenesSchema, mediaAnalysisStatusSchema, mediaAnalysisResultSchema } from "./media-analysis";

package/dist/index.js

@@ -5,9 +5,9 @@
  * Official TypeScript/JavaScript client for the UGC Inc API
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasMissingTriggerError = exports.getPortErrorsForNode = exports.getErrorNodeIds = exports.validateWorkflow = exports.getCapturedNodes = exports.getNodesDownstreamOfSet = exports.getDownstreamNodes = exports.checkCrossContextViolation = exports.getForEachContext = exports.getConnectedSource = exports.cleanupStaleConnections = exports.removeNodeConnections = exports.removeConnection = exports.addConnection = exports.deriveConnections = exports.createNode = exports.getOutputSchema = exports.getNodeByType = exports.getAllNodes = exports.getInputPreviewValue = exports.computeAllNodePortsWithPreviews = exports.computeAllNodePorts = exports.computePortsWithPreviews = exports.computePortsForNode = exports.areTypesCompatible = exports.parseRemotionPropsJson = exports.REMOTION_COMPOSITION_IMPORTS = exports.remotionCompositionPortSchema = exports.remotionCompositionNodeSchema = exports.remotionCompositionSchema = exports.submitIMessageDmRenderJob = exports.submitInstagramDmRenderJob = exports.submitAutoCaptionRenderJob = exports.submitRemotionCompositionRenderJob = exports.submitScreenshotAnimationRenderJob = exports.submitSceneSplitJob = exports.submitDeduplicationJob = exports.getRenderJobStatus = exports.submitVideoRenderJob = exports.submitImageRenderJob = exports.BillingClient = exports.CommentsClient = exports.MediaClient = exports.AutomationsClient = exports.OrganizationClient = exports.StatsClient = exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
-exports.parseOpenAPIOutputPath = exports.parseOpenAPIInputs = exports.mapOpenAPIType = exports.nodeConfigToCaptionStyle = exports.HttpMethods = exports.prepareImageComposerInput = exports.substituteVariables = exports.processTemplate = exports.extractTemplateVariables = exports.PortIdSchema = exports.normalizeToPortId = exports.portIdToTitle = exports.isValidPortId = exports.portId = exports.selectFromPool = exports.getModelDurations = exports.getModelAspectRatios = exports.ALL_VIDEO_MODELS = exports.getAvailableInputModes = exports.hasReferenceVariant = exports.getReferenceModelId = exports.hasFirstLastFrameVariant = exports.getFirstLastFrameModelId = exports.hasImageToVideoVariant = exports.getImageToVideoModelId = exports.isImageToVideoModel = exports.IMAGE_ASPECT_RATIOS = exports.ALL_IMAGE_MODELS = exports.getEditModelId = exports.isEditModel = exports.getCapturedSourceNodeTypes = exports.getFlowControlNodeTypes = exports.getAllNodeDefinitions = exports.getNodeDefinition = exports.isPortType = exports.formatPortType = exports.isAsyncExecutor = exports.internalNodeTypes = exports.nodeDefinitions = exports.extractWorkflowConfig = exports.generateNodeName = exports.shuffleNodePreview = exports.getPreviewValue = exports.removePreviewForConnection = exports.updatePreviewMapForConnection = exports.computePreviewMap = exports.computeAllNodePreviews = exports.resolveNodePreview = exports.getWorkflowOutputSchema = exports.hasMissingTerminalError = void 0;
-exports.mediaAnalysisResultSchema = exports.mediaAnalysisStatusSchema = exports.detectScenesSchema = exports.extractFramesSchema = exports.videoTextResultSchema = exports.imageTextResultSchema = exports.readVideoTextSchema = exports.readImageTextSchema = exports.audioLevelsResultSchema = exports.audioTranscriptResultSchema = exports.measureAudioLevelsSchema = exports.transcribeAudioSchema = exports.binaryMaskSchema = exports.measureLayoutResultSchema = exports.sampleColorsResultSchema = exports.measureLayoutSchema = exports.sampleColorsSchema = exports.prepareVideoComposerInput = exports.formatDateTag = exports.outputFieldsToZod = exports.outputFieldToZod = exports.LLMProviders = exports.applyLogicOperator = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToString = exports.indexExpressionToIndexes = exports.resolveUnknownPath = exports.getOutputTypeFromCategory = void 0;
+exports.getErrorNodeIds = exports.validateWorkflow = exports.getCapturedNodes = exports.getNodesDownstreamOfSet = exports.getDownstreamNodes = exports.checkCrossContextViolation = exports.getForEachContext = exports.getConnectedSource = exports.cleanupStaleConnections = exports.removeNodeConnections = exports.removeConnection = exports.addConnection = exports.deriveConnections = exports.createNode = exports.getOutputSchema = exports.getNodeByType = exports.getAllNodes = exports.getInputPreviewValue = exports.computeAllNodePortsWithPreviews = exports.computeAllNodePorts = exports.computePortsWithPreviews = exports.computePortsForNode = exports.areTypesCompatible = exports.parseRemotionPropsJson = exports.REMOTION_COMPOSITION_IMPORTS = exports.remotionCompositionPortSchema = exports.remotionCompositionNodeSchema = exports.remotionCompositionSchema = exports.submitIMessageDmRenderJob = exports.submitInstagramDmRenderJob = exports.submitAutoCaptionRenderJob = exports.nativeTextStickerSchema = exports.submitNativeTextStickerRenderJob = exports.submitRemotionCompositionRenderJob = exports.submitScreenshotAnimationRenderJob = exports.submitSceneSplitJob = exports.submitDeduplicationJob = exports.getRenderJobStatus = exports.submitVideoRenderJob = exports.submitImageRenderJob = exports.BillingClient = exports.CommentsClient = exports.MediaClient = exports.AutomationsClient = exports.OrganizationClient = exports.StatsClient = exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
+exports.mapOpenAPIType = exports.nodeConfigToCaptionStyle = exports.HttpMethods = exports.prepareImageComposerInput = exports.substituteVariables = exports.processTemplate = exports.extractTemplateVariables = exports.PortIdSchema = exports.normalizeToPortId = exports.portIdToTitle = exports.isValidPortId = exports.portId = exports.selectFromPool = exports.getModelDurations = exports.getModelAspectRatios = exports.ALL_VIDEO_MODELS = exports.getAvailableInputModes = exports.hasReferenceVariant = exports.getReferenceModelId = exports.hasFirstLastFrameVariant = exports.getFirstLastFrameModelId = exports.hasImageToVideoVariant = exports.getImageToVideoModelId = exports.isImageToVideoModel = exports.IMAGE_ASPECT_RATIOS = exports.ALL_IMAGE_MODELS = exports.getEditModelId = exports.isEditModel = exports.getCapturedSourceNodeTypes = exports.getFlowControlNodeTypes = exports.getAllNodeDefinitions = exports.getNodeDefinition = exports.isPortType = exports.formatPortType = exports.isAsyncExecutor = exports.internalNodeTypes = exports.nodeDefinitions = exports.extractWorkflowConfig = exports.generateNodeName = exports.shuffleNodePreview = exports.getPreviewValue = exports.removePreviewForConnection = exports.updatePreviewMapForConnection = exports.computePreviewMap = exports.computeAllNodePreviews = exports.resolveNodePreview = exports.getWorkflowOutputSchema = exports.hasMissingTerminalError = exports.hasMissingTriggerError = exports.getPortErrorsForNode = void 0;
+exports.mediaAnalysisResultSchema = exports.mediaAnalysisStatusSchema = exports.detectScenesSchema = exports.extractFramesSchema = exports.videoTextResultSchema = exports.imageTextResultSchema = exports.readVideoTextSchema = exports.readImageTextSchema = exports.audioLevelsResultSchema = exports.audioTranscriptResultSchema = exports.measureAudioLevelsSchema = exports.transcribeAudioSchema = exports.binaryMaskSchema = exports.measureLayoutResultSchema = exports.sampleColorsResultSchema = exports.measureLayoutSchema = exports.sampleColorsSchema = exports.matchTextStyleResultSchema = exports.matchTextStyleSchema = exports.prepareVideoComposerInput = exports.formatDateTag = exports.outputFieldsToZod = exports.outputFieldToZod = exports.LLMProviders = exports.applyLogicOperator = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToString = exports.indexExpressionToIndexes = exports.resolveUnknownPath = exports.getOutputTypeFromCategory = exports.parseOpenAPIOutputPath = exports.parseOpenAPIInputs = void 0;
 // =============================================================================
 // Client Exports
 // =============================================================================
@@ -40,6 +40,8 @@ Object.defineProperty(exports, "submitDeduplicationJob", { enumerable: true, get
 Object.defineProperty(exports, "submitSceneSplitJob", { enumerable: true, get: function () { return render_1.submitSceneSplitJob; } });
 Object.defineProperty(exports, "submitScreenshotAnimationRenderJob", { enumerable: true, get: function () { return render_1.submitScreenshotAnimationRenderJob; } });
 Object.defineProperty(exports, "submitRemotionCompositionRenderJob", { enumerable: true, get: function () { return render_1.submitRemotionCompositionRenderJob; } });
+Object.defineProperty(exports, "submitNativeTextStickerRenderJob", { enumerable: true, get: function () { return render_1.submitNativeTextStickerRenderJob; } });
+Object.defineProperty(exports, "nativeTextStickerSchema", { enumerable: true, get: function () { return render_1.nativeTextStickerSchema; } });
 Object.defineProperty(exports, "submitAutoCaptionRenderJob", { enumerable: true, get: function () { return render_1.submitAutoCaptionRenderJob; } });
 Object.defineProperty(exports, "submitInstagramDmRenderJob", { enumerable: true, get: function () { return render_1.submitInstagramDmRenderJob; } });
 Object.defineProperty(exports, "submitIMessageDmRenderJob", { enumerable: true, get: function () { return render_1.submitIMessageDmRenderJob; } });
@@ -175,6 +177,8 @@ Object.defineProperty(exports, "formatDateTag", { enumerable: true, get: functio
 var video_composer_1 = require("./automations/nodes/video-composer");
 Object.defineProperty(exports, "prepareVideoComposerInput", { enumerable: true, get: function () { return video_composer_1.prepareVideoComposerInput; } });
 var media_analysis_1 = require("./media-analysis");
+Object.defineProperty(exports, "matchTextStyleSchema", { enumerable: true, get: function () { return media_analysis_1.matchTextStyleSchema; } });
+Object.defineProperty(exports, "matchTextStyleResultSchema", { enumerable: true, get: function () { return media_analysis_1.matchTextStyleResultSchema; } });
 Object.defineProperty(exports, "sampleColorsSchema", { enumerable: true, get: function () { return media_analysis_1.sampleColorsSchema; } });
 Object.defineProperty(exports, "measureLayoutSchema", { enumerable: true, get: function () { return media_analysis_1.measureLayoutSchema; } });
 Object.defineProperty(exports, "sampleColorsResultSchema", { enumerable: true, get: function () { return media_analysis_1.sampleColorsResultSchema; } });