@scenario-labs/sdk 2.3.0 → 2.4.0

package/src/resources/generate.ts

@@ -72,9 +72,9 @@ export class Generate extends APIResource {
     params: GenerateRunModelParams,
     options?: RequestOptions,
   ): APIPromise<GenerateRunModelResponse> {
-    const { body, dryRun } = params;
+    const { body, dryRun, ipDetection } = params;
     return this._client.post(path`/generate/custom/${modelID}`, {
-      query: { dryRun },
+      query: { dryRun, ipDetection },
       body: body,
       ...options,
     });
@@ -117,6 +117,11 @@ export interface GenerateCaptionResponse {
    * ignored.
    */
   detailsLevel?: 'action' | 'action+style';
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GenerateCaptionResponse.IPDetection;
 }
 
 export namespace GenerateCaptionResponse {
@@ -1079,6 +1084,84 @@ export namespace GenerateCaptionResponse {
       cuDiscount: number;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GenerateDescribeStyleResponse {
@@ -1103,6 +1186,11 @@ export interface GenerateDescribeStyleResponse {
    * The Creative Units discount for the request billed
    */
   creativeUnitsDiscount?: number;
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GenerateDescribeStyleResponse.IPDetection;
 }
 
 export namespace GenerateDescribeStyleResponse {
@@ -2065,6 +2153,84 @@ export namespace GenerateDescribeStyleResponse {
       cuDiscount: number;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GenerateDetectResponse {
@@ -2081,6 +2247,11 @@ export interface GenerateDetectResponse {
    * The Creative Units discount for the request billed
    */
   creativeUnitsDiscount?: number;
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GenerateDetectResponse.IPDetection;
 }
 
 export namespace GenerateDetectResponse {
@@ -4184,6 +4355,84 @@ export namespace GenerateDetectResponse {
       url: string;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GenerateEmbedResponse {
@@ -4205,6 +4454,11 @@ export interface GenerateEmbedResponse {
    * The Creative Units discount for the request billed
    */
   creativeUnitsDiscount?: number;
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GenerateEmbedResponse.IPDetection;
 }
 
 export namespace GenerateEmbedResponse {
@@ -5167,6 +5421,84 @@ export namespace GenerateEmbedResponse {
       cuDiscount: number;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GeneratePatchResponse {
@@ -5183,6 +5515,11 @@ export interface GeneratePatchResponse {
    * The Creative Units discount for the request billed
    */
   creativeUnitsDiscount?: number;
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GeneratePatchResponse.IPDetection;
 }
 
 export namespace GeneratePatchResponse {
@@ -7286,6 +7623,84 @@ export namespace GeneratePatchResponse {
       url: string;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GeneratePromptResponse {
@@ -7296,6 +7711,12 @@ export interface GeneratePromptResponse {
    */
   prompts: Array<string>;
 
+  /**
+   * The full ready-to-run model calls, index-aligned with `prompts`: `prompts[i]` is
+   * the prompt text of `calls[i]`.
+   */
+  calls?: Array<GeneratePromptResponse.Call>;
+
   /**
    * The Creative Units cost for the request billed
    */
@@ -7306,10 +7727,15 @@ export interface GeneratePromptResponse {
    */
   creativeUnitsDiscount?: number;
 
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GeneratePromptResponse.IPDetection;
+
   /**
    * The mode used to generate new prompt(s).
    */
-  mode?: 'completion' | 'contextual' | 'image-editing' | 'inventive' | 'structured';
+  mode?: 'completion' | 'contextual' | 'contextual-v2' | 'image-editing' | 'inventive' | 'structured';
 }
 
 export namespace GeneratePromptResponse {
@@ -8272,6 +8698,108 @@ export namespace GeneratePromptResponse {
       cuDiscount: number;
     }
   }
+
+  /**
+   * A complete, ready-to-run model call proposed by Prompt Spark v3.
+   *
+   * The prompt text is carried inside `parameters` under the target model's prompt
+   * input (when the model defines one). For models without a prompt input, the text
+   * is only available in the index-aligned `prompts` array.
+   */
+  export interface Call {
+    /**
+     * The target model the call is for.
+     */
+    modelId: string;
+
+    /**
+     * Schema-valid dynamic parameters for the target model, prompt included.
+     */
+    parameters: unknown;
+
+    /**
+     * Optional rationale for the proposed call.
+     */
+    rationale?: string;
+  }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GenerateRunModelResponse {
@@ -8286,6 +8814,11 @@ export interface GenerateRunModelResponse {
    * The Creative Units discount for the request billed
    */
   creativeUnitsDiscount?: number;
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GenerateRunModelResponse.IPDetection;
 }
 
 export namespace GenerateRunModelResponse {
@@ -9248,6 +9781,84 @@ export namespace GenerateRunModelResponse {
       cuDiscount: number;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GenerateTranslateResponse {
@@ -9272,6 +9883,11 @@ export interface GenerateTranslateResponse {
    * The Creative Units discount for the request billed
    */
   creativeUnitsDiscount?: number;
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  ipDetection?: GenerateTranslateResponse.IPDetection;
 }
 
 export namespace GenerateTranslateResponse {
@@ -10234,6 +10850,84 @@ export namespace GenerateTranslateResponse {
       cuDiscount: number;
     }
   }
+
+  /**
+   * IP detection findings, when detection ran for this request.
+   */
+  export interface IPDetection {
+    /**
+     * Whether and how detection affected the request.
+     */
+    action: 'allowed' | 'blocked' | 'flagged';
+
+    /**
+     * IP-detection CU fee, separate from creativeUnitsCost: a fixed base fee plus a
+     * per-image fee for each analyzed input image.
+     */
+    creativeUnitsCharged: number;
+
+    /**
+     * Number of enabled filters evaluated for this request.
+     */
+    evaluatedFilters: number;
+
+    /**
+     * Per-filter verdicts gathered for this request.
+     */
+    findings: Array<IPDetection.Finding>;
+
+    /**
+     * Convenience flag; always true when action is not 'allowed'.
+     */
+    flagged: boolean;
+
+    /**
+     * True if one or more detectors errored while evaluating this request.
+     */
+    hasDetectorError?: boolean;
+  }
+
+  export namespace IPDetection {
+    /**
+     * A single filter's verdict.
+     */
+    export interface Finding {
+      /**
+       * Category of the filter that produced this verdict.
+       */
+      category: 'artist-style' | 'brand-trademark' | 'celebrity-likeness' | 'custom' | 'fictional-character';
+
+      /**
+       * Confidence score from 0 (low) to 1 (high).
+       */
+      confidence: number;
+
+      /**
+       * Identifier of the filter that produced this verdict.
+       */
+      filterId: string;
+
+      /**
+       * Display name of the filter that produced this verdict.
+       */
+      filterName: string;
+
+      /**
+       * Whether this filter considered the request an IP risk.
+       */
+      flagged: boolean;
+
+      /**
+       * Short, user-facing explanation of the verdict.
+       */
+      reason: string;
+
+      /**
+       * Named entities the filter recognized (e.g. characters, brands, people).
+       */
+      entities?: Array<string>;
+    }
+  }
 }
 
 export interface GenerateCaptionParams {
@@ -10589,7 +11283,7 @@ export interface GeneratePromptParams {
   /**
    * Body param: The mode used to generate new prompt(s).
    */
-  mode: 'completion' | 'contextual' | 'image-editing' | 'inventive' | 'structured';
+  mode: 'completion' | 'contextual' | 'contextual-v2' | 'image-editing' | 'inventive' | 'structured';
 
   /**
    * Query param
@@ -10697,6 +11391,13 @@ export interface GenerateRunModelParams {
    * Query param
    */
   dryRun?: unknown;
+
+  /**
+   * Query param: Set to "true" to run an IP-detection preflight on this request.
+   * Combine with ?dryRun=true for an advisory check that returns findings without
+   * generating.
+   */
+  ipDetection?: boolean;
 }
 
 export interface GenerateTranslateParams {