openapi: 3.1.0 info: title: Undress API description: API for undressing images, face swaps, and animations. Premium v3 lives under its own `/api/v3/undress` namespace; everything else is served from `/api/v1/...`. version: 2.0.0 contact: name: DeepStrip url: https://deepstrip.com/ servers: - url: https://deepstrip.com components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: "Opaque API key issued at /api/documentation. Sent as `Authorization: Bearer `." schemas: UndressRequest: type: object required: - style properties: source_image: type: string description: Base64 encoded source image in jpeg, png, or webp format (max 12 MB). Required unless `parent` is supplied. mask: type: string description: "Base64 encoded mask image in png format (max 1 MB). Contains two colors: white for undressing regions, black for the rest. Only honored when style is `premium_v2` and `automask` is not `true`; ignored for all other styles." automask: type: boolean description: When `true`, the server generates the mask. Only meaningful for `premium_v2`; `standard` and `video` always auto-mask server-side regardless of this field. parent: type: string description: ID of a previous `video` Undress to continue with the next clothing layer. Style and source are inherited; the parent must be less than 24 hours old. style: type: string description: The model for undressing. `premium_v3` is served from a dedicated endpoint (`POST /api/v3/undress`) and is not accepted here. enum: [standard, premium_v2, video] body_shape: type: string description: Body shape adjustment (only for premium_v2 style). enum: ["null", fat, skinny, athletic, old] boobs: type: string description: Breast size adjustment (only for premium_v2 style). enum: ["null", small, large] hair: type: string description: Pubic hair style (only for premium_v2 style). enum: ["null", hairy, shaved] UndressV3Request: type: object required: - image_url - person_id properties: image_url: type: string format: uri description: HTTPS URL of the source image (jpeg, png, or webp, max 12 MB). The same URL the caller submitted to `POST /api/v1/persons/analyze`. person_id: type: string description: Identifier returned by `GET /api/v1/persons/analyze/{id}` for the specific person to undress. Must belong to an analysis of the same `image_url`, owned by the caller, and still within the 3-hour cache window. person_gender: type: string description: Override the detector's gender for this person. Use when the detector misclassifies and you want to force the opposite workflow. Case-insensitive. When omitted, the detector's gender is used. enum: [male, female] PersonsAnalyzeRequest: type: object required: - image_url properties: image_url: type: string format: uri description: HTTPS URL of the image to analyze. The detector service fetches it directly. PersonsAnalyzeResponse: type: object properties: id: type: string description: Identifier for the analysis job. Poll with `GET /api/v1/persons/analyze/{id}`. PersonSchema: type: object properties: id: type: string description: Stable identifier for this person within the analysis result. Pass as `person_id` to `POST /api/v3/undress`. bbox: type: array description: Bounding box in source-image pixel coordinates, `[x1, y1, x2, y2]`. items: type: number minItems: 4 maxItems: 4 age: type: number description: Estimated age. Persons without a recognized age are not returned. gender: type: string description: Detected gender. Persons without a recognized gender are not returned. enum: [male, female] score: type: number description: Detector confidence for the person box. PersonsAnalysisStatusResponse: type: object properties: status: type: string enum: [pending, completed, failed] persons: type: array description: Only present when `status` is `completed`. May be an empty array when the detector finds no recognized persons in the image. items: $ref: "#/components/schemas/PersonSchema" details: type: string description: Failure reason. Only present when `status` is `failed`. enum: [detector_failed] FaceSwapRequest: type: object required: - image - face properties: image: type: string description: Base64 encoded image. face: type: string description: Base64 encoded face image. version: type: string description: Version of the face swap model. enum: [v1, v2] mode: type: string description: Swap type. `face_swap` (default, 3 credits) replaces only the face; `head_swap` (5 credits) replaces the entire head. enum: [face_swap, head_swap] default: face_swap UndressResponse: type: object properties: id: type: string description: Identifier for the job. FaceSwapResponse: type: object properties: id: type: string description: Identifier for the job. ErrorResponse: type: object properties: error: type: string message: type: string description: "English sentence, the same the website shows: `File is too large. Maximum size is N MB.` (the limit of the mode: 20 MB for a base64 photo, 10 MB for an animation photo, 12 MB for an `image_url`). Only present when `error` is `file_too_large`." errors: type: array items: type: string UndressResultResponse: type: object properties: status: type: string description: Status of the undress job. enum: [pending, completed, failed] image: type: string description: URL of the generated image, if the job is completed. DEPRECATED — use `result`. result: type: string description: URL of the generated result, if the job is completed. For `video` style this is an mp4 URL; otherwise an image URL. details: type: string description: Failure reason. Only present when `status` is `failed`. enum: [analysis_failed, system_error] error_details: type: object description: Why the upload checks turned the job away. Only present for these rejections. properties: code: type: string enum: [face.child] underage_persons: type: array description: Detected underage persons (age and face/body boxes). Only present when code is "face.child". items: type: object message: type: string description: "English sentence for the rejection, the same the website shows: `Person under 21 detected. Blocked due to a Terms of Use violation.` (code `face.child`) or `Face not found.` (code `no_face_found`). Only present for these rejections." FaceSwapResultResponse: type: object properties: status: type: string description: Status of the face swap job. enum: [pending, completed, failed] image: type: string description: URL of the generated image, if the job is completed. error_details: type: object description: Why the upload checks turned the job away. Only present for these rejections. properties: code: type: string enum: [face.child, no_face_found] underage_persons: type: array description: Detected underage persons (age and face/body boxes). Only present when code is "face.child". items: type: object message: type: string description: "English sentence for the rejection, the same the website shows: `Person under 21 detected. Blocked due to a Terms of Use violation.` (code `face.child`) or `Face not found.` (code `no_face_found`). Only present for these rejections." FaceSwapVideoAnalyzeRequest: type: object required: - video_url properties: video_url: type: string description: Public HTTPS URL of the video to analyze, on port 443, at most 4096 characters, without embedded credentials. All resolved IP addresses must be public. Downloads are limited to 1024 MiB (1,073,741,824 bytes) and require at least 256 KiB/s in each 15-second body window. preview: type: boolean description: Whether to create a preview (shorter) version. version: type: string description: Version of the face swap model. enum: [v1, v2] FaceSwapVideoAnalyzeResponse: type: object properties: price: type: number description: Calculated price for the face swap video, in credits. duration: type: integer description: Detected video duration in seconds. FaceSwapVideoRequest: type: object properties: video_url: type: string description: Public HTTPS URL of the video to process, on port 443, at most 4096 characters, without embedded credentials. All resolved IP addresses must be public. face_url: type: string description: Public HTTPS URL of the face image, on port 443, at most 4096 characters, without embedded credentials. All resolved IP addresses must be public. preview: type: boolean description: Whether to create a preview version. version: type: string description: Version of the face swap model. enum: [v1, v2] FaceSwapVideoResponse: type: object properties: id: type: string description: Identifier for the face swap video job. status: type: string description: Initial status of the job. message: type: string description: Additional information about the job. FaceSwapVideoStatusResponse: type: object properties: id: type: string description: Identifier for the face swap video job. status: type: string description: Status of the face swap video job. enum: [initial, sent, processing, completed, failed] progress: type: number description: Progress percentage of the processing. step: type: string description: Current processing step. enum: [queued, downloading, fps, analysing, working, sound, reencoding_step_1, reencoding_step_2, postprocessing, uploading] result_url: type: string description: URL of the processed video, if completed. error_details: type: object description: Error information if the job failed. message: type: string description: "English sentence for the rejection, the same the website shows: `Person under 21 detected. Blocked due to a Terms of Use violation.` (code `face.child`) or `Face not found.` (code `no_face_found`). Only present for these rejections." created_at: type: string format: date-time description: When the job was created. updated_at: type: string format: date-time description: When the job was last updated. HeadSwapVideoRequest: type: object required: [video_url, face_url, trim_start, trim_end] properties: video_url: type: string format: uri description: Public HTTPS URL (port 443, at most 4096 characters) of an MP4, MOV, MKV, AVI, FLV or WebM video, up to 1024 MiB (1,073,741,824 bytes). Downloaded asynchronously by media-analyzer; at least 256 KiB/s is required in every 15-second body window, with no fixed two-minute deadline. face_url: type: string format: uri description: Public HTTPS URL (port 443, at most 4096 characters) of a JPEG, PNG or WebP face photo, at most 20 MiB. Downloaded asynchronously by media-analyzer; at least 256 KiB/s is required in every 15-second body window. trim_start: type: number minimum: 0 maximum: 999999999.999 description: Start offset in seconds in the source video. trim_end: type: number minimum: 0 maximum: 999999999.999 description: End offset in seconds. The selected duration must be 1–30 seconds; the end is clamped to the actual video length. auto_start: type: boolean default: true description: With true, a single person or an explicit person selection starts the paid render even with a small face. Pass false to review face_small, photo_face_small and the quote before calling /start. HeadSwapVideoPerson: type: object required: [id, face_px, face_small] properties: id: type: [integer, string] description: Person identifier within this job. Send it to select_person. thumb: type: [string, "null"] description: Face thumbnail as a data URI, when available. share: type: number description: Fraction of sampled frames containing this person. recognized: type: boolean description: Recognition indicator. You can also choose a person whose value is false. face_px: type: [integer, "null"] description: Smallest measured median face height on the render canvas across this person's plain and mask shots, rounded down to whole pixels. Null when none of those shots has a measurement. face_small: type: boolean description: True when a measured median is below the recommended 220 pixels. False when the size is unknown. A small face can still be chosen and rendered at the usual price. HeadSwapVideoResponse: type: object required: [id, status] description: Compact response with fields for the current state only. Includes progress while active, result_url when completed, price/people/photo_face_px/photo_face_small when choosing, and price, face_px, face_small, photo_face_px, photo_face_small and any blocking reason when ready. Failures include error details. Paid queued, processing, completed and failed jobs include the charged price. failed also includes refunded. no_faces returns only id and status. properties: id: type: string format: uuid status: type: string enum: [analyzing, analysis_failed, no_faces, choosing_person, ready, queued, processing, completed, failed] progress: type: number minimum: 0 maximum: 100 description: Only in analyzing, queued or processing. result_url: type: [string, "null"] description: Result video URL once completed. error_details: type: object required: [code, message] additionalProperties: false description: Present only in analysis_failed or failed. Contains an allowed code, its fixed public message and the affected input for media errors. properties: code: type: string enum: [INVALID_URL, DOWNLOAD_FAILED, FILE_TOO_LARGE, INVALID_MEDIA, TRIM_OUT_OF_RANGE, SERVICE_UNAVAILABLE, ANALYSIS_FAILED, FACE_REJECTED, CONTENT_POLICY, RENDER_FAILED] description: Media error codes cover rejected URLs, download failures, file size, invalid or unsupported files, trim range and temporary service capacity. Other analysis failures use ANALYSIS_FAILED. In failed, FACE_REJECTED indicates a rejected face photo and CONTENT_POLICY indicates a content policy rejection. Other rendering failures, including unclassified and legacy failures, use RENDER_FAILED. Use refunded to check the actual refund and retryable for analysis retries. input: type: string enum: [face, video] description: Affected input for media errors; omitted when unavailable or for other failures. message: type: string maxLength: 500 description: Fixed public message selected by code; never taken from stored diagnostics or exception messages. blocked_reason: type: string enum: [NO_CREDITS, RENDER_CONCURRENT] description: Only in ready when a paid start was refused. face_px: type: [integer, "null"] description: Only in ready. Smallest measured median face height on the render canvas across the chosen person's plain and mask shots, rounded down to whole pixels. Null when unknown. face_small: type: boolean description: Only in ready. True when the chosen person's measured face height falls below the 220 px recommendation in any swapped shot. False when unknown. photo_face_px: type: [integer, "null"] description: Only in choosing_person and ready. Height in pixels of the largest face on the face photo, measured by the photo check. Null when unknown. photo_face_small: type: boolean description: Only in choosing_person and ready. True when the face on the photo is below the recommended 160 px. False when unknown. A small photo face can still be rendered at the usual price. required_credits: type: number description: Only for a blocked ready job. Total required credits, not the balance shortfall. retryable: type: boolean description: Only in analysis_failed. Whether the same inputs may be retried within the remaining attempt budget; balance, cooldown and concurrent analysis limits still apply. The Retry-After header indicates the cooldown. Permanent failures require changed URLs. Retries do not consume hourly or daily creation quotas. price: type: number description: Quote in credits in the unpaid choosing_person and ready states. After a charge, also present in queued, processing, completed and failed, including automatic starts. This is the original amount charged and remains unchanged after a refund. Omitted for unpaid legacy rendering records. refunded: type: boolean description: Only in failed. True if the charged credits have actually been returned; false otherwise, including failures without a charge. Face-photo and content-policy rejections may not be refunded under the existing refund limits. Do not infer a refund from the error code. people: type: array description: Present only in choosing_person; thumbnails are not repeated during rendering or after completion. items: $ref: "#/components/schemas/HeadSwapVideoPerson" HeadSwapVideoError: type: object required: [error] properties: error: type: string enum: [NOT_AUTHORIZED, NOT_FOUND, INVALID_VIDEO_URL, INVALID_FACE_URL, INVALID, INVALID_PERSON, INVALID_AUTO_START, NOT_READY, NO_CREDITS, ANALYSIS_CONCURRENT, ANALYSIS_HOURLY, ANALYSIS_DAILY, RENDER_CONCURRENT, ANALYSIS_COOLDOWN, ANALYSIS_RETRY_LIMIT, NOT_RETRYABLE] details: type: array items: type: string blocked_reason: type: [string, "null"] required_credits: type: [number, "null"] retry_after: type: [integer, "null"] AnimationRequest: type: object properties: source_image: type: string description: Base64 encoded data URI in jpeg, png, or webp format (e.g., data:image/jpeg;base64,/9j/4AAQ...). Required unless `parent_id` is supplied; ignored when `parent_id` is supplied (the parent's last video frame is always used as input). template_id: type: integer description: ID of the animation template to use. Get available templates from /animation_templates endpoint. Combo templates cost 14 credits instead of 7. Optional when `parent_id` is supplied (defaults to the parent's template; pass a different one to switch styles); otherwise required. quality: type: string description: "Output quality. `sd` (default) renders up to 480x640; `hd` renders up to 720x1280 (source aspect ratio preserved) and costs 2x the template price (see `price_hd` in `/api/v1/animation_templates`). Omit for backward-compatible SD. Inherited from the parent and ignored when `parent_id` is supplied." enum: [sd, hd] default: sd preset_id: type: integer description: "Deprecated: use template_id instead. ID of the animation template." parent_id: type: string description: ID of a previous Animation to continue. The new clip is concatenated to the parent's video. The parent's last video frame is always used as the source (any `source_image` is ignored). `template_id` is optional and defaults to the parent's template. Parent must be less than 24 hours old and have a saved last frame. undress_before_animation: type: boolean description: "When `true`, the photo is first undressed (Premium v3, 3 credits, charged separately; an internal step, hidden from the undress history on the website) and the animation runs on the undressed result. Only honored for templates whose `undress_before_animation` flag is `true` (see `/api/v1/animation_templates`), and only on a fresh animation (ignored when `parent_id` is supplied). Requires `image_url` + `person_id` instead of `source_image` — see the Persons Analysis API." image_url: type: string format: uri description: "Required when `undress_before_animation` is `true`. HTTPS URL of the source image (jpeg, png, or webp, max 12 MB) — the same URL submitted to `POST /api/v1/persons/analyze`. Replaces `source_image` for the undress-before-animation flow; `source_image` is ignored when `image_url`/`person_id` are present." person_id: type: string description: "Required when `undress_before_animation` is `true`. Identifier of the person to undress, taken from a `completed` `GET /api/v1/persons/analyze/{id}` result owned by the caller and still within the 3-hour cache window. Must belong to an analysis of the same `image_url`." person_gender: type: string description: "Override the detector's gender for the undressed person. Only used in the undress-before-animation flow. Case-insensitive." enum: [male, female] body_shape: type: string description: "Body figure for the undress step (female persons only). Only used in the undress-before-animation flow. `as_in_photo` lets the AI keep what it sees." enum: [as_in_photo, fat, skinny, athletic] boobs: type: string description: "Breast size for the undress step (female persons only). Only used in the undress-before-animation flow. `as_in_photo` lets the AI decide." enum: [as_in_photo, small, large, huge] AnimationResponse: type: object properties: id: type: string description: Identifier for the animation job. AnimationResultResponse: type: object properties: status: type: string description: Status of the animation job. enum: [pending, completed, failed] result: type: string description: URL of the generated video, if the job is completed. error_details: type: object description: Error information when the animation failed due to image analysis. Only present when status is "failed" and the failure was caused by content analysis (underage person detected). properties: code: type: string description: Error code indicating the failure reason. enum: [face.child] underage_persons: type: array description: Detected underage persons with age and bounding box coordinates. Only present when code is "face.child". items: type: object properties: age: type: number description: Estimated age of the detected person. face: type: object description: Bounding box coordinates of the detected face. properties: x1: type: integer x2: type: integer y1: type: integer y2: type: integer body: type: object description: Bounding box coordinates of the detected body. properties: x1: type: integer x2: type: integer y1: type: integer y2: type: integer message: type: string description: "English sentence for the rejection, the same the website shows: `Person under 21 detected. Blocked due to a Terms of Use violation.` (code `face.child`) or `Face not found.` (code `no_face_found`). Only present for these rejections." AnimationTemplateListResponse: type: array items: type: object properties: id: type: integer description: Template ID to use with the animation API. name: type: string description: English name of the template. name_de: type: string description: German name (falls back to English if not set). name_es: type: string description: Spanish name (falls back to English if not set). name_pt: type: string description: Portuguese name (falls back to English if not set). name_fr: type: string description: French name (falls back to English if not set). name_ru: type: string description: Russian name (falls back to English if not set). name_zh: type: string description: Chinese name (falls back to English if not set). combo: type: boolean description: Whether this is a combo template (combines two templates). price: type: integer description: SD credit cost for this template (7 for standard, 14 for combo). price_hd: type: integer description: HD credit cost for this template (2x `price`; 14 for standard, 28 for combo). undress_before_animation: type: boolean description: "Whether this template supports the optional \"undress before animation\" step. When `true`, you may pass `undress_before_animation: true` (with `image_url` + `person_id`) to `POST /api/v1/animations`." UndressFaceSwapVideoRequest: type: object required: - undress_id properties: undress_id: type: string description: ID of a completed `video`-style Undress owned by the caller. UndressFaceSwapVideoResponse: type: object properties: id: type: string description: Identifier of the UndressFaceSwapVideo record. face_swap_video_id: type: string description: Identifier of the underlying face swap video job; poll `/face_swap_videos/{id}` for processing status. undress_id: type: string description: Identifier of the source video-style Undress. undress_result_id: type: string nullable: true description: Identifier of the resulting Undress once the face swap completes. `null` while processing. parameters: HeadSwapVideoId: name: id in: path required: true description: Job ID belonging to the authenticated user. schema: type: string format: uuid responses: HeadSwapVideoStatus: description: Current job status. Poll every five seconds while analysis or rendering is in progress. headers: Retry-After: description: Remaining manual retry cooldown in seconds, when applicable. schema: type: integer content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoResponse" HeadSwapVideoUnauthorized: description: Missing or invalid API key (NOT_AUTHORIZED). content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoError" HeadSwapVideoNotFound: description: Job not found or belongs to another user (NOT_FOUND). content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoError" HeadSwapVideoInvalid: description: Invalid input, invalid person selection, job not ready, or insufficient credits. No new render is charged on refusal. content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoError" HeadSwapVideoRateLimited: description: Per-user limit or retry cooldown reached. At most 2 active analyses, 10 new jobs per hour, 40 per day and 2 active renders, shared with the website. New jobs count even if downloading fails; retries do not consume creation quotas. No new render is charged on refusal. headers: Retry-After: description: Wait in seconds. For concurrency limits this is a polling suggestion; it does not reserve a slot. schema: type: integer content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoError" FaceSwapVideoAttemptLimit: description: RATE_LIMITED. Create and analyze share 10 attempts per user per minute, including invalid and zero-credit requests, checked before DNS. headers: Retry-After: description: Wait 60 seconds before trying again. schema: type: integer const: 60 content: application/json: schema: type: object properties: error: type: string const: RATE_LIMITED retry_after: type: integer security: - bearerAuth: [] paths: /api/v1/undress: post: summary: Create an undress job operationId: createUndress requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UndressRequest" responses: "200": description: Job created successfully. content: application/json: schema: $ref: "#/components/schemas/UndressResponse" "400": description: Invalid parameters, no credits, expired parent, or too many retries. content: application/json: schema: type: object properties: error: type: string enum: [no_credits, invalid_params, too_many_retries, parent_expired, internal_server_error, file_too_large] message: type: string description: "English sentence, the same the website shows: `File is too large. Maximum size is N MB.` (the limit of the mode: 20 MB for a base64 photo, 10 MB for an animation photo, 12 MB for an `image_url`). Only present when `error` is `file_too_large`." errors: type: array description: Validation error messages. Only present when `error` is `invalid_params`. items: type: string /api/v1/persons/analyze: post: summary: Queue a person-detection analysis for an image URL description: "Detects persons on the image at `image_url` and returns an analysis id. Rate limited to 15 requests per minute per API key. Results are cached for 3 hours. Poll `GET /api/v1/persons/analyze/{id}` for the outcome." operationId: createPersonsAnalysis requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PersonsAnalyzeRequest" responses: "201": description: Analysis queued. content: application/json: schema: $ref: "#/components/schemas/PersonsAnalyzeResponse" "400": description: "Invalid parameters (missing `image_url`, non-HTTPS URL, or malformed URL)." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": description: Rate limit exceeded (more than 15 analyses per minute for this API key). content: application/json: schema: type: object properties: error: type: string example: rate_limited retry_after: type: integer description: Seconds until the next minute window, after which new requests will succeed. /api/v1/persons/analyze/{id}: get: summary: Get a persons-analysis result description: "Returns `pending` while the detector is running, `completed` with the persons list when done, or `failed` with a `details` code. A `completed` response with an empty `persons` array means the image had no recognized persons (not a failure). Returns 404 after the 3-hour cache TTL expires or if the id was not created by the caller." operationId: getPersonsAnalysis parameters: - name: id in: path required: true schema: type: string description: Analysis id returned by `POST /api/v1/persons/analyze`. responses: "200": description: Current status of the analysis. content: application/json: schema: $ref: "#/components/schemas/PersonsAnalysisStatusResponse" "404": description: Analysis not found, expired, or not owned by the caller. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v3/undress: post: summary: Create a premium v3 undress job (explicit person selection) description: "Premium v3 — 5 credits, always auto-masks, always requires an explicit person selected via `POST /api/v1/persons/analyze`. Pass back the exact `image_url` you analyzed plus the `person_id` from the analysis result." operationId: createUndressV3 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UndressV3Request" responses: "201": description: Job created successfully. content: application/json: schema: $ref: "#/components/schemas/UndressResponse" "400": description: "Invalid parameters, invalid/expired/foreign person_id, image URL unreachable, underage subject, or insufficient credits." content: application/json: schema: type: object properties: error: type: string enum: [invalid_params, invalid_person_id, image_fetch_failed, under_age, no_credits, file_too_large] message: type: string description: "English sentence: `Person under 21 detected. Blocked due to a Terms of Use violation.` for `under_age`, `File is too large. Maximum size is 12 MB.` for `file_too_large`." errors: type: array description: Validation error messages. Only present when `error` is `invalid_params`. items: type: string /api/v3/undress/{id}: get: summary: Get the result of a premium v3 undress job operationId: getUndressV3Result parameters: - name: id in: path required: true schema: type: string description: Identifier of the undress job. responses: "200": description: Status or result of the undress job (same shape as `GET /api/v1/undress/{id}`). content: application/json: schema: $ref: "#/components/schemas/UndressResultResponse" "404": description: Job not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v3/undress/{id}/regenerate: post: summary: Regenerate a premium v3 undress for free (once per parent, 24 hours) description: "Creates a new premium v3 undress using the same source image and selected person as the parent, with a different random seed. Completely free — no credits are charged. Exactly one free regeneration is allowed per parent. The parent must be a completed premium v3 undress less than 24 hours old. Poll the returned id via `GET /api/v3/undress/{id}`." operationId: regenerateUndressV3 parameters: - name: id in: path required: true schema: type: string description: Identifier of the parent premium v3 undress. responses: "201": description: Regeneration job created successfully. content: application/json: schema: $ref: "#/components/schemas/UndressResponse" "400": description: Regeneration not available for this parent. content: application/json: schema: type: object properties: error: type: string enum: [already_regenerated, parent_expired, parent_not_completed, not_v3, invalid_params] "404": description: Parent not found, or created by a different API key. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/face_swap_videos/analyze: post: summary: Analyze a video for face swap processing operationId: analyzeFaceSwapVideo description: Authenticated attempts are limited before DNS, sharing a 10-per-minute user budget with creation. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FaceSwapVideoAnalyzeRequest" responses: "200": description: Analysis completed successfully. content: application/json: schema: $ref: "#/components/schemas/FaceSwapVideoAnalyzeResponse" "422": description: Invalid URL (including private or unresolved hosts), or analysis failed due to video constraints. content: application/json: schema: type: object properties: error: type: string enum: [INVALID_VIDEO_URL, ANALYSIS_FAILED] example: "ANALYSIS_FAILED" details: oneOf: - type: string example: "too_large" - type: array items: type: string "500": description: Internal server error. "429": $ref: "#/components/responses/FaceSwapVideoAttemptLimit" /api/v1/face_swap_videos: post: summary: Create a face swap video job operationId: createFaceSwapVideo description: Authenticated attempts are limited before DNS, sharing a 10-per-minute user budget with analysis. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FaceSwapVideoRequest" multipart/form-data: schema: $ref: "#/components/schemas/FaceSwapVideoRequest" responses: "201": description: Job created successfully. content: application/json: schema: $ref: "#/components/schemas/FaceSwapVideoResponse" "422": description: Invalid parameters, files, URLs (including private or unresolved hosts), or insufficient credits. content: application/json: schema: type: object properties: error: type: string example: INVALID_FACE_URL details: type: array items: type: string "500": description: Internal server error. "429": $ref: "#/components/responses/FaceSwapVideoAttemptLimit" /api/v1/face_swap_videos/{id}: get: summary: Get the status of a face swap video job operationId: getFaceSwapVideoStatus parameters: - name: id in: path required: true schema: type: string description: Identifier of the face swap video job. responses: "200": description: Current status of the face swap video job. content: application/json: schema: $ref: "#/components/schemas/FaceSwapVideoStatusResponse" "404": description: Job not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error. /api/v1/head_swap_videos: post: summary: Create a Head Swap Video job operationId: createHeadSwapVideo description: Requires at least 10 credits for a new job. Downloads, DNS checks and analysis run in the background. With auto_start true (default), a single person starts a paid render regardless of face size. Multiple people require select_person. Pass auto_start false to review face_small, photo_face_small and price before calling /start. Analysis failures and no_faces do not charge. Rendering costs 10 credits per started 5 seconds, at most 60 credits. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoRequest" multipart/form-data: schema: $ref: "#/components/schemas/HeadSwapVideoRequest" responses: "201": description: Job created in analyzing status. Keep source URLs accessible until downloaded. content: application/json: schema: $ref: "#/components/schemas/HeadSwapVideoResponse" "401": $ref: "#/components/responses/HeadSwapVideoUnauthorized" "422": $ref: "#/components/responses/HeadSwapVideoInvalid" "429": $ref: "#/components/responses/HeadSwapVideoRateLimited" /api/v1/head_swap_videos/{id}: get: summary: Get Head Swap Video status and detected people operationId: getHeadSwapVideo parameters: - $ref: "#/components/parameters/HeadSwapVideoId" responses: "200": $ref: "#/components/responses/HeadSwapVideoStatus" "401": $ref: "#/components/responses/HeadSwapVideoUnauthorized" "404": $ref: "#/components/responses/HeadSwapVideoNotFound" /api/v1/head_swap_videos/{id}/select_person: post: summary: Choose a person and start the paid render operationId: selectHeadSwapVideoPerson description: Accepted in choosing_person or ready; any other state returns NOT_READY, and a missing or unknown person_id returns INVALID_PERSON. Only person_id is used; plan and price are calculated by the server. With auto_start false, saves the selection without charging. A blocked start preserves the selection. After a charge, repeating the same selection returns the current job without another charge; selecting another person is rejected. parameters: - $ref: "#/components/parameters/HeadSwapVideoId" requestBody: required: true content: application/json: schema: type: object required: [person_id] properties: person_id: type: [integer, string] description: ID from this job's people array. responses: "200": $ref: "#/components/responses/HeadSwapVideoStatus" "401": $ref: "#/components/responses/HeadSwapVideoUnauthorized" "404": $ref: "#/components/responses/HeadSwapVideoNotFound" "422": $ref: "#/components/responses/HeadSwapVideoInvalid" "429": $ref: "#/components/responses/HeadSwapVideoRateLimited" /api/v1/head_swap_videos/{id}/start: post: summary: Start a ready Head Swap Video explicitly or after a credit or concurrency refusal operationId: startHeadSwapVideo description: No body required. Confirms the paid render for the chosen person, including when face_small or photo_face_small is true. Repeating start after a charge returns the current status without another charge or render. parameters: - $ref: "#/components/parameters/HeadSwapVideoId" responses: "200": $ref: "#/components/responses/HeadSwapVideoStatus" "401": $ref: "#/components/responses/HeadSwapVideoUnauthorized" "404": $ref: "#/components/responses/HeadSwapVideoNotFound" "422": $ref: "#/components/responses/HeadSwapVideoInvalid" "429": $ref: "#/components/responses/HeadSwapVideoRateLimited" /api/v1/head_swap_videos/{id}/retry_analysis: post: summary: Retry failed Head Swap Video analysis operationId: retryHeadSwapVideoAnalysis description: Requires at least 10 credits and a free concurrent analysis slot. An unpaid analysis_failed job returns to analyzing. At most two manual retries per job, first 60 seconds after creation, second 120 seconds after the first retry. Failures consume this retry budget; retries do not consume or require hourly/daily creation quotas. Without a body, reuses files and any cut; optional changed URLs replace expired inputs and invalidate only the corresponding files. Permanent failures require changed URLs. URL replacement is rejected in other states; no-body calls leave those states unchanged. Does not restart paid renders or no_faces jobs. parameters: - $ref: "#/components/parameters/HeadSwapVideoId" requestBody: required: false content: application/json: schema: type: object properties: face_url: type: string format: uri description: Replacement public HTTPS face URL. Does not reset retry budgets. video_url: type: string format: uri description: Replacement public HTTPS video URL. Discards the previous source and cut. responses: "200": $ref: "#/components/responses/HeadSwapVideoStatus" "401": $ref: "#/components/responses/HeadSwapVideoUnauthorized" "404": $ref: "#/components/responses/HeadSwapVideoNotFound" "422": $ref: "#/components/responses/HeadSwapVideoInvalid" "429": $ref: "#/components/responses/HeadSwapVideoRateLimited" /api/v1/undress/{id}: get: summary: Get the result of an undress job operationId: getUndressResult parameters: - name: id in: path required: true schema: type: string description: Identifier of the undress job. responses: "200": description: Status or result of the undress job. content: application/json: schema: $ref: "#/components/schemas/UndressResultResponse" "404": description: Job not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/undress_face_swap_videos: post: summary: Run a free face swap over a completed video-style undress description: Applies only to completed `video`-style Undresses. Improves face consistency in the animated result; typically completes in 60–120 seconds. Poll `/undress_face_swap_videos/{id}` for status, then fetch the resulting video via `/undress/{undress_result_id}`. operationId: createUndressFaceSwapVideo requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UndressFaceSwapVideoRequest" responses: "200": description: Job created successfully. content: application/json: schema: $ref: "#/components/schemas/UndressFaceSwapVideoResponse" "404": description: Undress not found, not owned by the caller, or not a `video`-style undress. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Service failed to enqueue the face swap job. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/undress_face_swap_videos/{id}: get: summary: Get the status of an undress face swap video job operationId: getUndressFaceSwapVideo parameters: - name: id in: path required: true schema: type: string description: Identifier of the UndressFaceSwapVideo record. responses: "200": description: While processing, `undress_result_id` is `null`. Once populated, fetch the swapped result via `/undress/{undress_result_id}`. content: application/json: schema: $ref: "#/components/schemas/UndressFaceSwapVideoResponse" "404": description: Record not found or not owned by the caller. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/face_swaps: post: summary: Create a face swap job operationId: createFaceSwap requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FaceSwapRequest" responses: "200": description: Job created successfully. content: application/json: schema: $ref: "#/components/schemas/FaceSwapResponse" "400": description: Invalid parameters or no credits. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error. /api/v1/face_swaps/{id}: get: summary: Get the result of a face swap job operationId: getFaceSwapResult parameters: - name: id in: path required: true schema: type: string description: Identifier of the face swap job. responses: "200": description: Status or result of the face swap job. content: application/json: schema: $ref: "#/components/schemas/FaceSwapResultResponse" "404": description: Job not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/animations: post: summary: Create an animation job operationId: createAnimation requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AnimationRequest" responses: "200": description: Job created successfully. content: application/json: schema: $ref: "#/components/schemas/AnimationResponse" "400": description: "Invalid parameters, no credits, expired parent, analysis failed (child detected, no face found), or (undress-before-animation only) invalid person, image fetch failure, or underage subject." content: application/json: schema: type: object properties: error: type: string enum: [invalid_params, no_credits, analysis_failed, parent_expired, internal_server_error, invalid_person_id, image_fetch_failed, under_age, file_too_large] message: type: string description: "English sentence: `Person under 21 detected. Blocked due to a Terms of Use violation.` for `under_age` and an underage `analysis_failed`; `File is too large. Maximum size is N MB.` for `file_too_large` (10 MB for `source_image`, 12 MB for `image_url`)." errors: type: array items: type: string error_details: type: object description: Analysis failure details. Only present when error is "analysis_failed". properties: code: type: string enum: [face.child] underage_persons: type: array description: Detected underage persons. Only present when code is "face.child". items: type: object properties: age: type: number face: type: object properties: x1: type: integer x2: type: integer y1: type: integer y2: type: integer body: type: object properties: x1: type: integer x2: type: integer y1: type: integer y2: type: integer /api/v1/animations/{id}: get: summary: Get the result of an animation job operationId: getAnimationResult parameters: - name: id in: path required: true schema: type: string description: Identifier of the animation job. responses: "200": description: Status or result of the animation job. content: application/json: schema: $ref: "#/components/schemas/AnimationResultResponse" "404": description: Job not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/animation_templates: get: summary: List available animation templates operationId: listAnimationTemplates security: [] responses: "200": description: List of available animation templates. content: application/json: schema: $ref: "#/components/schemas/AnimationTemplateListResponse" /api/v1/animation_presets: get: summary: "Deprecated: use /api/v1/animation_templates instead" operationId: listAnimationPresets deprecated: true security: [] responses: "200": description: List of available animation templates (deprecated endpoint). content: application/json: schema: $ref: "#/components/schemas/AnimationTemplateListResponse"