ugcinc 4.14.0 → 4.15.1

package/README.md

@@ -166,6 +166,28 @@ await client.posts.createVideo({
 await client.posts.updatePost({ postId: "post_123", post_tag: "campaign-august" });
 ```
 
+When a post fails, its category is appended to the tag as `fail reason: <fail_category>` (for
+example `campaign-july fail reason: device_error`), so a post list shows why without a status call
+per post. The suffix is removed again when the post is retried.
+
+## Backup Audio
+
+A post can carry a second sound. If the platform refuses the primary sound at posting time, the
+backup becomes the post's `social_audio_id`, the post is re-attempted once, ` switched to backup
+audio` is appended to its `tag`, and `backup_audio_used_at` is set. With no backup left the post
+fails as `audio_unavailable` and is not retried. Set it with `backupSocialAudioId` on
+`posts.createVideo()`, `posts.createSlideshow()`, `posts.createDraft()`, and `posts.updatePost()`
+(`null` clears it on update).
+
+```typescript
+await client.posts.createSlideshow({
+  accountId: "acc_123",
+  imageUrls: ["https://example.com/img1.jpg"],
+  socialAudioId: "audio_primary",
+  backupSocialAudioId: "audio_fallback",
+});
+```
+
 ## Useful Exports
 
 - `UGCClient` for API access

package/dist/index.d.ts

@@ -27,10 +27,10 @@ export type { InputType } from './automations/nodes/types';
 export type { ClientConfig } from './base';
 export type { Account, AccountStatus, AccountStat, AccountTask, QuarantineAccountParams, ReleaseAccountParams, QuarantineAccountResponse, EditProfileInfo, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, AccountInfoUpdate, UpdateAccountInfoParams, AccountInfoUpdateResult, UpdateAccountInfoResponse, AccountSocialUpdate, UpdateAccountSocialParams, AccountSocialUpdateResult, UpdateAccountSocialResponse, DeleteAccountPostsParams, DeleteAccountPostsResponse, ResetWarmupParams, ResetWarmupResponse, NicheSwitchUpdate, NicheSwitchParams, NicheSwitchResult, NicheSwitchResponse, CreateAccountInput, CreateAccountsParams, CreateAccountResult, CreateAccountsResponse, TroubleshootFailReason, TroubleshootAccount, TroubleshootParams, } from './accounts';
 export type { TaskType, Task, GetTasksParams } from './tasks';
-export type { PostType, PostStatus, Post, PostStat, CaptionOverlay, GetPostsParams, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
+export type { PostType, PostStatus, Post, PostStat, CaptionOverlay, GetPostsParams, GetPostsPageParams, PostsPage, PostSortField, PostSortDirection, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
 export type { RefreshStatsParams, RefreshStatsError, RefreshStatsResponse, RefreshStatsProgressResponse, RefreshStartEvent, RefreshProgressEvent, RefreshDoneEvent, RefreshStreamEvent, DailyAggregatedStat, GetDailyAggregatedStatsParams, DailyAccountStat, GetDailyAccountStatsParams, DailyPostStat, GetDailyPostStatsParams, DashboardDailyStat, GetDashboardDailyStatsParams, TopAccount, GetTopAccountsParams, TopPost, GetTopPostsParams, } from './stats';
 export type { Org, ApiKey, DeleteApiKeyParams, EditApiKeyParams, IntegrationKey, IntegrationProvider, UpsertIntegrationKeyParams, DeleteIntegrationKeyParams } from './org';
-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, GetUploadTokenParams, UploadTokenResponse, } from './media';
+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, } 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';

package/dist/media.d.ts

@@ -150,13 +150,17 @@ export interface PfpSearchResponse {
     search_term: string;
     count: number;
 }
-export interface GetUploadTokenParams {
+export interface OwnedUploadParams {
     filename: string;
-    contentType?: string;
+    contentType: string;
+    size: number;
 }
-export interface UploadTokenResponse {
-    clientToken: string;
+export interface OwnedUploadResponse {
+    url: string;
+    fields: Record<string, string>;
     pathname: string;
+    publicUrl: string;
+    expiresAt: string;
 }
 /**
  * Client for managing media files
@@ -175,15 +179,12 @@ export declare class MediaClient extends BaseClient {
     getSocialAudio(params?: GetSocialAudioParams): Promise<ApiResponse<SocialAudio[]>>;
     /**
      * Create media from URL(s)
-     * Creates media records from files already uploaded to blob storage
+     * Creates media records from files already uploaded to owned media storage
+     * (see getOwnedUpload() for the upload policy)
      */
     create(params: CreateMediaFromUrlParams): Promise<ApiResponse<UploadMediaResponse>>;
-    /**
-     * Get a client token for direct upload to Vercel Blob storage
-     * Use this with the `put` function from @vercel/blob/client
-     * After uploading, call create() with the resulting blob URL
-     */
-    getUploadToken(params: GetUploadTokenParams): Promise<ApiResponse<UploadTokenResponse>>;
+    /** Request a short-lived Wasabi POST policy for an owned media upload. */
+    getOwnedUpload(params: OwnedUploadParams): Promise<ApiResponse<OwnedUploadResponse>>;
     /**
      * Update tags on multiple media items in a single request
      * Works for both user_media and social_audio
@@ -203,7 +204,7 @@ export declare class MediaClient extends BaseClient {
     updateTag(params: UpdateMediaTagParams): Promise<ApiResponse<UpdateMediaTagsResponse>>;
     /**
      * Delete one or more media items
-     * Also deletes the files from blob storage
+     * Also deletes the files from owned media storage
      */
     delete(params: DeleteMediaParams): Promise<ApiResponse<DeleteMediaResponse>>;
     /**

package/dist/media.js

@@ -23,18 +23,15 @@ class MediaClient extends base_1.BaseClient {
     }
     /**
      * Create media from URL(s)
-     * Creates media records from files already uploaded to blob storage
+     * Creates media records from files already uploaded to owned media storage
+     * (see getOwnedUpload() for the upload policy)
      */
     async create(params) {
         return this.post('/media/create', params);
     }
-    /**
-     * Get a client token for direct upload to Vercel Blob storage
-     * Use this with the `put` function from @vercel/blob/client
-     * After uploading, call create() with the resulting blob URL
-     */
-    async getUploadToken(params) {
-        return this.post('/media/create/url', params);
+    /** Request a short-lived Wasabi POST policy for an owned media upload. */
+    async getOwnedUpload(params) {
+        return this.post('/media/create/owned-upload', params);
     }
     /**
      * Update tags on multiple media items in a single request
@@ -61,7 +58,7 @@ class MediaClient extends base_1.BaseClient {
     }
     /**
      * Delete one or more media items
-     * Also deletes the files from blob storage
+     * Also deletes the files from owned media storage
      */
     async delete(params) {
         return this.post('/media/delete', params);

package/dist/posts.d.ts

@@ -10,9 +10,13 @@ import type { ApiResponse } from './types';
  * - `capacity_deferred` — no posting capacity was available; the post will be retried
  * - `platform_change` — the social app's interface changed and the post could not complete
  * - `unconfirmed` — posting finished but publication could not be confirmed
+ * - `audio_unavailable` — the chosen sound was not available on the platform and no backup audio was left
  * - `unknown` — the post failed for an unrecognized reason
+ *
+ * A failed post also carries its category on its `tag`, as a trailing
+ * `fail reason: <category>` (removed again when the post is retried).
  */
-export type PostFailCategory = 'device_error' | 'network_error' | 'upload_interrupted' | 'account_issue' | 'capacity_deferred' | 'platform_change' | 'unconfirmed' | 'unknown';
+export type PostFailCategory = 'device_error' | 'network_error' | 'upload_interrupted' | 'account_issue' | 'capacity_deferred' | 'platform_change' | 'unconfirmed' | 'audio_unavailable' | 'unknown';
 export type PostType = 'video' | 'slideshow';
 export type PostStatus = 'draft' | 'scheduled' | 'pending' | 'complete' | 'failed' | 'retrying' | 'deleting' | 'deleted' | 'hidden' | 'require-approval';
 /**
@@ -42,6 +46,10 @@ export interface Post {
     thumbnail_url: string | null;
     music_post_id: string | null;
     social_audio_id: string | null;
+    /** Fallback sound. Moved into `social_audio_id` (and cleared) if the platform refuses the primary sound. */
+    backup_social_audio_id: string | null;
+    /** When the backup sound was swapped in (ISO 8601), or null if it never was. */
+    backup_audio_used_at: string | null;
     scheduled_at: string | null;
     postUrl?: string;
 }
@@ -101,6 +109,8 @@ export interface CreateSlideshowParams {
     caption?: string;
     title?: string;
     socialAudioId?: string;
+    /** Fallback sound, used once if the platform refuses the primary sound at posting time */
+    backupSocialAudioId?: string;
     postTime?: string;
     imageUrls: string[];
     strict?: boolean;
@@ -126,6 +136,8 @@ export interface CreateVideoParams {
     caption?: string;
     captionOverlays?: CaptionOverlay[];
     socialAudioId?: string;
+    /** Fallback sound, used once if the platform refuses the primary sound at posting time */
+    backupSocialAudioId?: string;
     postTime?: string;
     videoUrl: string;
     strict?: boolean;
@@ -158,6 +170,8 @@ export interface UpdatePostParams {
     caption?: string;
     title?: string;
     socialAudioId?: string;
+    /** Fallback sound, used once if the platform refuses the primary sound at posting time; `null` clears it */
+    backupSocialAudioId?: string | null;
     postTime?: string;
     accountId?: string;
     mediaUrls?: string[];
@@ -184,6 +198,8 @@ export interface CreateDraftParams {
     caption?: string;
     title?: string;
     socialAudioId?: string;
+    /** Fallback sound, used once if the platform refuses the primary sound at posting time */
+    backupSocialAudioId?: string;
     /** Tag stored on the created POST itself (returned as `tag` on the Post object) */
     post_tag?: string;
 }

package/dist/render/Root.js

@@ -59,7 +59,7 @@ const defaultAutoCaptionProps = {
     },
 };
 const defaultScreenshotAnimationProps = {
-    imageUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/IMG_3163-RY0CFNrbnSnqZpaJzi9VdslzfYLLKf.png',
+    imageUrl: 'https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/IMG_3163-RY0CFNrbnSnqZpaJzi9VdslzfYLLKf.png',
     width: 1206,
     height: 2622,
     pauseDurationMs: 1000,
@@ -213,7 +213,7 @@ const instagramDmSchema = zod_1.z.object({
     // Debug overlay
     showDebugOverlay: zod_1.z.boolean().optional().default(true).describe('Show debug overlay with mouse coordinates'),
     // Reference overlay
-    referenceImageUrl: zod_1.z.string().optional().default('https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/IMG_3153-TiJrpzJKKvsTsjmP9zIX5LpoT8s2hF.png').describe('Reference screenshot URL'),
+    referenceImageUrl: zod_1.z.string().optional().default('https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/IMG_3153-TiJrpzJKKvsTsjmP9zIX5LpoT8s2hF.png').describe('Reference screenshot URL'),
     showReferenceImage: zod_1.z.boolean().optional().default(true).describe('Show/hide reference image'),
     referenceOpacity: zod_1.z.number().min(0).max(100).optional().default(50).describe('Reference overlay opacity (0-100)'),
     // Canvas
@@ -326,7 +326,7 @@ const instagramDmSchema = zod_1.z.object({
     backArrowLeft: zod_1.z.number().optional().default(78).describe('Back arrow left X'),
     backArrowRight: zod_1.z.number().optional().default(111).describe('Back arrow right X'),
     // Header - User profile picture
-    userPfpUrl: zod_1.z.string().optional().default('https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/884a81ce74fa88e229f6be5f76f29385-3P4rjQqfbLidxtZ7OmvgaDQNMSSIGi.jpg').describe('User profile picture URL'),
+    userPfpUrl: zod_1.z.string().optional().default('https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/884a81ce74fa88e229f6be5f76f29385-3P4rjQqfbLidxtZ7OmvgaDQNMSSIGi.jpg').describe('User profile picture URL'),
     userPfpTop: zod_1.z.number().optional().default(220).describe('User pfp top Y'),
     userPfpBottom: zod_1.z.number().optional().default(320).describe('User pfp bottom Y'),
     userPfpLeft: zod_1.z.number().optional().default(179).describe('User pfp left X'),

package/dist/render/compositions/IMessageDmComposition/index.js

@@ -25,7 +25,7 @@ Object.defineProperty(exports, "convertPropsToElements", { enumerable: true, get
  */
 exports.defaultIMessageDmProps = {
     showDebugOverlay: false,
-    referenceImageUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/06c3ed1c-eefb-4a60-b0c4-5fb872811ba0/IMG_3189-hUoucNOmBoT8fihIL7ybuEXwoRrngz.png',
+    referenceImageUrl: 'https://media.ugc.inc/media/06c3ed1c-eefb-4a60-b0c4-5fb872811ba0/IMG_3189-hUoucNOmBoT8fihIL7ybuEXwoRrngz.png',
     showReferenceImage: false,
     referenceOpacity: 50,
     lightMode: false,
@@ -38,7 +38,7 @@ exports.defaultIMessageDmProps = {
     headerBottom: 424,
     headerBackgroundColor: '#171717',
     // Profile section defaults
-    profilePicUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/06c3ed1c-eefb-4a60-b0c4-5fb872811ba0/pinterest-1766175215011-3-ftQGbunlgHOFdfFtr1PdxxmHD9TAf9.jpg',
+    profilePicUrl: 'https://media.ugc.inc/media/06c3ed1c-eefb-4a60-b0c4-5fb872811ba0/pinterest-1766175215011-3-ftQGbunlgHOFdfFtr1PdxxmHD9TAf9.jpg',
     profilePicTop: 195,
     profilePicBottom: 347,
     profilePicLeft: 528,
@@ -225,7 +225,7 @@ exports.defaultIMessageDmProps = {
     readReceiptRight: 1158,
     // Example messages
     messages: [
-        { id: 'msg-1', sender: 'user', text: 'heyyy fae, help me slide on this baddie pls 🙏', imageUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/06c3ed1c-eefb-4a60-b0c4-5fb872811ba0/pinterest-1766175214139-0-JpXmGIxVWdjEJ3qxGyoC4DAi2KAZrg.jpg' },
+        { id: 'msg-1', sender: 'user', text: 'heyyy fae, help me slide on this baddie pls 🙏', imageUrl: 'https://media.ugc.inc/media/06c3ed1c-eefb-4a60-b0c4-5fb872811ba0/pinterest-1766175214139-0-JpXmGIxVWdjEJ3qxGyoC4DAi2KAZrg.jpg' },
         { id: 'msg-2', sender: 'recipient', text: 'don\'t worry king, i gotchu' },
         { id: 'msg-3', sender: 'recipient', text: 'that is indeed a cute kitty', groupWithPrevious: true },
         { id: 'msg-4', sender: 'recipient', text: 'try this line out for speed: are you a kitty? because you deserve pets', groupWithPrevious: true },

package/dist/render/compositions/InstagramDmComposition/index.js

@@ -26,7 +26,7 @@ Object.defineProperty(exports, "convertPropsToElements", { enumerable: true, get
  */
 exports.defaultInstagramDmProps = {
     showDebugOverlay: false,
-    referenceImageUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/IMG_3186-L1M2HgmhYFpnI5uKDrhcKYpRQSzwoz.png',
+    referenceImageUrl: 'https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/IMG_3186-L1M2HgmhYFpnI5uKDrhcKYpRQSzwoz.png',
     showReferenceImage: false,
     referenceOpacity: 50,
     width: 1206,
@@ -89,7 +89,7 @@ exports.defaultInstagramDmProps = {
     // Message defaults
     messages: [
         // Sender group 1 (with story reply)
-        { id: '1', sender: 'user', text: "if you were a disney princess you'd be jasmine", storyReplyImageUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/ddafc0af3ae404d8223d191bcd424a4a-IMBUblDJvuj2g8LkUZXQ3pJZzfBSTc.jpg' },
+        { id: '1', sender: 'user', text: "if you were a disney princess you'd be jasmine", storyReplyImageUrl: 'https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/ddafc0af3ae404d8223d191bcd424a4a-IMBUblDJvuj2g8LkUZXQ3pJZzfBSTc.jpg' },
         // Receiver group 1
         { id: '2', sender: 'recipient', text: 'aww ur sweet' },
         { id: '3', sender: 'recipient', text: "but i'm clearly more of a mulan 🙄", groupWithPrevious: true },
@@ -131,7 +131,7 @@ exports.defaultInstagramDmProps = {
     recipientBubbleLeft: 168,
     senderBubbleRight: 1182,
     bubbleMaxWidth: 866,
-    profilePicUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/884a81ce74fa88e229f6be5f76f29385-3P4rjQqfbLidxtZ7OmvgaDQNMSSIGi.jpg',
+    profilePicUrl: 'https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/884a81ce74fa88e229f6be5f76f29385-3P4rjQqfbLidxtZ7OmvgaDQNMSSIGi.jpg',
     profilePicSize: 83,
     profilePicGap: 37,
     // Header - Back arrow
@@ -140,7 +140,7 @@ exports.defaultInstagramDmProps = {
     backArrowLeft: 78,
     backArrowRight: 111,
     // Header - User profile picture
-    userPfpUrl: 'https://n14dcpakf8w1fekl.public.blob.vercel-storage.com/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/884a81ce74fa88e229f6be5f76f29385-3P4rjQqfbLidxtZ7OmvgaDQNMSSIGi.jpg',
+    userPfpUrl: 'https://media.ugc.inc/media/8ff1462b-13d7-4abe-9325-0a6ad19004f0/884a81ce74fa88e229f6be5f76f29385-3P4rjQqfbLidxtZ7OmvgaDQNMSSIGi.jpg',
     userPfpTop: 220,
     userPfpBottom: 320,
     userPfpLeft: 179,

package/dist/render.d.ts

@@ -1,6 +1,11 @@
 /**
- * Render functions for submitting jobs to the Modal renderer.
- * These functions call Modal endpoints directly, not the UGC Inc API.
+ * Render functions: submit image, video, deduplication, scene-split and DM
+ * jobs to the UGC render worker and poll them.
+ *
+ * The worker's origin is read from `UGC_RENDER_URL` at call time. It is a
+ * private origin (the owned render worker is reachable only from the UGC API's
+ * network); there is no public default, so calling these functions without the
+ * variable set fails fast.
  */
 import type { ApiResponse } from './types';
 import type { VideoEditorNodeConfig, DeduplicationInput } from './render/types';
@@ -156,45 +161,45 @@ export interface SubmitIMessageDmRenderJobParams {
     dynamicCrop?: import('./render/types/crop').DynamicCropConfig;
 }
 /**
- * Submit an image render job to the Modal renderer.
+ * Submit an image render job to the render worker.
  * Uses the element-based format for single-source-of-truth rendering.
  */
 export declare function submitImageRenderJob(params: SubmitImageRenderJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Submit a video render job to the Modal renderer.
+ * Submit a video render job to the render worker.
  */
 export declare function submitVideoRenderJob(params: SubmitVideoRenderJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Get render job status from the Modal renderer.
+ * Get render job status from the render worker.
  */
 export declare function getRenderJobStatus(jobId: string): Promise<ApiResponse<RenderJobStatus>>;
 /**
- * Submit a deduplication job to the Modal renderer.
+ * Submit a deduplication job to the render worker.
  * Applies hash-breaking, metadata injection, and trace removal to a video.
  */
 export declare function submitDeduplicationJob(params: SubmitDeduplicationJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Submit a scene split job to the Modal renderer.
+ * Submit a scene split job to the render worker.
  * Detects scene boundaries and splits a video into individual clips.
  */
 export declare function submitSceneSplitJob(params: SubmitSceneSplitJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Submit a screenshot animation render job to the Modal renderer.
+ * Submit a screenshot animation render job to the render worker.
  * Renders an iPhone screenshot animation video from a source image.
  */
 export declare function submitScreenshotAnimationRenderJob(params: SubmitScreenshotAnimationRenderJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Submit an auto-caption render job to the Modal renderer.
+ * Submit an auto-caption render job to the render worker.
  * Renders a video with captions overlaid.
  */
 export declare function submitAutoCaptionRenderJob(params: SubmitAutoCaptionRenderJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Submit an Instagram DM render job to the Modal renderer.
+ * Submit an Instagram DM render job to the render worker.
  * Renders a fake Instagram DM conversation image.
  */
 export declare function submitInstagramDmRenderJob(params: SubmitInstagramDmRenderJobParams): Promise<ApiResponse<RenderJobResponse>>;
 /**
- * Submit an iMessage DM render job to the Modal renderer.
+ * Submit an iMessage DM render job to the render worker.
  * Renders a fake iMessage conversation image.
  */
 export declare function submitIMessageDmRenderJob(params: SubmitIMessageDmRenderJobParams): Promise<ApiResponse<RenderJobResponse>>;

package/dist/render.js

@@ -1,7 +1,12 @@
 "use strict";
 /**
- * Render functions for submitting jobs to the Modal renderer.
- * These functions call Modal endpoints directly, not the UGC Inc API.
+ * Render functions: submit image, video, deduplication, scene-split and DM
+ * jobs to the UGC render worker and poll them.
+ *
+ * The worker's origin is read from `UGC_RENDER_URL` at call time. It is a
+ * private origin (the owned render worker is reachable only from the UGC API's
+ * network); there is no public default, so calling these functions without the
+ * variable set fails fast.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.submitImageRenderJob = submitImageRenderJob;
@@ -13,72 +18,40 @@ exports.submitScreenshotAnimationRenderJob = submitScreenshotAnimationRenderJob;
 exports.submitAutoCaptionRenderJob = submitAutoCaptionRenderJob;
 exports.submitInstagramDmRenderJob = submitInstagramDmRenderJob;
 exports.submitIMessageDmRenderJob = submitIMessageDmRenderJob;
-// Modal renderer endpoints
-const RENDER_BASE_URL = "https://render.ugc.inc";
-const RENDER_SUBMIT_URL = `${RENDER_BASE_URL}/submit-job`;
-const RENDER_STATUS_URL = `${RENDER_BASE_URL}/get-status`;
-// =============================================================================
-// Rate Limiting & Retry (Modal workspace limit: 200 req/s)
-// =============================================================================
-const MODAL_RATE_LIMIT = 150; // per second, safety margin below 200
-const MAX_RETRIES = 3;
-// Sliding window: timestamps of recent requests within the last second
-const requestTimestamps = [];
-function acquireRateSlot() {
-    const now = Date.now();
-    // Evict timestamps older than 1 second
-    while (requestTimestamps.length > 0 && requestTimestamps[0] < now - 1000) {
-        requestTimestamps.shift();
-    }
-    if (requestTimestamps.length < MODAL_RATE_LIMIT) {
-        requestTimestamps.push(now);
-        return 0; // no wait needed
-    }
-    // Calculate ms until the oldest request exits the window
-    return 1000 - (now - requestTimestamps[0]) + 10;
-}
-async function waitForRateSlot() {
-    let waitMs = acquireRateSlot();
-    while (waitMs > 0) {
-        await new Promise(resolve => setTimeout(resolve, waitMs));
-        waitMs = acquireRateSlot();
+function renderBaseUrl() {
+    const url = process.env.UGC_RENDER_URL?.trim();
+    if (!url) {
+        throw new Error('UGC_RENDER_URL is not set: the render functions need the render worker origin');
     }
+    return url.replace(/\/+$/, '');
 }
+const MAX_RETRIES = 3;
 /**
- * Fetch wrapper for all Modal API calls.
- * Applies rate limiting (150 req/s) and retries on 429/5xx with exponential backoff.
+ * Fetch wrapper for every render worker call: retries network errors, 429 and
+ * 5xx with exponential backoff; returns 4xx responses to the caller unchanged.
  */
-async function modalFetch(url, options) {
+async function renderFetch(path, options) {
+    const url = `${renderBaseUrl()}${path}`;
+    let response;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-        await waitForRateSlot();
-        let response;
         try {
             response = await fetch(url, options);
         }
         catch (error) {
-            // Network error — retry with backoff
             if (attempt < MAX_RETRIES) {
-                const backoff = Math.pow(2, attempt) * 500 + Math.random() * 500;
-                await new Promise(resolve => setTimeout(resolve, backoff));
+                await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 500 + Math.random() * 500));
                 continue;
             }
             throw error;
         }
-        // Success or non-retryable client error (400, 401, 403, 404, etc.)
         if (response.ok || (response.status >= 400 && response.status < 500 && response.status !== 429)) {
             return response;
         }
-        // Retryable: 429 (rate limit) or 5xx (server error)
         if (attempt < MAX_RETRIES) {
-            const backoff = Math.pow(2, attempt) * 500 + Math.random() * 500;
-            await new Promise(resolve => setTimeout(resolve, backoff));
-            continue;
+            await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 500 + Math.random() * 500));
         }
-        return response; // Return error response on final attempt
     }
-    // Unreachable, but satisfies TypeScript
-    await waitForRateSlot();
-    return fetch(url, options);
+    return response;
 }
 // =============================================================================
 // DM Message Transformation Helpers
@@ -131,12 +104,12 @@ function transformToIMessageMessages(messages, imageAttachmentUrl) {
 // Render Functions
 // =============================================================================
 /**
- * Submit an image render job to the Modal renderer.
+ * Submit an image render job to the render worker.
  * Uses the element-based format for single-source-of-truth rendering.
  */
 async function submitImageRenderJob(params) {
     try {
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -164,7 +137,7 @@ async function submitImageRenderJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit render job' };
@@ -177,11 +150,11 @@ async function submitImageRenderJob(params) {
     }
 }
 /**
- * Submit a video render job to the Modal renderer.
+ * Submit a video render job to the render worker.
  */
 async function submitVideoRenderJob(params) {
     try {
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -202,7 +175,7 @@ async function submitVideoRenderJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit render job' };
@@ -215,11 +188,11 @@ async function submitVideoRenderJob(params) {
     }
 }
 /**
- * Get render job status from the Modal renderer.
+ * Get render job status from the render worker.
  */
 async function getRenderJobStatus(jobId) {
     try {
-        const response = await modalFetch(RENDER_STATUS_URL, {
+        const response = await renderFetch('/get-status', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ job_id: jobId }),
@@ -230,7 +203,7 @@ async function getRenderJobStatus(jobId) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to get job status' };
@@ -247,12 +220,12 @@ async function getRenderJobStatus(jobId) {
     }
 }
 /**
- * Submit a deduplication job to the Modal renderer.
+ * Submit a deduplication job to the render worker.
  * Applies hash-breaking, metadata injection, and trace removal to a video.
  */
 async function submitDeduplicationJob(params) {
     try {
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -267,7 +240,7 @@ async function submitDeduplicationJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit deduplication job' };
@@ -280,12 +253,12 @@ async function submitDeduplicationJob(params) {
     }
 }
 /**
- * Submit a scene split job to the Modal renderer.
+ * Submit a scene split job to the render worker.
  * Detects scene boundaries and splits a video into individual clips.
  */
 async function submitSceneSplitJob(params) {
     try {
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -300,7 +273,7 @@ async function submitSceneSplitJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit scene split job' };
@@ -313,12 +286,12 @@ async function submitSceneSplitJob(params) {
     }
 }
 /**
- * Submit a screenshot animation render job to the Modal renderer.
+ * Submit a screenshot animation render job to the render worker.
  * Renders an iPhone screenshot animation video from a source image.
  */
 async function submitScreenshotAnimationRenderJob(params) {
     try {
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -337,7 +310,7 @@ async function submitScreenshotAnimationRenderJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit screenshot animation job' };
@@ -350,12 +323,12 @@ async function submitScreenshotAnimationRenderJob(params) {
     }
 }
 /**
- * Submit an auto-caption render job to the Modal renderer.
+ * Submit an auto-caption render job to the render worker.
  * Renders a video with captions overlaid.
  */
 async function submitAutoCaptionRenderJob(params) {
     try {
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -379,7 +352,7 @@ async function submitAutoCaptionRenderJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit auto-caption job' };
@@ -392,14 +365,14 @@ async function submitAutoCaptionRenderJob(params) {
     }
 }
 /**
- * Submit an Instagram DM render job to the Modal renderer.
+ * Submit an Instagram DM render job to the render worker.
  * Renders a fake Instagram DM conversation image.
  */
 async function submitInstagramDmRenderJob(params) {
     try {
         const transformedMessages = transformToInstagramMessages(params.messages, params.imageAttachmentUrl);
         const hasStoryReply = params.messages.some(msg => msg.hasImage);
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -424,7 +397,7 @@ async function submitInstagramDmRenderJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit Instagram DM job' };
@@ -437,13 +410,13 @@ async function submitInstagramDmRenderJob(params) {
     }
 }
 /**
- * Submit an iMessage DM render job to the Modal renderer.
+ * Submit an iMessage DM render job to the render worker.
  * Renders a fake iMessage conversation image.
  */
 async function submitIMessageDmRenderJob(params) {
     try {
         const transformedMessages = transformToIMessageMessages(params.messages, params.imageAttachmentUrl);
-        const response = await modalFetch(RENDER_SUBMIT_URL, {
+        const response = await renderFetch('/submit-job', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
@@ -473,7 +446,7 @@ async function submitIMessageDmRenderJob(params) {
             data = JSON.parse(text);
         }
         catch {
-            return { ok: false, code: response.status || 500, message: `Modal endpoint error: ${text.substring(0, 100)}` };
+            return { ok: false, code: response.status || 500, message: `Render endpoint error: ${text.substring(0, 100)}` };
         }
         if (data.status === 'error' || !response.ok) {
             return { ok: false, code: response.status, message: data.error ?? data.message ?? 'Failed to submit iMessage DM job' };

package/dist/tools/posts.js

@@ -26,6 +26,7 @@ exports.postTools = [
             videoUrl: zod_1.z.string().describe('URL of the video file'),
             caption: zod_1.z.string().optional().describe('Post caption'),
             socialAudioId: zod_1.z.string().optional().describe('Social audio ID to use'),
+            backupSocialAudioId: zod_1.z.string().optional().describe('Fallback social audio ID, used once if the platform refuses the primary sound'),
             postTime: zod_1.z.string().optional().describe('Scheduled time (ISO 8601). Omit for next available slot.'),
             strict: zod_1.z.boolean().optional().describe('If true with auto-selection, must post at exact time or error'),
             mustPostBy: zod_1.z.string().optional().describe('Latest allowed scheduled time (ISO 8601). Errors if no slot is available before this deadline.'),
@@ -47,6 +48,7 @@ exports.postTools = [
             caption: zod_1.z.string().optional().describe('Post caption'),
             title: zod_1.z.string().optional().describe('Slideshow title'),
             socialAudioId: zod_1.z.string().optional().describe('Social audio ID to use'),
+            backupSocialAudioId: zod_1.z.string().optional().describe('Fallback social audio ID, used once if the platform refuses the primary sound'),
             postTime: zod_1.z.string().optional().describe('Scheduled time (ISO 8601)'),
             strict: zod_1.z.boolean().optional().describe('If true with auto-selection, must post at exact time or error'),
             mustPostBy: zod_1.z.string().optional().describe('Latest allowed scheduled time (ISO 8601). Errors if no slot is available before this deadline.'),
@@ -68,6 +70,7 @@ exports.postTools = [
             caption: zod_1.z.string().optional().describe('Post caption'),
             title: zod_1.z.string().optional().describe('Slideshow title'),
             socialAudioId: zod_1.z.string().optional().describe('Social audio ID'),
+            backupSocialAudioId: zod_1.z.string().optional().describe('Fallback social audio ID, used once if the platform refuses the primary sound'),
             post_tag: zod_1.z.string().optional().describe('Tag stored on the created post'),
         }),
         execute: async (client, params) => {
@@ -92,6 +95,7 @@ exports.postTools = [
             caption: zod_1.z.string().optional().describe('New caption'),
             title: zod_1.z.string().optional().describe('New title (slideshows only)'),
             socialAudioId: zod_1.z.string().optional().describe('New social audio ID'),
+            backupSocialAudioId: zod_1.z.string().nullable().optional().describe('Fallback social audio ID, used once if the platform refuses the primary sound; null clears it'),
             postTime: zod_1.z.string().optional().describe('New scheduled time (ISO 8601)'),
             accountId: zod_1.z.string().optional().describe('Move post to different account'),
             mediaUrls: zod_1.z.array(zod_1.z.string()).optional().describe('New media URLs'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc",
-  "version": "4.14.0",
+  "version": "4.15.1",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",