{"openapi":"3.0.0","info":{"title":"A2E Developer API","description":"HeadSwap provides affordable, accessible, and flexible AI-powered media processing capabilities through RESTful APIs. Generate avatar videos, swap faces, clone voices, create images and videos from text or images, and much more.\n\n## Quickstart for AI Integration\n\nUse the machine-readable OpenAPI spec or download a generated SKILL.md for Cursor, MCP clients, and other AI agents.\n\n| Resource | URL |\n|----------|-----|\n| OpenAPI JSON | [`https://headswap.app/dev/openapi-spec`](https://headswap.app/dev/openapi-spec) |\n| SKILL.md | [`https://headswap.app/dev/skill`](https://headswap.app/dev/skill) |\n| Webhook receiver | [Receiving protocol](https://headswap.app/dev#description/webhook-receiving-protocol) |\n| Get API Token | [Account > API Token](https://headswap.app/account/token) |\n\n**3-step quickstart:**\n1. Create an API token in **Account > API Token**.\n2. Load the machine-readable OpenAPI spec from `https://headswap.app/dev/openapi-spec`\n3. Download the generated SKILL.md from `https://headswap.app/dev/skill`\n\n## Minimal image-to-video integration\n\n1. Call POST /api/v1/r2/upload-presigned-url with a unique key, contentType and the actual file size (or omit a size binding). Read data.uploadUrl and data.cdnUrl.\n2. PUT the actual file bytes to data.uploadUrl with the same Content-Type and, when bound, the actual Content-Length. Continue only after the PUT succeeds; use data.cdnUrl as image_url.\n3. Quote POST /api/v1/userImage2Video/start through POST /api/v1/generation/quote with endpoint and the exact requestBody: name, image_url, prompt, model_version=a2e, video_time=5. Continue only when code=0 and data.available=true. A quote does not reserve credits or validate access.\n4. Submit that same requestBody to POST /api/v1/userImage2Video/start. Check code and save data._id. A successful moderation response may have no task ID; do not poll such a response.\n5. Poll GET /api/v1/userImage2Video/{_id} at a modest interval, such as 10 seconds, until current_status is completed or failed. On completion, download result_url before expirationDate; on failure, surface failed_code and failed_message and consult hasRefundCoin rather than assuming a refund.\n\nExample generation body after replacing the accessible image_url:\n\n    {\"name\":\"API example\",\"image_url\":\"https://example.com/input.jpg\",\"prompt\":\"A gentle camera move\",\"model_version\":\"a2e\",\"video_time\":5}\n\nUse this exact object as requestBody when quoting and as the submission body. Replace the image URL with data.cdnUrl from your successful PUT; the placeholder image URL is not an uploaded asset.\n\nOther models use their documented ID, status, result and billing fields; do not apply this workflow's field names to every model. Quote, submission and final settlement are separate stages. The OpenAPI license metadata alone is not a license for hosted services, third-party models or generated outputs; consult their applicable terms.\n\n## Access Points\n\n| Environment | Base URL |\n|--------|----------|\n| Current Environment | `https://headswap.app` |\n\n## Authentication\n\nUse an **API token** for developer API calls.\nAPI tokens start with `sk_` and should be sent as a Bearer token in the `Authorization` header.\n\n### How to get an API token\n\n1. Sign in to `https://headswap.app`.\n2. Open **Account > API Token**.\n3. Create a new token and copy the generated value.\n4. Send it in the request header as `Authorization: Bearer sk_...`.\n\nJWT/session tokens used by the web app are not part of the public developer authentication flow and are not required in this documentation.\n\n```bash\ncurl -X POST \"https://headswap.app/api/v1/...\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"my-task\", \"prompt\": \"...\"}'\n```\n\n## Webhook receiving protocol\n\nFor generation operations that accept `webhook_url`, submit with an API token and an optional `webhook_token` (your shared secret). Browser/session requests cannot configure callbacks. The URL must normally be a public HTTPS address without URL credentials; private and reserved hosts/IPs are rejected, and the host is checked again before delivery. Local development has limited HTTP exceptions. The token is limited to 256 visible ASCII characters and is never returned in task details or callback bodies; `webhook_token_set` indicates whether one was configured.\n\nOn a terminal result, we make one best-effort HTTP POST to your URL with `Content-Type: application/json`. The JSON body is the formatted **task object itself**, not the detail API's `{code,data}` envelope and not `{event,data}`. Task fields vary by generation family; use the task ID and X-A2e-Event header as the common terminal signal. Most task families expose current_status (completed/failed/blocked; blocked is delivered as task.failed), while legacy Video exposes status (success/fail). Consult that family's detail operation for result fields. Some detail endpoints add computed fields that do not appear in callbacks. Event metadata is in headers:\n\n| Header | Value |\n|--------|-------|\n| `X-A2e-Event` | `task.completed` or `task.failed` |\n| `X-A2e-Task-Type` | Task family identifier; do not assume it equals an OpenAPI tag |\n| `X-A2e-Webhook-Token` | Your configured shared token, when supplied |\n\nFor a current_status task family, a minimal completed body: `{\"_id\":\"507f1f77bcf86cd799439011\",\"current_status\":\"completed\"}` with `X-A2e-Event: task.completed`. A minimal failed body for that family: `{\"_id\":\"507f1f77bcf86cd799439012\",\"current_status\":\"failed\"}` with `X-A2e-Event: task.failed`. These illustrate one task family; actual task objects contain family-specific fields. Check the shared token against your stored value and deduplicate by task ID before processing. No HMAC signature is sent.\n\nReturn any 2xx response after accepting the event. The sender times out after 5 seconds, does not follow redirects, and limits request and response bodies to 64 KiB. A non-2xx response, timeout, or delivery failure is **not retried**. Poll the task detail API to recover a missed event; the detail response is the source of truth. Callbacks are only attempted for eligible API-token tasks with a configured URL and are not sent for intermediate states.\n\n## Errors, retries, and task deletion\n\nRead both the HTTP status and JSON `code`. A normal `ctx.success` response is HTTP 200 with `code: 0`; a business error can be HTTP 200 with a nonzero `code` and `msg`. Other validation, authorization, missing-task, and server errors can use HTTP 4xx/5xx. Do not treat every HTTP 200 as a successful task submission. A top-level `trace_id`, when present, identifies the request for support and is not a task ID; include it with the HTTP status, code, and task ID when reporting a problem.\n\n| Condition | Client action |\n|-----------|---------------|\n| Invalid input, missing access, or insufficient balance (for example `100000`, `100004`, `20003`) | Fix the input, permissions, or balance before another submission. |\n| Task still processing (`30101`) | Poll its detail endpoint; do not resubmit or repeatedly DELETE. |\n| Task not found (`30104`) | Check the task ID, account, and whether it was deleted. |\n| Temporary HTTP 5xx or network failure on a read | Retry the read with bounded exponential backoff and jitter. |\n\nFor detail polling, start around 3–5 seconds and back off toward 30 seconds with jitter; this is client guidance, not a guaranteed service interval or request-rate allowance. Account-level generation concurrency and HTTP request-rate limits are separate controls. Follow an explicit `Retry-After` if one is returned. Avoid simultaneous polling bursts across many tasks.\n\nPaid creation POSTs have no documented idempotency-key guarantee. If a POST times out or its response is lost, the task may already exist and have been charged. Do not automatically replay it: first reconcile recent task/list and billing records using the submitted time and task details, then decide whether a new submission is needed. A repeated POST can create and charge for a second task.\n\nDELETE is not a universal cancellation operation. The task families below follow different code paths; a 200 DELETE response does not by itself promise cancellation, immediate physical media removal, or a refund.\n\n| Task family | Allowed state and window | Deletion and refund |\n|-------------|--------------------------|---------------------|\n| Head Swap, Image to Video, Face Swap Task, and other media tasks using the shared task-delete path | initialized only after at least 60 seconds from creation; completed, failed, blocked (including legacy block) at any time. sent, pending, and processing are rejected. | Soft-delete; refund only a qualifying queued initialized task. |\n| Video Twin | initialized only after 60 seconds; completed or failed at any time. Other states are rejected. | Soft-delete; refund an eligible queued task or a record with a pending billing refund. |\n| Photobook | initialized, completed, or failed, subject to an in-flight claim check; no fixed 60-second rule. | Soft-delete; refund initialized or pending-refund records. |\n| Sora 2 Pro | sent, pending, and processing are rejected; no fixed 60-second rule for initialized. | Soft-delete; refund initialized if it has not already been refunded. |\n| GPT Image, Flux 2, Kling Image, Qwen Image, Wan 2.6/2.7 Image | No processing-state gate in the history-delete path. | Set deleted=true; no cancellation or refund in that path. |\n| Kling Video, Kling Omni, Seedance 1.5/2.0 | No processing-state gate in the owned-record delete path. | Soft-delete; no cancellation or refund in that path. |\n\nOther DELETE endpoints, including voice and asset records, have their own lifecycle rules. Read each operation description before applying a task-family rule to it.\n\n## FAQ\n\n**What is the SLA?**\nNo measured uptime period or contractual SLA is published in this reference. Consult the current service terms and support for availability commitments.\n\n**Is there a free tier?**\nSignup credit eligibility and amounts depend on current site settings. Credits do not grant access to every model: paid-access rules still apply, and an API token does not bypass them. Browser-only quotas are not automatically available to API-token requests. Check current pricing and the generation response before treating an operation as free.\n","version":"1.0.0","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://headswap.app","description":"Current Environment"}],"paths":{"/api/v1/r2/get_upload_presigned_url":{"post":{"summary":"Get pre-signed upload URL","description":"Legacy endpoint for generating a pre-signed R2 PUT URL.\nPrefer /api/v1/r2/upload-presigned-url for new integrations.\nIf bucket is omitted, files are uploaded to 3days-apac by default.\nurlPrefix changes the leading object-key path and defaults to adam2eve.\ncdnDomain changes the CDN domain suffix and defaults to the existing makefun.ai behavior.\nThe returned key is scoped to {urlPrefix}/{env}/user/{user_id}/.\nPUT upload contract (also applies to the legacy alias):\n- Only the A2E request for this URL uses Authorization: Bearer. Send the raw file bytes to uploadUrl with HTTP PUT; do not use JSON or multipart/form-data.\n- The uploadUrl query already authenticates the PUT. Use a separate unauthenticated HTTP client: do not forward Authorization or manually add x-amz-* headers.\n- Send Content-Type matching the requested contentType. Preserve the complete uploadUrl, including all query bytes and its R2 host; do not rewrite it to cdnUrl.\n- fileSize and contentLength are optional outside site runtimes. Omit them for a minimal upload; never copy a placeholder byte count.\n- If you provide a positive integer size, Content-Length must equal that actual file byte count. Outside site runtimes, contentLength takes priority over fileSize; site runtimes ignore contentLength and always bind the PUT to the validated fileSize. A chunked request without that bound Content-Length will fail.\n- Site runtimes can require fileSize; use the actual byte count there. expiresIn is URL validity, not object retention. Use cdnUrl only after PUT succeeds.\nTwo-step cURL example (requires curl and jq):\n```sh\ncurl -X POST \"https://headswap.app/api/v1/r2/get_upload_presigned_url\" \\\n  -H 'Authorization: Bearer YOUR_A2E_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"key\":\"upload.png\",\"purpose\":\"STAGING\",\"contentType\":\"image/png\",\"expiresIn\":300}' \\\n  --fail-with-body --output /tmp/a2e-upload-response.json\nupload_url=$(jq -er '.data.uploadUrl' /tmp/a2e-upload-response.json)\ncurl -X PUT \"$upload_url\" -H 'Content-Type: image/png' \\\n  --data-binary @upload.png --fail-with-body\n```\nReplace YOUR_A2E_API_KEY and upload.png with your own API key and file.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `key`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/r2/upload-presigned-url` — Get pre-signed upload URL.","tags":["Miscellaneous"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"key parameter","example":"example_key"},"bucket":{"type":"string","deprecated":true,"description":"R2 bucket. Defaults to 3days-apac. Deprecated, use purpose instead.","example":"3days-apac"},"purpose":{"type":"string","enum":["STAGING","RESULT_SHORT","RESULT","SHORT_CACHE"],"description":"Storage purpose. The backend maps it to the physical bucket. Ignored when bucket is provided.","example":"STAGING"},"urlPrefix":{"type":"string","description":"Leading object-key path. Defaults to adam2eve.","example":"adam2eve"},"cdnDomain":{"type":"string","description":"CDN domain suffix without scheme or path. Defaults to the existing makefun.ai behavior.","example":"makefun.ai"},"expiresIn":{"type":"integer","minimum":60,"maximum":600,"default":300,"description":"Upload URL validity in seconds","example":60},"contentType":{"type":"string","description":"MIME type to bind to the upload request.","example":"image/png"},"fileSize":{"type":"number","description":"Optional actual file size in bytes. A positive safe integer binds Content-Length; the PUT must send exactly this many raw bytes.","example":1},"contentLength":{"type":"number","description":"Optional actual Content-Length in bytes. A positive safe integer binds the PUT length; takes priority over fileSize outside site runtimes. Site runtimes ignore it and sign with fileSize.","example":1}},"required":["key"],"example":{"key":"example_key"}},"example":{"key":"upload.png","purpose":"STAGING","expiresIn":60,"contentType":"image/png"}}}},"responses":{"200":{"description":"Item retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/R2UploadPresignedUrlResponse"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1R2GetUploadPresignedUrl","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/r2/get_upload_presigned_url\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"key\": \"upload.png\",\n  \"purpose\": \"STAGING\",\n  \"expiresIn\": 60,\n  \"contentType\": \"image/png\"\n}'"}]}},"/api/v1/generation/quote":{"post":{"summary":"Estimate generation credit consumption","description":"Returns a credit estimate without creating a task, calling a generation provider, or charging credits.\nFor agent use, send `endpoint` plus the exact `requestBody` intended for that generation endpoint.\nOnly pricing-related fields are interpreted; a successful quote does not validate the complete generation request.\nThe legacy normalized quote body remains supported for backward compatibility.\nCore first-last-frame video quotes preserve the requested batch size (`requestBody.number_of_images`, or legacy `count`) and multiply the per-output price by that count, matching generation billing.\nUnlimited mode still quotes one output; its video price is zero and optional V1 auto-audio is charged once. V2 models do not support Unlimited mode.\nOnly supported generation endpoints can be quoted. `/api/v1/seedAudio/generate` and `/api/v1/seedAudio/start` do not support advance quotes because the actual output duration is only known after generation.\nSeed Audio reserves 120 credits at submission and settles against the actual output duration after success; the reservation is not an estimate of the final charge. Explain the billing rules and obtain the user's acceptance before submitting generation directly.\nHTTP 400 with `code=UNSUPPORTED_GENERATION_QUOTE_ENDPOINT` is a non-retryable capability response, not a generation failure. Do not repeatedly request a quote for the same unsupported endpoint.\nFor A2E/Qwen image generation, include the output `width` and `height` as well as `resolution`.\nFor `/api/v1/talkingVideo/start`, include `input_audio_duration` in `requestBody` to quote the source audio length; `input_video_duration` does not price this operation.\nIn the legacy normalized quote body, use `inputAudioDuration` for Talking Video. `inputVideoDuration` remains accepted as a legacy alias and is interpreted as audio duration for that mode.\n`/api/v1/imageBackgroundRemoval/start` uses GPT Image 2.5 Flare pricing at the requested `resolution` (default `1K`).\nQuotes use the same dimension-based resolution promotion as task creation; supported A2E tiers are `1K`, `1080P`, and `2K`.\nA quote is not a task, entitlement approval, balance reservation, or payment. Even available=true/generationRequestValidated=false does not guarantee submission will be accepted. Use /api/v1/feature-pricing for the current configured price source; user role and current site basic settings determine access. API tokens do not bypass paid-access gates. Free signup credits do not grant access to every model.\nFor duration-priced media operations, include the measured source duration (input_audio_duration for talkingVideo, input_video_duration for video transforms). HTTP 200 with available=false must be resolved before submission.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Unsupported endpoint or invalid pricing combinations. Missing duration may instead return HTTP 200 with available=false; inspect data.available.\n- `401` — Missing or invalid bearer token.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Use endpoint plus requestBody, OR a legacy normalized body with mode. Endpoint/requestBody takes precedence when supplied.","properties":{"endpoint":{"type":"string","description":"Generation route path. A leading `POST ` is accepted but optional.","example":"/api/v1/userWan25/start"},"requestBody":{"type":"object","additionalProperties":true,"description":"The exact JSON body intended for the generation request.","example":{}},"count":{"type":"integer","minimum":1,"maximum":8,"example":1},"mode":{"type":"string","enum":["text-to-video","image-to-video","text-to-image","image-edit","upscale","caption-removal","face-swap","head-swap","actor-swap","virtual-try-on","talking-photo","talking-video","product-avatar","photobook","video-to-audio"],"example":"text-to-video"},"model":{"type":"string","description":"Required for video/image model modes. Prefer endpoint/requestBody instead of guessing normalized model names.","example":"example"},"workflow":{"type":"string","example":"example"},"duration":{"type":"number","example":5},"resolution":{"type":"string","example":"example"},"ratio":{"type":"string","example":"example"},"quality":{"type":"string","example":"example"},"size":{"type":"string","example":"example"},"audio":{"type":"boolean","example":false},"inputVideoDuration":{"type":"number","minimum":0,"example":0},"inputAudioDuration":{"type":"number","minimum":0,"example":0},"referenceVideoDurations":{"type":"array","items":{"type":"number","example":5},"example":[5]},"inputImageCount":{"type":"integer","minimum":0,"example":0},"modelVersion":{"type":"string","example":"example"},"mediaType":{"type":"string","enum":["image","video"],"example":"image"},"totalCount":{"type":"integer","minimum":4,"maximum":16,"example":4},"autoAddAudio":{"type":"boolean","example":false},"unlimited":{"type":"boolean","example":false},"hasVideoInput":{"type":"boolean","example":false},"hasEndFrame":{"type":"boolean","example":false},"googleSearch":{"type":"boolean","example":false},"inputVideoCount":{"type":"integer","minimum":0,"maximum":3,"example":0},"characterOrientation":{"type":"string","description":"Kling motion-control character orientation.","example":"example"},"mediakitToolVersion":{"type":"string","enum":["standard","professional"],"example":"standard"},"mediakitResolution":{"type":"string","enum":["1080p","2k"],"example":"1080p"}},"anyOf":[{"required":["endpoint","requestBody"]},{"required":["mode"],"not":{"anyOf":[{"required":["endpoint"]},{"required":["requestBody"]}]}}],"example":{"endpoint":"/api/v1/userWan25/start","requestBody":{}}},"examples":{"generationRequest":{"value":{"endpoint":"/api/v1/userImage2Video/start","requestBody":{"name":"Quote example","prompt":"A gentle camera move","image_url":"https://example.com/image.jpg","model_version":"a2e","video_time":5}}},"legacyNormalized":{"value":{"mode":"image-to-video","model":"core","duration":5,"count":1}}}}}},"responses":{"200":{"description":"Estimate result. HTTP 200 with available=false and coins=null means no usable estimate, never a free generation.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["available","coins","perOutputCoins","count"],"properties":{"available":{"type":"boolean"},"coins":{"type":"number","nullable":true,"minimum":0},"perOutputCoins":{"type":"number","nullable":true,"minimum":0},"count":{"type":"integer","minimum":1},"exact":{"type":"boolean","description":"Present for endpoint/requestBody form only. Pricing exactness does not validate the complete generation request."},"generationRequestValidated":{"type":"boolean","enum":[false],"description":"Present for endpoint/requestBody form; quote only interprets pricing inputs."},"inputFormat":{"type":"string","enum":["generation_request"]},"endpoint":{"type":"string"},"unavailableReason":{"type":"string"},"missingPricingFields":{"type":"array","items":{"type":"string"}},"freeQuotaApplied":{"type":"boolean","description":"Optional web-account quota result; API-token requests do not inherit browser-only quota."},"freeVideoDurationSeconds":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"examples":{"available":{"value":{"code":0,"data":{"available":true,"coins":30,"perOutputCoins":30,"count":1,"inputFormat":"generation_request","endpoint":"POST /api/v1/userImage2Video/start","exact":true,"generationRequestValidated":false}}},"missingDuration":{"value":{"code":0,"data":{"available":false,"coins":null,"perOutputCoins":null,"count":1,"inputFormat":"generation_request","endpoint":"POST /api/v1/talkingVideo/start","exact":false,"generationRequestValidated":false,"unavailableReason":"pricing_input_required","missingPricingFields":["requestBody.input_audio_duration"]}}}},"example":{"code":0,"data":{"available":false,"coins":0,"perOutputCoins":0,"count":1,"exact":false,"generationRequestValidated":false,"inputFormat":"generation_request","endpoint":"example","unavailableReason":"example","missingPricingFields":["example"],"freeQuotaApplied":false,"freeVideoDurationSeconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Unsupported endpoint or invalid pricing combinations. Missing duration may instead return HTTP 200 with available=false; inspect data.available."},"401":{"description":"Missing or invalid bearer token"}},"operationId":"postApiV1GenerationQuote","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/generation/quote\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"endpoint\": \"/api/v1/userImage2Video/start\",\n  \"requestBody\": {\n    \"name\": \"Quote example\",\n    \"prompt\": \"A gentle camera move\",\n    \"image_url\": \"https://example.com/image.jpg\",\n    \"model_version\": \"a2e\",\n    \"video_time\": 5\n  }\n}'"}]}},"/api/v1/anchor/list":{"post":{"summary":"List available avatars","description":"Returns the system and user-specific avatars available to the authenticated API user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Generate Avatar Videos"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"web_type":{"type":"string","description":"Optional client type. Use a2e or tyzn to include default system avatars alongside user-specific avatars.","enum":["a2e","tyzn"],"example":"a2e"}},"required":[],"example":{}},"example":{"web_type":"a2e"}}}},"responses":{"200":{"description":"Operation completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarListResponse"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1AnchorList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/anchor/list\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"web_type\": \"a2e\"\n}'"}]}},"/api/v1/share/downloadUrl":{"get":{"summary":"Get a downloadable video URL from a share link","description":"Accepts a complete /share-result/{shareId} link. Returns the current result video URL for a completed, unexpired shared task without downloading media through this API. The returned URL may expire; save the file before expires_at when present. Image shares, expired shares, and results without a video URL return an error.\n### Request\n- This operation does not declare bearer authentication in the published specification.\n- Supported query parameters: `share_url`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Reads the requested information without creating a generation task.\n- Use the returned fields as documented; availability may depend on the caller and current resource state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Malformed or unsupported share link.\n- `404` — Shared video is missing, unavailable, or expired.","tags":["Miscellaneous"],"security":[],"responses":{"200":{"description":"Download URL returned.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"download_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time","nullable":true}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"download_url":"https://example.com/file","expires_at":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Malformed or unsupported share link."},"404":{"description":"Shared video is missing, unavailable, or expired."}},"parameters":[{"name":"share_url","in":"query","required":true,"schema":{"type":"string","example":"https://example.com/file"},"description":"Complete share-result link issued by this service."}],"operationId":"getApiV1ShareDownloadUrl","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/share/downloadUrl?share_url=https%3A%2F%2Fexample.com%2Ffile\""}]}},"/api/v1/anchor/tts_list":{"post":{"summary":"List system voices (TTS presets)","description":"List available system TTS voices/presets for the current user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/anchor/language_list` — List supported languages/regions for voices.\n- `POST /api/v1/anchor/voice_list` — List available voices by country/region.\n- `GET /api/v1/anchor/voice_list` — List available voices (GET)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Voice preset list","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","description":"Voice preset list","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"children":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"children":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"children":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string","description":"TTS preset id"},"chinese_val_3":{"type":"string"},"english_val_3":{"type":"string"},"user_id":{"type":"string","nullable":true}}}}}}}}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"label":"example","value":"example","children":[{"label":"example","value":"example","children":[{"label":"example","value":"example","children":[{"label":"example","value":"example","chinese_val_3":"example","english_val_3":"example","user_id":"507f1f77bcf86cd799439011"}]}]}]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1AnchorTtsList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/anchor/tts_list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/anchor/language_list":{"post":{"summary":"List supported languages/regions for voices","description":"List supported language and region options. Optional `voice_map_type` changes display labels; it does not filter the returned locales.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/anchor/tts_list` — List system voices (TTS presets)\n- `POST /api/v1/anchor/voice_list` — List available voices by country/region.\n- `GET /api/v1/anchor/voice_list` — List available voices (GET)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"voice_map_type":{"type":"string","description":"Display-label language mapping (e.g. zh-CN, pt-BR, ja-JP); omitted or other values use English labels. The locale set is unchanged.","example":"en-US"}},"required":[],"example":{}},"example":{"voice_map_type":"en-US"}}}},"responses":{"200":{"description":"Language/region list","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"data":{"type":"array","description":"Language/region list","items":{"type":"object","required":["label","value","children"],"properties":{"label":{"type":"string","example":"English"},"value":{"type":"string","example":"en"},"children":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","example":"United States"},"value":{"type":"string","example":"US"}}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"label":"English","value":"en","children":[{"label":"United States","value":"US"}]}]}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1AnchorLanguageList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/anchor/language_list\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"voice_map_type\": \"en-US\"\n}'"}]}},"/api/v1/anchor/voice_list":{"post":{"summary":"List available voices by country/region","description":"List available voices filtered by `country`, `region`, and `voice_map_type`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/anchor/tts_list` — List system voices (TTS presets)\n- `POST /api/v1/anchor/language_list` — List supported languages/regions for voices.\n- `GET /api/v1/anchor/voice_list` — List available voices (GET)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"Country/language code (default en)","example":"en"},"region":{"type":"string","description":"Region code (default US)","example":"US"},"voice_map_type":{"type":"string","description":"Locale mapping type (default en-US)","example":"en-US"}},"required":[],"example":{}},"example":{"country":"en","region":"US","voice_map_type":"en-US"}}}},"responses":{"200":{"description":"Voice list","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","description":"Voices grouped by gender, with current account billing rates from the dynamic price catalog.","items":{"type":"object","properties":{"value":{"type":"string","description":"Gender group value"},"label":{"type":"string","description":"Localized gender group label"},"children":{"type":"array","items":{"type":"object","required":["value","label","ttsRate"],"properties":{"value":{"type":"string","description":"System voice ID passed as tts_id when generating audio"},"label":{"type":"string","description":"Localized voice name"},"ttsRate":{"type":"number","minimum":0,"description":"Credits per started 10 seconds of generated audio, using the same dynamic rates and account privileges as send_tts. Zero is a valid free rate. A rate is not a total-price estimate."}}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"value":"example","label":"example","children":[{"value":"example","label":"example","ttsRate":0}]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1AnchorVoiceList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/anchor/voice_list\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"country\": \"en\",\n  \"region\": \"US\",\n  \"voice_map_type\": \"en-US\"\n}'"}]},"get":{"summary":"List available voices (GET)","description":"List available voices grouped by gender with the current account's dynamic ttsRate. Defaults: country=en, region=US, voice_map_type=en-US.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `country`, `region`, `voice_map_type`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/anchor/tts_list` — List system voices (TTS presets)\n- `POST /api/v1/anchor/language_list` — List supported languages/regions for voices.\n- `POST /api/v1/anchor/voice_list` — List available voices by country/region.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Item retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","description":"Voices grouped by gender, with current account billing rates from the dynamic price catalog.","items":{"type":"object","properties":{"value":{"type":"string","description":"Gender group value"},"label":{"type":"string","description":"Localized gender group label"},"children":{"type":"array","items":{"type":"object","required":["value","label","ttsRate"],"properties":{"value":{"type":"string","description":"System voice ID passed as tts_id when generating audio"},"label":{"type":"string","description":"Localized voice name"},"ttsRate":{"type":"number","minimum":0,"description":"Credits per started 10 seconds of generated audio, using the same dynamic rates and account privileges as send_tts. Zero is a valid free rate. A rate is not a total-price estimate."}}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"value":"example","label":"example","children":[{"value":"example","label":"example","ttsRate":0}]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"en","example":"en"},"description":"country parameter"},{"name":"region","in":"query","required":false,"schema":{"type":"string","default":"US","example":"US"},"description":"region parameter"},{"name":"voice_map_type","in":"query","required":false,"schema":{"type":"string","default":"en-US","example":"en-US"},"description":"voice_map_type parameter"}],"operationId":"getApiV1AnchorVoiceList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/anchor/voice_list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/video/send_tts":{"post":{"summary":"Generate text-to-speech audio","description":"Convert text to speech using AI voices with customizable parameters.\n### Voice Selection\nProvide exactly one of `tts_id` (system voice) or `user_voice_id` (custom cloned voice).\nDo not send both: synthesis would use the `tts_id` voice while locale defaults and billing follow `user_voice_id`.\n- `tts_id`: Use built-in system voice (400+ voices available)\n- `user_voice_id`: Use your own custom cloned voice; omitted `country` and `region` default to `en-US`\n### Billing\nSystem voice lists return the current account's `ttsRate` in credits per 10 seconds.\nCharges are based on the generated audio duration: `ceil(duration / 10) * ttsRate`.\nA valid zero rate means no credits are charged. Fetch the selected voice's current rate before submitting;\ngenerated duration is unknown before synthesis, so this rate is not a total-price quote.\n### Text Limitations\n- **API token users**: No local 3000-unit text limit is applied by this controller\n- **Web users**: Maximum 3000 weighted units after pause tags are removed\n- The server counts ASCII and Latin-1 characters as one unit, Cyrillic characters as one unit, and other non-Latin-1 characters as two units\n### Rate Limiting & Captcha\nFor non-API users, captcha verification may be required after frequent usage:\n- Use `type` parameter to specify captcha type (`turnstile` or `aliyun_captcha`)\n- Provide corresponding `turnstile_token` or `captchaVerifyParam` when captcha is required\n- API token users skip captcha verification\nIf generated audio needs a duration probe and that probe fails, msg includes the audio source failure reason.\nInvalid audio URLs are cached for 180 seconds; cached failures return the same reason without probing again.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `msg`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid request parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `500` — Generated audio duration probe failed; msg includes the audio source failure reason.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["msg"],"anyOf":[{"required":["tts_id"]},{"required":["user_voice_id"]}],"properties":{"msg":{"type":"string","description":"Text content to convert to speech. Web users are limited to 3000 weighted units; API token users are not checked against this local limit.","example":"Welcome. Let's start your AI journey.","minLength":1},"tts_id":{"type":"string","description":"System voice ID (MongoDB ObjectId). Must provide either tts_id or user_voice_id.","example":"66dc3c1b7dc1f1c483cc5ab8"},"user_voice_id":{"type":"string","description":"Custom cloned voice ID (MongoDB ObjectId). Used only when tts_id is absent.","example":"66f1234567890abcdef12345"},"country":{"type":"string","description":"Locale language part (e.g. 'en', 'zh', 'pt', 'ja'). Optional when using user_voice_id, defaults to 'en'. Combine with `region` to form locale like 'en-US'/'zh-CN'. Values should come from POST /api/v1/anchor/language_list (top-level `value`).","example":"en","default":"en"},"region":{"type":"string","description":"Locale region part (e.g. 'US', 'CN', 'BR', 'JP'). Optional when using user_voice_id, defaults to 'US'. Combine with `country` to form locale like 'en-US'/'zh-CN'. Values should come from POST /api/v1/anchor/language_list (child `value`).","example":"US","default":"US"},"speechRate":{"type":"number","description":"Speech speed multiplier (0.5-2.0)","example":1,"minimum":0.5,"maximum":2,"default":1},"type":{"type":"string","description":"Captcha type (required when captcha verification is needed)","enum":["turnstile","aliyun_captcha"],"example":"turnstile"},"turnstile_token":{"type":"string","description":"Captcha token (required when type is 'turnstile')","example":"0x4AAAAAAxxxxxxxxxxxxxxxxxx"},"captchaVerifyParam":{"type":"string","description":"Captcha verification parameter (required when type is 'aliyun_captcha')","example":"xxxxxxxxxxxx"}},"example":{"msg":"Welcome. Let's start your AI journey.","tts_id":"66dc3c1b7dc1f1c483cc5ab8"}},"examples":{"system_voice":{"summary":"Using system voice (tts_id)","value":{"msg":"Welcome. Let's start your AI journey.","tts_id":"66dc3c1b7dc1f1c483cc5ab8","speechRate":1}},"cloned_voice":{"summary":"Using cloned voice (user_voice_id)","value":{"msg":"Hello, this is my cloned voice.","user_voice_id":"66f1234567890abcdef12345","country":"en","region":"US","speechRate":1}}}}}},"responses":{"200":{"description":"Text-to-speech generation successful","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"data":{"type":"string","format":"uri","description":"Generated audio preview URL","example":"https://example.com/audio/tts_output.wav"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"examples":{"system_voice":{"summary":"System voice preview URL","value":{"code":0,"data":"https://example.com/audio/system_voice.wav"}},"cloned_voice":{"summary":"Cloned voice preview URL","value":{"code":0,"data":"https://example.com/audio/cloned_voice.wav"}}},"example":{"code":0,"data":"https://example.com/audio/tts_output.wav","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing_voice":{"summary":"Missing voice selection","value":{"code":400,"msg":"user_voice_id and tts_id must required one"}},"text_too_long":{"summary":"Text exceeds limit","value":{"code":400,"msg":"Text length cannot exceed 3000 characters"}}}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Generated audio duration probe failed; msg includes the audio source failure reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":500,"msg":"Invalid audio URL: HTTP 404 Not Found. Check that the URL is accessible."}}}}},"operationId":"postApiV1VideoSendTts","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/video/send_tts\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"msg\": \"Welcome. Let'\\''s start your AI journey.\",\n  \"tts_id\": \"66dc3c1b7dc1f1c483cc5ab8\",\n  \"speechRate\": 1\n}'"}]}},"/api/v1/tts/preview/list":{"get":{"summary":"Get TTS preview list","description":"Return the authenticated user's non-deleted TTS preview records created during the last 24 hours, ordered for recent-preview playback.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageSize`, `current`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/tts/preview/{id}` — Delete TTS preview record.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"TTS preview list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"msg":{"type":"string"},"speechRate":{"type":"number"},"country":{"type":"string"},"region":{"type":"string"},"tts_id":{"type":"string"},"user_voice_id":{"type":"string"},"audio_url":{"type":"string"},"duration":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"data":[{"_id":"507f1f77bcf86cd799439011","msg":"success","speechRate":1,"country":"example","region":"example","tts_id":"507f1f77bcf86cd799439011","user_voice_id":"507f1f77bcf86cd799439011","audio_url":"https://example.com/audio.mp3","duration":5,"createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z"}]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"description":"Number of items per page"},{"name":"current","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Current page number"}],"operationId":"getApiV1TtsPreviewList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/tts/preview/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/tts/preview/{id}":{"delete":{"summary":"Delete TTS preview record","description":"Soft-delete the authenticated user's TTS preview record identified by `id`; the underlying audio object is not physically removed by this operation.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Record not found.\n### Related Operations\n- `GET /api/v1/tts/preview/list` — Get TTS preview list.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"TTS preview record deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"message":{"type":"string","example":"Record deleted successfully"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"Record deleted successfully"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"TTS preview record ID to delete"}],"operationId":"deleteApiV1TtsPreviewId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/tts/preview/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/video/generate":{"post":{"summary":"Generate AI video with avatar","description":"Generate AI video with avatar using audio source and selected avatar. Either audioSrc or custom_voice is required. For background replacement, use back_id for system backgrounds or custom_back_id for backgrounds created by /api/v1/custom_back/add. The avatar must have an original background saved, or the request must provide anchor_background_img or anchor_background_color.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `anchor_id`, `anchor_type`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters or missing required audio source.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/video/detail` — detail.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Generate Avatar Videos"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"title":{"type":"string","maxLength":40,"description":"Video title (optional, max 40 characters)","example":"My AI Video"},"audioSrc":{"type":"string","description":"Audio source URL (required if custom_voice not provided)","example":"https://example.com/audio.mp3"},"custom_voice":{"type":"string","description":"Custom voice audio URL (required if audioSrc not provided)","example":"https://example.com/custom_voice.wav"},"anchor_id":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Avatar/anchor ID (MongoDB ObjectId)","example":"507f1f77bcf86cd799439011"},"anchor_type":{"type":"number","description":"Avatar type (0 for system avatar, 1 for custom avatar)","example":0},"anchor_background_img":{"type":"string","description":"Original avatar background image URL. Required for background replacement if the avatar record does not already have background_img or background_color.","example":"https://example.com/original-avatar-background.jpg"},"anchor_background_color":{"type":"string","description":"Original avatar background color in RGBA format. Required for background replacement if the avatar record does not already have background_img or background_color.","example":"rgba(255,255,255,1)"},"back_id":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"System background template ID (MongoDB ObjectId). Mutually exclusive with custom_back_id; sending both returns error 30005.","example":"507f1f77bcf86cd799439012"},"face_swap_id":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Face swap template ID (MongoDB ObjectId)","example":"507f1f77bcf86cd799439013"},"custom_back_id":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Custom background ID returned by /api/v1/custom_back/add (MongoDB ObjectId). Mutually exclusive with back_id; sending both returns error 30005.","example":"507f1f77bcf86cd799439014"},"color":{"type":"string","description":"Color setting in RGBA format","example":"rgba(0,0,0,1)"},"wl_model":{"type":"string","description":"Watermark/logo model setting","example":"default"},"isSkipRs":{"type":"boolean","description":"Skip resolution scaling","example":false},"web_bg_width":{"type":"number","default":0,"description":"Output canvas/background width. Required when using back_id, custom_back_id, or color.","example":1920},"web_bg_height":{"type":"number","default":0,"description":"Output canvas/background height. Required when using back_id, custom_back_id, or color.","example":1080},"web_people_width":{"type":"number","default":0,"description":"Avatar width in output layout. Required when using back_id, custom_back_id, or color.","example":800},"web_people_height":{"type":"number","default":0,"description":"Avatar height in output layout. Required when using back_id, custom_back_id, or color.","example":600},"web_people_x":{"type":"number","default":0,"description":"Avatar X position in web layout","example":100},"web_people_y":{"type":"number","default":0,"description":"Avatar Y position in web layout","example":50},"web_dist_bg_width":{"type":"number","default":-1,"description":"Distributed background width","example":1920},"web_dist_bg_height":{"type":"number","default":-1,"description":"Distributed background height","example":1080},"web_dist_bg_x":{"type":"number","default":0,"description":"Distributed background X position","example":0},"web_dist_bg_y":{"type":"number","default":0,"description":"Distributed background Y position","example":0},"resolution":{"type":"number","default":1080,"description":"Video resolution (height in pixels)","example":1080},"msg":{"type":"string","description":"Additional message or notes","example":"Custom video generation"},"erode_factor":{"type":"number","description":"Erosion factor for image processing","example":0.5},"isSkipGp":{"type":"boolean","description":"Skip green screen processing","example":false},"isCaptionEnabled":{"type":"boolean","description":"Enable captions/subtitles","example":true},"gp_model":{"type":"object","description":"Green screen processing model settings","properties":{"compose_mode":{"type":"string","description":"Composition mode","example":"overlay"},"compose_ratio":{"type":"number","description":"Composition ratio","example":0.8}}},"isToPublicPool":{"type":"boolean","description":"Add to public pool for sharing","example":false},"lip_model":{"type":"string","description":"Lip sync model selection","example":"default"},"captionAlign":{"type":"object","description":"Caption alignment and styling settings","properties":{"language":{"type":"string","description":"Caption language","example":"en"},"PrimaryColour":{"type":"string","description":"Primary text color in RGBA format","example":"rgba(255,255,255,1)"},"title":{"type":"string","description":"Caption title","example":"Video Caption"},"TitleBoxColour":{"type":"string","description":"Title box background color in RGBA format","example":"rgba(0,0,0,0.5)"},"FontName":{"type":"string","description":"Font family name","example":"Arial"},"Fontsize":{"type":"integer","description":"Font size in pixels","example":24},"subtitle_position":{"type":"number","description":"Subtitle vertical position (0-1)","example":0.9},"OutlineColour":{"type":"string","description":"Text outline color in RGBA format","example":"rgba(0,0,0,1)"},"BackColour":{"type":"string","description":"Text background color in RGBA format","example":"rgba(0,0,0,0.3)"}}},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["anchor_id","anchor_type"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"title":"Avatar video with custom background","audioSrc":"https://example.com/audio.mp3","anchor_id":"507f1f77bcf86cd799439011","anchor_type":1,"custom_back_id":"507f1f77bcf86cd799439014","anchor_background_color":"rgba(255,255,255,1)","resolution":1080,"web_bg_width":1920,"web_bg_height":1080,"web_people_width":600,"web_people_height":1080,"web_people_x":660,"web_people_y":0}}}},"responses":{"200":{"description":"Video generation started, or audio preflight rejected with code 10001. Invalid audio URLs are cached for 180 seconds without extending the TTL on repeated requests; a different full URL is probed immediately.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"msg":{"type":"string","description":"Audio preflight failures include the source failure reason on both the first attempt and cached failures.","example":"Invalid audio URL: HTTP 404 Not Found. Check that the URL is accessible."},"data":{"type":"object","description":"Video generation result","properties":{"coins":{"type":"number","description":"Duration in seconds (cost in coins)","example":30}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"msg":"Invalid audio URL: HTTP 404 Not Found. Check that the URL is accessible.","data":{"coins":30},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters or missing required audio source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1VideoGenerate","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/video/generate\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"title\": \"Avatar video with custom background\",\n  \"audioSrc\": \"https://example.com/audio.mp3\",\n  \"anchor_id\": \"507f1f77bcf86cd799439011\",\n  \"anchor_type\": 1,\n  \"custom_back_id\": \"507f1f77bcf86cd799439014\",\n  \"anchor_background_color\": \"rgba(255,255,255,1)\",\n  \"resolution\": 1080,\n  \"web_bg_width\": 1920,\n  \"web_bg_height\": 1080,\n  \"web_people_width\": 600,\n  \"web_people_height\": 1080,\n  \"web_people_x\": 660,\n  \"web_people_y\": 0\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/video/detail":{"get":{"summary":"Get record details","description":"detail.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `video_id`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `POST /api/v1/video/generate` — Generate AI video with avatar.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Generate Avatar Videos"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Operation completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Response data"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"video_id","in":"query","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Video task ID returned by the generate endpoint"}],"operationId":"getApiV1VideoDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/video/detail?video_id=507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/custom_avatar/add":{"post":{"summary":"Create a custom avatar","description":"Create a custom avatar in the authenticated user's library from an image or video URL. A URL ending in .jpg, .jpeg, or .png is treated as an image and converted to a one-second base video; any other URL is treated as a video and its cover frame is extracted. Background matting starts asynchronously after creation.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `video_url`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_avatar/list` — List custom avatars.\n- `PUT /api/v1/custom_avatar/{_id}` — Update item.\n- `POST /api/v1/custom_avatar/del` — Delete a custom avatar.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Create Avatars"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","format":"uri","description":"Publicly reachable image (.jpg/.jpeg/.png) or video URL of the person; it becomes the avatar's base video.","example":"https://example.com/avatar.mp4"},"name":{"type":"string","description":"Display name. When omitted, the next free name in the form `Avatar<N>` is used.","example":"My Avatar"},"gender":{"type":"string","enum":["female","male"],"default":"female","description":"Avatar gender, used to suggest matching voices.","example":"female"},"wl_model":{"type":"string","default":"live_protrait","description":"Lip-sync model identifier. Keep the default unless support instructs otherwise.","example":"live_protrait"},"background_img":{"type":"string","format":"uri","description":"Original background image URL to keep with the avatar for later background replacement.","example":"example"},"background_color":{"type":"string","description":"Original background color to keep with the avatar, for example `#FFFFFF`.","example":"#FFFFFF"},"video":{"type":"string","format":"uri","description":"Optional display (preview) video; defaults to the processed base video.","example":"example"},"user_photo_twin_id":{"type":"string","description":"Photo twin ID when the avatar is created from a photo twin result.","example":"507f1f77bcf86cd799439011"},"user_photo_twin_image_id":{"type":"string","description":"Photo twin image ID used together with `user_photo_twin_id`.","example":"507f1f77bcf86cd799439011"},"user_video_twin_id":{"type":"string","description":"Video twin ID from `/api/v1/userVideoTwin`. If an avatar for this twin already exists, that avatar is returned instead of creating a new one; a missing or deleted twin returns `data` null.","example":"507f1f77bcf86cd799439011"},"user_video_twin_training_model":{"type":"string","description":"Training model recorded for the video twin, for example `fast` or `best`.","example":"fast"}},"required":["video_url"],"example":{"video_url":"https://example.com/avatar.mp4"}},"example":{"video_url":"https://example.com/avatar.mp4"}}}},"responses":{"200":{"description":"Avatar created, or the existing avatar returned for the same video twin","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","nullable":true,"description":"Newly created avatar summary. When `user_video_twin_id` already has an avatar, the full existing avatar record is returned instead.","properties":{"_id":{"type":"string","description":"Custom avatar ID."},"createdAt":{"type":"string","format":"date-time"},"width":{"type":"number"},"height":{"type":"number"},"type":{"type":"string","example":"custom"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","createdAt":"2026-01-01T00:00:00Z","width":1,"height":1,"type":"custom"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomAvatarAdd","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_avatar/add\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"video_url\": \"https://example.com/avatar.mp4\"\n}'"}]}},"/api/v1/custom_avatar/list":{"post":{"summary":"List custom avatars","description":"Return all active custom avatars belonging to the authenticated user, newest first. This route takes no request parameters; send an empty JSON body (`{}`) or no body. It does not implement pagination or filtering.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `PUT /api/v1/custom_avatar/{_id}` — Update item.\n- `POST /api/v1/custom_avatar/add` — Create a custom avatar.\n- `POST /api/v1/custom_avatar/del` — Delete a custom avatar.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Create Avatars"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Custom avatars retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"data":{"type":"array","description":"Active custom avatars, newest first.","items":{"type":"object","properties":{"_id":{"type":"string","description":"Custom avatar ID."},"name":{"type":"string"},"img":{"type":"string","description":"Cover image URL."},"base_video":{"type":"string","description":"Base video URL."},"video":{"type":"string","description":"Display video URL."},"anchor_type":{"type":"string","enum":["image","video"]},"gender":{"type":"string"},"status":{"type":"string","example":"normal"},"createdAt":{"type":"string","format":"date-time"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","img":"example","base_video":"example","video":"example","anchor_type":"image","gender":"example","status":"normal","createdAt":"2026-01-01T00:00:00Z"}]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomAvatarList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_avatar/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/custom_avatar/del":{"post":{"summary":"Delete a custom avatar","description":"Remove the authenticated user's active custom avatar identified by `_id` (the `_id` returned by add or list). Deleting an avatar created from a video twin also removes that twin when no other active avatar uses it.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `_id`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_avatar/list` — List custom avatars.\n- `PUT /api/v1/custom_avatar/{_id}` — Update item.\n- `POST /api/v1/custom_avatar/add` — Create a custom avatar.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Create Avatars"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"ID of the authenticated user's avatar to delete.","example":"507f1f77bcf86cd799439011"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Avatar deleted; `data` is null when no active avatar with this ID belongs to the caller","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","nullable":true,"description":"The deleted avatar record, or null when nothing was deleted."},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomAvatarDel","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_avatar/del\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/custom_avatar/all_tags":{"get":{"summary":"List all tags","description":"Return the distinct tags available for organizing and filtering the authenticated user's custom avatars.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_avatar/list` — List custom avatars.\n- `PUT /api/v1/custom_avatar/{_id}` — Update item.\n- `POST /api/v1/custom_avatar/add` — Create a custom avatar.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Create Avatars"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Operation completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Response data"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1CustomAvatarAllTags","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/custom_avatar/all_tags\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/custom_avatar/{_id}":{"put":{"summary":"Update item","description":"Update editable metadata for the authenticated user's custom avatar identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Updates the identified resource using the fields accepted by the request schema and the operation's access controls.\n- Fields omitted from the request retain their existing values unless the schema states otherwise.\n- Read the returned record or call the detail operation to confirm the persisted state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_avatar/list` — List custom avatars.\n- `POST /api/v1/custom_avatar/add` — Create a custom avatar.\n- `POST /api/v1/custom_avatar/del` — Delete a custom avatar.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Create Avatars"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string"},"gender":{"type":"string","enum":["female","male"]},"skin_tone":{"type":"string","enum":["light","medium","dark"]},"tags":{"type":"array","items":{"type":"string"}},"has_occlusion":{"type":"boolean"}}}]},"example":{}}}},"responses":{"200":{"description":"Item updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","nullable":true,"properties":{"_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["custom"]},"gender":{"type":"string"},"skin_tone":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"has_occlusion":{"type":"boolean"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","type":"custom","gender":"example","skin_tone":"example","tags":["example"],"has_occlusion":false},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"putApiV1CustomAvatarId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https://headswap.app/api/v1/custom_avatar/507f1f77bcf86cd799439011\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{}'"}]}},"/api/v1/custom_back/add":{"post":{"summary":"Add new custom background","description":"Create a custom background in the authenticated user's library from the submitted background image and metadata.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `img_url`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters or missing img_url.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_back/list` — List items.\n- `POST /api/v1/custom_back/del` — del.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Background Library"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"img_url":{"type":"string","description":"URL of the background image to add","example":"https://example.com/background.jpg"}},"required":["img_url"],"example":{"img_url":"https://example.com/background.jpg"}},"example":{"img_url":"https://example.com/background.jpg"}}}},"responses":{"200":{"description":"Background item created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier of the created background","example":"63f9a0b2c1d4e5f678901234"},"type":{"type":"string","description":"Background type","example":"custom"},"url":{"type":"string","description":"CDN URL of the background image","example":"https://cdn.example.com/background.webp"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2023-02-25T10:30:45.123Z"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"63f9a0b2c1d4e5f678901234","type":"custom","url":"https://cdn.example.com/background.webp","createdAt":"2023-02-25T10:30:45.123Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters or missing img_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomBackAdd","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_back/add\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"img_url\": \"https://example.com/background.jpg\"\n}'"}]}},"/api/v1/custom_back/list":{"post":{"summary":"Create/Run list","description":"Return the authenticated user's custom backgrounds using the submitted pagination and filtering controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_back/add` — Add new custom background.\n- `POST /api/v1/custom_back/del` — del.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Background Library"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Item retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Response data"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomBackList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_back/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/custom_back/del":{"post":{"summary":"Delete record","description":"Remove the authenticated user's custom background identified by the submitted record ID.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `_id`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_back/list` — List items.\n- `POST /api/v1/custom_back/add` — Add new custom background.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Background Library"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["_id"],"properties":{"_id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"}}}]},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Operation completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Response data"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomBackDel","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_back/del\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/custom_back/allBackground":{"post":{"summary":"List available backgrounds","description":"List available backgrounds.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/custom_back/randomBackground` — Get a random default background.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"type":{"type":"string","enum":["default","custom"]},"url":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","type":"default","url":"https://example.com/file","createdAt":"2026-01-01T00:00:00Z"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1CustomBackAllBackground","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_back/allBackground\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/custom_back/randomBackground":{"post":{"summary":"Get a random default background","description":"Get a random default background.\n### Request\n- This operation does not declare bearer authentication in the published specification.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- Non-success responses use the published error envelope; surface the returned message and code to diagnostics.\n### Related Operations\n- `POST /api/v1/custom_back/allBackground` — List available backgrounds.","tags":["Credits"],"security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"type":{"type":"string","enum":["default","custom"]},"url":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","type":"default","url":"https://example.com/file","createdAt":"2026-01-01T00:00:00Z"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}},"operationId":"postApiV1CustomBackRandomBackground","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/custom_back/randomBackground\""}]}},"/api/v1/userVoice/training":{"post":{"summary":"Start voice training","description":"Create an asynchronous custom-voice training task from the submitted voice samples.\n- **Concurrency:** A user may submit only one training request at a time; concurrent submissions are rejected by the service guard.\n- **Charging:** The current voice_clone_model_costs entry for the selected model determines credits per clone; prices may be configured dynamically. The charge occurs at submission; a failed creation attempt rolls back it according to the documented failure flow. Read GET /api/v1/feature-pricing for current configured prices; a quote does not reserve credits.\n- **Status:** After creation, poll `GET /api/v1/userVoice/trainingRecord` and inspect `current_status` for progress.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `voice_urls`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid training data.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `403` — Forbidden - Voice clone limit exceeded.\n### Related Operations\n- `DELETE /api/v1/userVoice/{_id}` — Delete voice training record.\n- `GET /api/v1/userVoice/{_id}` — Get voice training record detail.\n- `PUT /api/v1/userVoice/{_id}` — Update voice training record name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UserVoiceTrainingRequest"},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Custom Voice","voice_urls":["https://example.com/audio1.wav","https://example.com/audio2.wav"]}}}},"responses":{"200":{"description":"Voice training record created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessUserVoiceResponse"}}}},"400":{"description":"Bad Request - Invalid training data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Voice clone limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVoiceTraining","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVoice/training\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Custom Voice\",\n  \"voice_urls\": [\n    \"https://example.com/audio1.wav\",\n    \"https://example.com/audio2.wav\"\n  ]\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userVoice/trainingRecord":{"get":{"summary":"Get voice training records","description":"Return the authenticated user's voice-training records across queued, processing, completed, and failed states.\n- **Ordering:** Records are sorted by `createdAt` in descending order, newest first.\n- **Status values:** `current_status` may be `sent`, `pendding`, `processing`, `completed`, or `failed`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/userVoice/{_id}` — Delete voice training record.\n- `GET /api/v1/userVoice/{_id}` — Get voice training record detail.\n- `PUT /api/v1/userVoice/{_id}` — Update voice training record name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessUserVoiceListResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserVoiceTrainingRecord","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVoice/trainingRecord\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVoice/completedRecord":{"get":{"summary":"Get completed voice training records","description":"Return only the authenticated user's completed voice-training records (`current_status=completed`).\n- **Ordering:** Records are sorted by `createdAt` in descending order, newest first.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/userVoice/{_id}` — Delete voice training record.\n- `GET /api/v1/userVoice/{_id}` — Get voice training record detail.\n- `PUT /api/v1/userVoice/{_id}` — Update voice training record name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessUserVoiceListResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserVoiceCompletedRecord","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVoice/completedRecord\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVoice/{_id}":{"delete":{"summary":"Delete voice training record","description":"Soft-delete the authenticated user's voice-training record by setting `deleted=true`; the stored record is not physically removed.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid voice training record ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVoice/{_id}` — Get voice training record detail.\n- `PUT /api/v1/userVoice/{_id}` — Update voice training record name.\n- `POST /api/v1/userVoice/training` — Start voice training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","properties":{"acknowledged":{"type":"boolean"},"matchedCount":{"type":"integer"},"modifiedCount":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"acknowledged":false,"matchedCount":1,"modifiedCount":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid voice training record ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"MongoDB ObjectId of the voice training record"}],"operationId":"deleteApiV1UserVoiceId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userVoice/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"get":{"summary":"Get voice training record detail","description":"Return one voice-training record owned by the authenticated user, identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid _id.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/userVoice/{_id}` — Delete voice training record.\n- `PUT /api/v1/userVoice/{_id}` — Update voice training record name.\n- `POST /api/v1/userVoice/training` — Start voice training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessUserVoiceResponse"}}}},"400":{"description":"Bad Request - Invalid _id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"MongoDB ObjectId of the voice training record"}],"operationId":"getApiV1UserVoiceId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVoice/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"put":{"summary":"Update voice training record name","description":"Rename the authenticated user's voice-training record identified by `_id`; no training inputs or status fields are changed.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n- Send an `application/json` body. Required fields: `name`.\n### Behavior\n- Updates the identified resource using the fields accepted by the request schema and the operation's access controls.\n- Fields omitted from the request retain their existing values unless the schema states otherwise.\n- Read the returned record or call the detail operation to confirm the persisted state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid voice training record ID or request body.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/userVoice/{_id}` — Delete voice training record.\n- `GET /api/v1/userVoice/{_id}` — Get voice training record detail.\n- `POST /api/v1/userVoice/training` — Start voice training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserVoiceUpdateRequest"},"example":{"name":"My Renamed Voice"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","properties":{"acknowledged":{"type":"boolean"},"matchedCount":{"type":"integer"},"modifiedCount":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"acknowledged":false,"matchedCount":1,"modifiedCount":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid voice training record ID or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"MongoDB ObjectId of the voice training record"}],"operationId":"putApiV1UserVoiceId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https://headswap.app/api/v1/userVoice/507f1f77bcf86cd799439011\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Renamed Voice\"\n}'"}]}},"/api/v1/userVideoTwin/upload":{"post":{"summary":"Deprecated video twin upload","description":"This route always returns ENDPOINT_DEPRECATED. Create an avatar with POST /api/v1/userVideoTwin/startTraining instead.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Reads the requested information without creating a generation task.\n- Use the returned fields as documented; availability may depend on the caller and current resource state.\n### Response\n- This operation does not declare a `2xx` response; consult the documented response statuses below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/startTraining.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n- `GET /api/v1/userVideoTwin/uploadStatus` — Get video twin upload status.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","deprecated":true,"tags":["Video Twin"],"security":[{"bearerAuth":[]}],"responses":{"400":{"description":"ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/startTraining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinUpload","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/upload\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/training":{"post":{"summary":"Deprecated video twin training","description":"This route always returns ENDPOINT_DEPRECATED. Start deep training with POST /api/v1/userVideoTwin/continueTraining instead.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Reads the requested information without creating a generation task.\n- Use the returned fields as documented; availability may depend on the caller and current resource state.\n### Response\n- This operation does not declare a `2xx` response; consult the documented response statuses below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/continueTraining.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `GET /api/v1/userVideoTwin/uploadStatus` — Get video twin upload status.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","deprecated":true,"tags":["Video Twin"],"security":[{"bearerAuth":[]}],"responses":{"400":{"description":"ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/continueTraining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinTraining","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/training\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/uploadStatus":{"get":{"summary":"Get video twin upload status","description":"Check the upload status of video twin files for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Upload status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Upload status information"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserVideoTwinUploadStatus","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVideoTwin/uploadStatus\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/userRecords":{"get":{"summary":"Get user video twin records","description":"Return every video-twin record available to the authenticated user, including its current training state and result metadata.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Video twin records retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"type":"object","description":"Video twin record"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserVideoTwinUserRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVideoTwin/userRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/remove":{"post":{"summary":"Remove video twin","description":"Remove the video twin identified in the request from the authenticated user's collection without affecting unrelated records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `_id`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid video twin ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"ID of the video twin to remove","example":"507f1f77bcf86cd799439011"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Video twin removed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Removal result"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid video twin ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinRemove","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/remove\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/userVideoTwin/records":{"get":{"summary":"Get video twin records","description":"Retrieve paginated video twin records with optional filters.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`, `status`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n- `GET /api/v1/userVideoTwin/uploadStatus` — Get video twin upload status.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Records retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/VideoTwinRecord"}},"total":{"type":"integer","description":"Total number of records"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","gender":"example","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","current_status":"initialized","failed_code":"example","failed_message":"example","failed_reason":"example","preview_result_url":"https://example.com/file","image_result_url":"https://example.com/image.jpg","video_backgroud_image":"example","video_backgroud_color":"example","skipPreview":false,"isSilent":false,"hasVoiceClone":false,"hasVideoClone":false,"hasEyecontact":false,"eyecontact_result_url":"https://example.com/file","custom_anchor_id":"507f1f77bcf86cd799439011","anchor_id":"507f1f77bcf86cd799439011","user_voice_id":"507f1f77bcf86cd799439011","coins":1,"hasRefundCoin":false}],"total":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number (starts from 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"Number of records per page"},{"name":"status","in":"query","required":false,"schema":{"type":"string","example":"completed","enum":["pending","processing","completed","failed"]},"description":"Filter by status"}],"operationId":"getApiV1UserVideoTwinRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVideoTwin/records\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/startTraining":{"post":{"summary":"Create an image or video avatar","description":"An image avatar is billed using the current image_twin price when created (code default: 30 coins; dynamic settings can override). A video source with skipPreview=false (the default) first creates a usable avatar without a training charge; a returned anchor_id only confirms avatar creation. Video deep training uses the current video_twin price when started later via continueTraining (code default: 100 coins; dynamic settings can override). Set skipPreview=true to start deep training automatically and charge at creation. Training failure may trigger a refund according to task status.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the video twin","example":"My Video Twin"},"image_url":{"type":"string","description":"URL of the source image","example":"https://example.com/face.jpg"},"video_url":{"type":"string","description":"URL of the source video","example":"https://example.com/video.mp4"},"skipPreview":{"type":"boolean","default":false,"description":"Start video deep training automatically and charge the current video_twin price at creation. Only applies to a video source.","example":false},"video_background_image":{"type":"string","description":"URL of background image","example":"https://example.com/bg.jpg"},"video_background_color":{"type":"string","description":"Background color in RGBA format","example":"rgba(255,255,255,1)"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.","example":false}},"required":[],"example":{}},"example":{}}}},"responses":{"200":{"description":"Avatar created; video deep training starts immediately only when skipPreview=true.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"$ref":"#/components/schemas/VideoTwinRecord"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","gender":"example","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","current_status":"initialized","failed_code":"example","failed_message":"example","failed_reason":"example","preview_result_url":"https://example.com/file","image_result_url":"https://example.com/image.jpg","video_backgroud_image":"example","video_backgroud_color":"example","skipPreview":false,"isSilent":false,"hasVoiceClone":false,"hasVideoClone":false,"hasEyecontact":false,"eyecontact_result_url":"https://example.com/file","custom_anchor_id":"507f1f77bcf86cd799439011","anchor_id":"507f1f77bcf86cd799439011","user_voice_id":"507f1f77bcf86cd799439011","coins":1,"hasRefundCoin":false},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinStartTraining","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/startTraining\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{}'"}]}},"/api/v1/userVideoTwin/continueTraining":{"post":{"summary":"Start video deep training","description":"Start deep training of an existing video avatar and charge the current video_twin price (code default: 100 coins). A video avatar created with skipPreview=false was usable before this call without a deep-training charge.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `_id`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid video twin ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"ID of the video twin to continue training","example":"507f1f77bcf86cd799439011"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Training continued successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Update result of the training record; it is not the refreshed record","properties":{"acknowledged":{"type":"boolean"},"matchedCount":{"type":"integer"},"modifiedCount":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"acknowledged":false,"matchedCount":1,"modifiedCount":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid video twin ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinContinueTraining","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/continueTraining\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/userVideoTwin/trainingRecords":{"get":{"summary":"Get training records","description":"Retrieve all video twin training records for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Training records retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoTwinRecord"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","gender":"example","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","current_status":"initialized","failed_code":"example","failed_message":"example","failed_reason":"example","preview_result_url":"https://example.com/file","image_result_url":"https://example.com/image.jpg","video_backgroud_image":"example","video_backgroud_color":"example","skipPreview":false,"isSilent":false,"hasVoiceClone":false,"hasVideoClone":false,"hasEyecontact":false,"eyecontact_result_url":"https://example.com/file","custom_anchor_id":"507f1f77bcf86cd799439011","anchor_id":"507f1f77bcf86cd799439011","user_voice_id":"507f1f77bcf86cd799439011","coins":1,"hasRefundCoin":false}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserVideoTwinTrainingRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVideoTwin/trainingRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoTwinRecord"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","gender":"example","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","current_status":"initialized","failed_code":"example","failed_message":"example","failed_reason":"example","preview_result_url":"https://example.com/file","image_result_url":"https://example.com/image.jpg","video_backgroud_image":"example","video_backgroud_color":"example","skipPreview":false,"isSilent":false,"hasVoiceClone":false,"hasVideoClone":false,"hasEyecontact":false,"eyecontact_result_url":"https://example.com/file","custom_anchor_id":"507f1f77bcf86cd799439011","anchor_id":"507f1f77bcf86cd799439011","user_voice_id":"507f1f77bcf86cd799439011","coins":1,"hasRefundCoin":false}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userVideoTwin/{_id}":{"get":{"summary":"Get a video twin record","description":"Get a video twin record.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `POST /api/v1/userVideoTwin/retry` — Retry a video twin task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/VideoTwinRecord"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","gender":"example","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","current_status":"initialized","failed_code":"example","failed_message":"example","failed_reason":"example","preview_result_url":"https://example.com/file","image_result_url":"https://example.com/image.jpg","video_backgroud_image":"example","video_backgroud_color":"example","skipPreview":false,"isSilent":false,"hasVoiceClone":false,"hasVideoClone":false,"hasEyecontact":false,"eyecontact_result_url":"https://example.com/file","custom_anchor_id":"507f1f77bcf86cd799439011","anchor_id":"507f1f77bcf86cd799439011","user_voice_id":"507f1f77bcf86cd799439011","coins":1,"hasRefundCoin":false},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"getApiV1UserVideoTwinId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userVideoTwin/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userVideoTwin/retry":{"post":{"summary":"Retry a video twin task","description":"Retry a video twin task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `_id`.\n### Behavior\n- Requests another processing attempt for an eligible failed task.\n- Eligibility, charging, and state transitions follow the task-specific rules exposed by the response.\n- Continue monitoring the same or returned task identifier after the retry is accepted.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/{_id}` — Get a video twin record.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["_id"],"properties":{"_id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"}}}]},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinRetry","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/retry\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/userVideoTwin/eyeContact":{"post":{"summary":"Start eye contact enhancement","description":"Enhance video twin with improved eye contact using AI processing.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userVideoTwin/records` — Get video twin records.\n- `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload.\n- `POST /api/v1/userVideoTwin/training` — Deprecated video twin training.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Video Twin"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"ID of the video twin to enhance","example":"507f1f77bcf86cd799439011"}},"required":[],"example":{}},"example":{}}}},"responses":{"200":{"description":"Eye contact enhancement started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"user_voice_id":{"type":"string","description":"Generated voice ID for the enhancement"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"user_voice_id":"507f1f77bcf86cd799439011"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserVideoTwinEyeContact","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userVideoTwin/eyeContact\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{}'"}]}},"/api/v1/userFaceSwapImage/add":{"post":{"summary":"Add a new face image for face swapping","description":"Add a new face image to the user's face swap image collection.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `face_url`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userFaceSwapImage/records` — Get user's face swap image records.\n- `DELETE /api/v1/userFaceSwapImage/{_id}` — Remove a face swap image.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"face_url":{"type":"string","description":"URL of the face image to be used for face swapping","example":"https://example.com/face-image.jpg"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.","example":false}},"required":["face_url"],"example":{"face_url":"https://example.com/face-image.jpg"}},"example":{"face_url":"https://example.com/face-image.jpg"}}}},"responses":{"200":{"description":"Face image added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Image ID","example":"507f1f77bcf86cd799439011"},"face_url":{"type":"string","description":"Face image URL","example":"https://example.com/face-image.jpg"},"user_id":{"type":"string","description":"User ID","example":"507f1f77bcf86cd799439012"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-14T18:22:13.726Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-01-14T18:22:13.726Z"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","face_url":"https://example.com/face-image.jpg","user_id":"507f1f77bcf86cd799439012","createdAt":"2025-01-14T18:22:13.726Z","updatedAt":"2025-01-14T18:22:13.726Z"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserFaceSwapImageAdd","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userFaceSwapImage/add\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"face_url\": \"https://example.com/face-image.jpg\"\n}'"}]}},"/api/v1/userFaceSwapImage/records":{"get":{"summary":"Get user's face swap image records","description":"Return the authenticated user's saved face-swap source images and their reusable record identifiers.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `DELETE /api/v1/userFaceSwapImage/{_id}` — Remove a face swap image.\n- `POST /api/v1/userFaceSwapImage/add` — Add a new face image for face swapping.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Face swap image records retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Image ID","example":"507f1f77bcf86cd799439011"},"face_url":{"type":"string","description":"Face image URL","example":"https://example.com/face-image.jpg"},"user_id":{"type":"string","description":"User ID","example":"507f1f77bcf86cd799439012"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-14T18:22:13.726Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-01-14T18:22:13.726Z"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","face_url":"https://example.com/face-image.jpg","user_id":"507f1f77bcf86cd799439012","createdAt":"2025-01-14T18:22:13.726Z","updatedAt":"2025-01-14T18:22:13.726Z"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserFaceSwapImageRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFaceSwapImage/records\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFaceSwapImage/{_id}":{"delete":{"summary":"Remove a face swap image","description":"Delete a specific face swap image from the user's collection.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid ID format.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userFaceSwapImage/records` — Get user's face swap image records.\n- `POST /api/v1/userFaceSwapImage/add` — Add a new face image for face swapping.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Face swap image deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Deletion result data"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the face swap image to delete"}],"operationId":"deleteApiV1UserFaceSwapImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userFaceSwapImage/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFaceSwapPreview/add":{"post":{"summary":"Create a new face swap preview task","description":"Create a face swap preview task using video and face image URLs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `video_url`, `face_url`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userFaceSwapPreview/status` — Get face swap preview status.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"URL of the video to swap face in","example":"https://example.com/video.mp4"},"face_url":{"type":"string","description":"URL of the face image to swap with","example":"https://example.com/face.jpg"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Retry after confirming a suspected-minor soft block","example":false}},"required":["video_url","face_url"],"example":{"video_url":"https://example.com/video.mp4","face_url":"https://example.com/face.jpg"}},"example":{"video_url":"https://example.com/video.mp4","face_url":"https://example.com/face.jpg"}}}},"responses":{"200":{"description":"Face swap preview task created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"video_url":{"type":"string","description":"Video URL"},"face_url":{"type":"string","description":"Face image URL"},"current_status":{"type":"string","description":"Current processing status"},"result_url":{"type":"string","description":"Result video URL"},"error_code":{"type":"string","description":"Error code if failed"},"faild_message":{"type":"string","description":"Failure message if error occurred"},"user_id":{"type":"string","description":"User ID"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","video_url":"https://example.com/video.mp4","face_url":"https://example.com/file","current_status":"processing","result_url":"https://example.com/file","error_code":"example","faild_message":"example","user_id":"507f1f77bcf86cd799439011","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserFaceSwapPreviewAdd","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userFaceSwapPreview/add\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"video_url\": \"https://example.com/video.mp4\",\n  \"face_url\": \"https://example.com/face.jpg\"\n}'"}]}},"/api/v1/userFaceSwapPreview/status":{"get":{"summary":"Get face swap preview status","description":"Check the processing status of a specific face swap preview task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `_id`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID format.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `POST /api/v1/userFaceSwapPreview/add` — Create a new face swap preview task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preview status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"video_url":{"type":"string","description":"Original video URL"},"face_url":{"type":"string","description":"Face image URL"},"current_status":{"type":"string","description":"Current processing status"},"result_url":{"type":"string","description":"Result video URL (if completed)"},"error_code":{"type":"string","description":"Error code (if failed)"},"faild_message":{"type":"string","description":"Failure message (if failed)"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","video_url":"https://example.com/video.mp4","face_url":"https://example.com/file","current_status":"processing","result_url":"https://example.com/file","error_code":"example","faild_message":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"query","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the face swap preview task"}],"operationId":"getApiV1UserFaceSwapPreviewStatus","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFaceSwapPreview/status?_id=507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFaceSwapTask/add":{"post":{"summary":"Create a new face swap task","description":"Create a face swap task with video, face image, and optional cover image.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `video_url`, `face_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records.\n- `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details.\n- `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the face swap task","example":"My Face Swap Video"},"video_url":{"type":"string","description":"URL of the video to swap face in","example":"https://example.com/video.mp4"},"face_url":{"type":"string","description":"URL of the face image to swap with","example":"https://example.com/face.jpg"},"cover_url":{"type":"string","description":"Optional cover image URL","example":"https://example.com/cover.jpg"},"model_version":{"type":"string","enum":["v1","v2"],"description":"Face swap model version: v1 (JAH pipeline, default), v2 (ComfyUI, image only)","example":"v1"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["name","video_url","face_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Face Swap Video","video_url":"https://example.com/video.mp4","face_url":"https://example.com/face.jpg"}}}},"responses":{"200":{"description":"Face swap task created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"duration":{"type":"number","description":"Video duration in seconds"},"video_url":{"type":"string","description":"Video URL"},"face_url":{"type":"string","description":"Face image URL"},"current_status":{"type":"string","description":"Current processing status"},"cover_url":{"type":"string","description":"Cover image URL"},"coins":{"type":"number","description":"Cost in coins"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","duration":5,"video_url":"https://example.com/video.mp4","face_url":"https://example.com/file","current_status":"processing","cover_url":"https://example.com/file","coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserFaceSwapTaskAdd","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userFaceSwapTask/add\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Face Swap Video\",\n  \"video_url\": \"https://example.com/video.mp4\",\n  \"face_url\": \"https://example.com/face.jpg\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userFaceSwapTask/records":{"get":{"summary":"Get user's face swap task records","description":"Retrieve paginated list of face swap tasks for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid pagination parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details.\n- `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task.\n- `POST /api/v1/userFaceSwapTask/add` — Create a new face swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task records retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"duration":{"type":"number"},"current_status":{"type":"string"},"result_url":{"type":"string"},"cover_url":{"type":"string"},"coins":{"type":"number"}}}},"total":{"type":"integer","description":"Total number of records"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","duration":5,"current_status":"processing","result_url":"https://example.com/file","cover_url":"https://example.com/file","coins":1}],"total":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":true,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number (starts from 1)"},{"name":"pageSize","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"Number of records per page"}],"operationId":"getApiV1UserFaceSwapTaskRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFaceSwapTask/records?pageNum=1&pageSize=10\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFaceSwapTask/status":{"get":{"summary":"Get user's face swap task status","description":"Get overall face swap task status information for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records.\n- `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details.\n- `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Task status information"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserFaceSwapTaskStatus","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFaceSwapTask/status\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFaceSwapTask/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records.\n- `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details.\n- `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskDubbing"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserFaceSwapTaskBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userFaceSwapTask/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userFaceSwapTask/{_id}":{"get":{"summary":"Get face swap task details","description":"Retrieve detailed information about a specific face swap task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID format.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records.\n- `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task.\n- `POST /api/v1/userFaceSwapTask/add` — Create a new face swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"duration":{"type":"number","description":"Video duration"},"video_url":{"type":"string","description":"Original video URL"},"face_url":{"type":"string","description":"Face image URL"},"current_status":{"type":"string","description":"Current processing status"},"result_url":{"type":"string","description":"Result video URL"},"cover_url":{"type":"string","description":"Cover image URL"},"coins":{"type":"number","description":"Cost in coins"},"processing_times":{"type":"object","description":"Processing timestamps"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","duration":5,"video_url":"https://example.com/video.mp4","face_url":"https://example.com/file","current_status":"processing","result_url":"https://example.com/file","cover_url":"https://example.com/file","coins":1,"processing_times":{}},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the face swap task"}],"operationId":"getApiV1UserFaceSwapTaskId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFaceSwapTask/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete face swap task","description":"Soft-delete a face swap task. `initialized` is queued and can be deleted with a coin refund only after at least 60 seconds from creation. Before then, or while `sent`, `pending`, or `processing`, deletion returns HTTP 400 / code 30101. `completed`, `failed`, and `blocked` (including legacy `block`) can be deleted without this refund. Deletion does not guarantee physical media removal.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records.\n- `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details.\n- `POST /api/v1/userFaceSwapTask/add` — Create a new face swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Face Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Empty object; this response is not a refund receipt."},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the face swap task to delete"}],"operationId":"deleteApiV1UserFaceSwapTaskId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userFaceSwapTask/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userDubbing/startDubbing":{"post":{"summary":"Start video dubbing task","description":"Create an asynchronous dubbing task that translates the source video's speech from `source_lang` to `target_lang` using the requested speaker and background-audio options.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `source_url`, `source_lang`, `target_lang`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userDubbing/allRecords` — Get all task records.\n- `GET /api/v1/userDubbing/{_id}` — Get task details.\n- `DELETE /api/v1/userDubbing/{_id}` — Delete dubbing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["AI Dubbing"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the dubbing task","example":"Dubbing video from English to Spanish"},"source_url":{"type":"string","description":"URL of the source video","example":"https://example.com/video.mp4"},"source_lang":{"type":"string","description":"Source language code","example":"en"},"target_lang":{"type":"string","description":"Target language code","example":"es"},"num_speakers":{"type":"number","description":"Number of speakers in the video","default":1,"example":2},"drop_background_audio":{"type":"boolean","description":"Whether to remove background audio","default":false,"example":true}},"required":["name","source_url","source_lang","target_lang"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"Dubbing video from English to Spanish","source_url":"https://example.com/video.mp4","source_lang":"en","target_lang":"es"}}}},"responses":{"200":{"description":"Dubbing task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"source_lang":{"type":"string"},"target_lang":{"type":"string"},"current_status":{"type":"string"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","source_lang":"en","target_lang":"en","current_status":"processing","coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserDubbingStartDubbing","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userDubbing/startDubbing\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"Dubbing video from English to Spanish\",\n  \"source_url\": \"https://example.com/video.mp4\",\n  \"source_lang\": \"en\",\n  \"target_lang\": \"es\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userDubbing/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's dubbing tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userDubbing/{_id}` — Get task details.\n- `DELETE /api/v1/userDubbing/{_id}` — Delete dubbing task.\n- `POST /api/v1/userDubbing/startDubbing` — Start video dubbing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["AI Dubbing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskDubbing"},{"type":"object","properties":{"faild_message":{"type":"string","nullable":true,"description":"Legacy (misspelled) runtime failure reason written on failed tasks; kept for backward compatibility. Read this field when failed_message is empty."}}}]}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"faild_message":"example"}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1UserDubbingAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userDubbing/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userDubbing/allProcessing":{"get":{"summary":"List processing task identifiers and statuses","description":"List processing task identifiers and statuses.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"processing","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserDubbingAllProcessing","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userDubbing/allProcessing\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userDubbing/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's dubbing task identified by `_id`, including its current processing status and available output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userDubbing/allRecords` — Get all task records.\n- `DELETE /api/v1/userDubbing/{_id}` — Delete dubbing task.\n- `POST /api/v1/userDubbing/startDubbing` — Start video dubbing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["AI Dubbing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskDubbing"},{"type":"object","properties":{"faild_message":{"type":"string","nullable":true,"description":"Legacy (misspelled) runtime failure reason written on failed tasks; kept for backward compatibility. Read this field when failed_message is empty."}}}]},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"faild_message":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserDubbingId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userDubbing/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete dubbing task","description":"Remove the authenticated user's dubbing task identified by `_id` from the task history without affecting other dubbing records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userDubbing/allRecords` — Get all task records.\n- `GET /api/v1/userDubbing/{_id}` — Get task details.\n- `POST /api/v1/userDubbing/startDubbing` — Start video dubbing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["AI Dubbing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the dubbing task"}],"operationId":"deleteApiV1UserDubbingId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userDubbing/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userCaptionRemoval/start":{"post":{"summary":"Start caption removal task","description":"Create an asynchronous caption-removal task for the submitted source video and return the record used to monitor processing.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `source_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records.\n- `GET /api/v1/userCaptionRemoval/{_id}` — Get task details.\n- `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Caption Removal"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the caption removal task","example":"Remove captions from video"},"source_url":{"type":"string","description":"URL of the source video","example":"https://example.com/video.mp4"}},"required":["name","source_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"Remove captions from video","source_url":"https://example.com/video.mp4"}}}},"responses":{"200":{"description":"Caption removal task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"duration":{"type":"number"},"source_url":{"type":"string"},"current_status":{"type":"string"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","duration":5,"source_url":"https://example.com/file","current_status":"processing","coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserCaptionRemovalStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userCaptionRemoval/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"Remove captions from video\",\n  \"source_url\": \"https://example.com/video.mp4\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userCaptionRemoval/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's caption-removal tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userCaptionRemoval/{_id}` — Get task details.\n- `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task.\n- `POST /api/v1/userCaptionRemoval/start` — Start caption removal task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Caption Removal"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},{"type":"object","properties":{"faild_message":{"type":"string","nullable":true,"description":"Legacy (misspelled) runtime failure reason written on failed tasks; kept for backward compatibility. Read this field when failed_message is empty."}}}]}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"faild_message":"example"}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1UserCaptionRemovalAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userCaptionRemoval/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userCaptionRemoval/allProcessing":{"get":{"summary":"List processing task identifiers and statuses","description":"List processing task identifiers and statuses.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"processing","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserCaptionRemovalAllProcessing","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userCaptionRemoval/allProcessing\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userCaptionRemoval/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records.\n- `GET /api/v1/userCaptionRemoval/{_id}` — Get task details.\n- `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Caption Removal"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},{"type":"object","properties":{"faild_message":{"type":"string","nullable":true,"description":"Legacy (misspelled) runtime failure reason written on failed tasks; kept for backward compatibility. Read this field when failed_message is empty."}}}]}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"faild_message":"example"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserCaptionRemovalBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userCaptionRemoval/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userCaptionRemoval/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's caption-removal task identified by `_id`, including its current processing status and available output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records.\n- `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task.\n- `POST /api/v1/userCaptionRemoval/start` — Start caption removal task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Caption Removal"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},{"type":"object","properties":{"faild_message":{"type":"string","nullable":true,"description":"Legacy (misspelled) runtime failure reason written on failed tasks; kept for backward compatibility. Read this field when failed_message is empty."}}}]},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"faild_message":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserCaptionRemovalId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userCaptionRemoval/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete caption removal task","description":"Remove the authenticated user's caption-removal task identified by `_id` from the task history without affecting other records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records.\n- `GET /api/v1/userCaptionRemoval/{_id}` — Get task details.\n- `POST /api/v1/userCaptionRemoval/start` — Start caption removal task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Caption Removal"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the caption removal task"}],"operationId":"deleteApiV1UserCaptionRemovalId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userCaptionRemoval/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userCaptionRemoval/retry":{"post":{"summary":"Retry existing media tasks","description":"Retry an owned, non-deleted task with _id, or a batch with _ids.\nWhen both are supplied, _ids takes precedence. Batch IDs are deduplicated\ncase-insensitively and results retain their first-occurrence order.\nRecords are queried in chunks of 50 and submissions run with at most four\nconcurrent tasks per request. There is no new request-size limit; an empty\nbatch succeeds without submitting work. All batch items are awaited, even\nafter failures. Any failure preserves the top-level error code and HTTP\nstatus of the first failed item in input order; data.results also includes\nsuccessful items so clients can avoid resubmitting them.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Requests another processing attempt for an eligible failed task.\n- Eligibility, charging, and state transitions follow the task-specific rules exposed by the response.\n- Continue monitoring the same or returned task identifier after the retry is accepted.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid request; no tasks submitted.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — A task is absent, deleted, or not owned; batch data.results reports every attempted item.\n- `500` — Existing upstream or database error response, with data.results for batch requests.\n### Related Operations\n- `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records.\n- `GET /api/v1/userCaptionRemoval/{_id}` — Get task details.\n- `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Caption Removal"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","allOf":[{"anyOf":[{"required":["_id"]},{"required":["_ids"]}]}],"properties":{"_id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"},"_ids":{"type":"array","items":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"},"example":["507f1f77bcf86cd799439011"]}},"example":{"_id":"507f1f77bcf86cd799439011"}},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Tasks submitted successfully (code 0).","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Zero on success; existing error code on failure."},"msg":{"type":"string","description":"Existing error message on failure."},"data":{"type":"object","description":"Empty on single-item success; batch responses include per-item results.","properties":{"results":{"type":"array","items":{"type":"object","required":["_id","success"],"properties":{"_id":{"type":"string"},"success":{"type":"boolean"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"msg":"success","data":{"results":[{"_id":"507f1f77bcf86cd799439011","success":true}]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid request; no tasks submitted."},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A task is absent, deleted, or not owned; batch data.results reports every attempted item.","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Zero on success; existing error code on failure."},"msg":{"type":"string","description":"Existing error message on failure."},"data":{"type":"object","description":"Empty on single-item success; batch responses include per-item results.","properties":{"results":{"type":"array","items":{"type":"object","required":["_id","success"],"properties":{"_id":{"type":"string"},"success":{"type":"boolean"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}}},"500":{"description":"Existing upstream or database error response, with data.results for batch requests.","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Zero on success; existing error code on failure."},"msg":{"type":"string","description":"Existing error message on failure."},"data":{"type":"object","description":"Empty on single-item success; batch responses include per-item results.","properties":{"results":{"type":"array","items":{"type":"object","required":["_id","success"],"properties":{"_id":{"type":"string"},"success":{"type":"boolean"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}}}},"operationId":"postApiV1UserCaptionRemovalRetry","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userCaptionRemoval/retry\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/userUpscale/start":{"post":{"summary":"Start upscale task","description":"Create an asynchronous media-upscaling task for the submitted image or video source and return the record used to monitor processing.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `source_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- Non-success responses use the published error envelope; surface the returned message and code to diagnostics.\n### Related Operations\n- `GET /api/v1/userUpscale/allRecords` — Get all task records.\n- `GET /api/v1/userUpscale/{_id}` — Get task details.\n- `DELETE /api/v1/userUpscale/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Upscale"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the upscale task","example":"Upscale media"},"source_url":{"type":"string","description":"URL of the source image or video","example":"https://example.com/video.mp4"},"model_version":{"type":"string","enum":["v1","v2"],"default":"v1","description":"Upscale model. V2 uses BytePlus AI MediaKit, supports video only, and requires a paid user."},"mediakit_tool_version":{"type":"string","enum":["standard","professional"],"default":"standard"},"mediakit_resolution":{"type":"string","enum":["1080p","2k"],"default":"1080p"},"mediakit_bit_depth":{"type":"integer","enum":[8,10,12,16],"description":"Professional version only."},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["source_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"source_url":"https://example.com/video.mp4"}}}},"responses":{"200":{"description":"Upscale task created","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskUpscale"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}},"operationId":"postApiV1UserUpscaleStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userUpscale/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"source_url\": \"https://example.com/video.mp4\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userUpscale/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's media-upscaling tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userUpscale/{_id}` — Get task details.\n- `DELETE /api/v1/userUpscale/{_id}` — Delete task.\n- `POST /api/v1/userUpscale/start` — Start upscale task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Upscale"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskUpscale"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1UserUpscaleAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userUpscale/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userUpscale/allProcessing":{"get":{"summary":"List processing task identifiers and statuses","description":"List processing task identifiers and statuses.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"processing","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserUpscaleAllProcessing","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userUpscale/allProcessing\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userUpscale/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userUpscale/allRecords` — Get all task records.\n- `GET /api/v1/userUpscale/{_id}` — Get task details.\n- `DELETE /api/v1/userUpscale/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Upscale"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskUpscale"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserUpscaleBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userUpscale/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userUpscale/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's media-upscaling task identified by `_id`, including its current processing status and available output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userUpscale/allRecords` — Get all task records.\n- `DELETE /api/v1/userUpscale/{_id}` — Delete task.\n- `POST /api/v1/userUpscale/start` — Start upscale task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Upscale"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskUpscale"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserUpscaleId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userUpscale/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's media-upscaling task identified by `_id` from the task history without affecting other records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userUpscale/allRecords` — Get all task records.\n- `GET /api/v1/userUpscale/{_id}` — Get task details.\n- `POST /api/v1/userUpscale/start` — Start upscale task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Upscale"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1UserUpscaleId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userUpscale/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userUpscale/retry":{"post":{"summary":"Retry existing media tasks","description":"Retry an owned, non-deleted task with _id, or a batch with _ids.\nWhen both are supplied, _ids takes precedence. Batch IDs are deduplicated\ncase-insensitively and results retain their first-occurrence order.\nRecords are queried in chunks of 50 and submissions run with at most four\nconcurrent tasks per request. There is no new request-size limit; an empty\nbatch succeeds without submitting work. All batch items are awaited, even\nafter failures. Any failure preserves the top-level error code and HTTP\nstatus of the first failed item in input order; data.results also includes\nsuccessful items so clients can avoid resubmitting them.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Requests another processing attempt for an eligible failed task.\n- Eligibility, charging, and state transitions follow the task-specific rules exposed by the response.\n- Continue monitoring the same or returned task identifier after the retry is accepted.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid request; no tasks submitted.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — A task is absent, deleted, or not owned; batch data.results reports every attempted item.\n- `500` — Existing upstream or database error response, with data.results for batch requests.\n### Related Operations\n- `GET /api/v1/userUpscale/allRecords` — Get all task records.\n- `GET /api/v1/userUpscale/{_id}` — Get task details.\n- `DELETE /api/v1/userUpscale/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Upscale"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","allOf":[{"anyOf":[{"required":["_id"]},{"required":["_ids"]}]}],"properties":{"_id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"},"_ids":{"type":"array","items":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"},"example":["507f1f77bcf86cd799439011"]}},"example":{"_id":"507f1f77bcf86cd799439011"}},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Success, or an existing business rejection (nonzero code); V2 upscale retries still require creating a new task.","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Zero on success; existing error code on failure."},"msg":{"type":"string","description":"Existing error message on failure."},"data":{"type":"object","description":"Empty on single-item success; batch responses include per-item results.","properties":{"results":{"type":"array","items":{"type":"object","required":["_id","success"],"properties":{"_id":{"type":"string"},"success":{"type":"boolean"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"msg":"success","data":{"results":[{"_id":"507f1f77bcf86cd799439011","success":true}]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid request; no tasks submitted."},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A task is absent, deleted, or not owned; batch data.results reports every attempted item.","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Zero on success; existing error code on failure."},"msg":{"type":"string","description":"Existing error message on failure."},"data":{"type":"object","description":"Empty on single-item success; batch responses include per-item results.","properties":{"results":{"type":"array","items":{"type":"object","required":["_id","success"],"properties":{"_id":{"type":"string"},"success":{"type":"boolean"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}}},"500":{"description":"Existing upstream or database error response, with data.results for batch requests.","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Zero on success; existing error code on failure."},"msg":{"type":"string","description":"Existing error message on failure."},"data":{"type":"object","description":"Empty on single-item success; batch responses include per-item results.","properties":{"results":{"type":"array","items":{"type":"object","required":["_id","success"],"properties":{"_id":{"type":"string"},"success":{"type":"boolean"}}}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}}}},"operationId":"postApiV1UserUpscaleRetry","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userUpscale/retry\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/userText2Image/start":{"post":{"summary":"Start text to image generation","description":"Create one or more asynchronous text-to-image tasks, then return the records used to monitor generated images.\nSelect the image model with `model_type`:\n- `a2e`: auto-select the default image model. It supports text-to-image and image editing with up to two reference images.\n- `zimage`: Z-Image Turbo for text-to-image generation. It does not accept reference images.\n- `seedream`: the Seedream image generation and editing family. Set `model_version` to `4.5`, `5.0`, or `5.0-pro`; Seedream 5.0 Pro accepts up to ten reference images, while 4.5 and 5.0 accept up to two.\nAPI clients should normally set concrete output dimensions with `width` and `height`. The optional `aspect_ratio` and `resolution` fields are also accepted and validated by this endpoint (an unsupported value returns 400), and both are echoed back in the task records, so they are part of the public request contract. For Seedream 5.0 Pro `aspect_ratio` takes precedence over `width`/`height`, and when it is omitted the backend falls back to `9:16`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userText2Image/allRecords` — Get all text to image records.\n- `GET /api/v1/userText2Image/{_id}` — Get text to image record detail.\n- `DELETE /api/v1/userText2Image/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Text to Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the text to image task (optional, auto-generated if not provided)","example":"My Generated Image"},"prompt":{"type":"string","description":"Text prompt for image generation","example":"A beautiful sunset over mountains"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"width":{"type":"number","description":"Image width","default":1024,"example":1024},"height":{"type":"number","description":"Image height","default":1024,"example":1024},"model_type":{"type":"string","description":"Model type to use for generation. Use `a2e` for automatic model selection.","enum":["a2e","zimage","seedream"],"default":"a2e","example":"a2e"},"model_version":{"type":"string","description":"Seedream model version. Required to select Seedream 4.5, 5.0, or 5.0 Pro when model_type is seedream.","enum":["4.5","5.0","5.0-pro"],"default":"4.5","example":"5.0-pro"},"input_images":{"type":"array","description":"Reference images for the auto-selected or Seedream model. Auto selection supports at most 2 images; Seedream 5.0 Pro supports at most 10.","items":{"type":"string"},"maxItems":10,"example":["https://example.com/image1.jpg","https://example.com/image2.jpg"]},"skip_face_enhance":{"type":"boolean","description":"Whether to disable face similarity enhancement for auto-selected image editing. Defaults to false.","default":false,"example":false},"aspect_ratio":{"type":"string","description":"Output aspect ratio for the Seedream family. Rejected with 400 when the value is outside this enum.\nSeedream 5.0 Pro resolves the size from this ratio first and only falls back to `width`/`height` when it is absent, and the backend defaults it to `9:16` for Seedream requests that omit it.\n","enum":["1:1","4:3","3:4","16:9","9:16","2:3","3:2","21:9"],"example":"1:1"},"resolution":{"type":"string","description":"Output resolution tier. Rejected with 400 when the value is outside this enum.\nThe billed tier is the higher of this value and the tier inferred from the short side of `width`/`height`, so a large `width`/`height` cannot be billed as a lower tier. `a2e` and `zimage` only have `1K`, `1080P`, and `2K`; `3K`/`4K` are treated as `2K` for them. For Seedream 5.0 Pro the output size comes from `aspect_ratio` plus this tier, so `width`/`height` never raise an explicitly requested tier there.\nEffective tiers per Seedream version: `5.0-pro` distinguishes only `1K` and `2K` and treats every other value as `2K`; `4.5` and `5.0` raise `1K`/`1080P` to `2K` because Seedream requires at least 3,686,400 pixels, and pass `3K`/`4K` through (`4.5` serves the `4K` tier, `5.0` serves `3K`).\n","enum":["1K","1080P","2K","3K","4K"],"example":"2K"},"max_images":{"type":"integer","description":"Maximum number of images to generate (creates multiple tasks internally)","minimum":1,"maximum":8,"example":1},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"A beautiful sunset over mountains"}}}},"responses":{"200":{"description":"Text to image task started successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Text2ImageStartResponse"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserText2ImageStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userText2Image/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"A beautiful sunset over mountains\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userText2Image/allRecords":{"get":{"summary":"Get all text to image records","description":"Retrieve paginated list of all text to image generation records for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userText2Image/{_id}` — Get text to image record detail.\n- `DELETE /api/v1/userText2Image/{_id}` — Delete task.\n- `POST /api/v1/userText2Image/start` — Start text to image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Text to Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"Number of records per page"}],"operationId":"getApiV1UserText2ImageAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userText2Image/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userText2Image/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userText2Image/allRecords` — Get all text to image records.\n- `GET /api/v1/userText2Image/{_id}` — Get text to image record detail.\n- `DELETE /api/v1/userText2Image/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Text to Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserText2ImageBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userText2Image/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userText2Image/{_id}":{"get":{"summary":"Get text to image record detail","description":"Retrieve detailed information of a specific text to image generation record.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `404` — Record not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userText2Image/allRecords` — Get all text to image records.\n- `DELETE /api/v1/userText2Image/{_id}` — Delete task.\n- `POST /api/v1/userText2Image/start` — Start text to image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Text to Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Record detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Record not found"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Record ID"}],"operationId":"getApiV1UserText2ImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userText2Image/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's text-to-image task identified by `_id` from the task history without affecting other generated-image records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userText2Image/allRecords` — Get all text to image records.\n- `GET /api/v1/userText2Image/{_id}` — Get text to image record detail.\n- `POST /api/v1/userText2Image/start` — Start text to image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Text to Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1UserText2ImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userText2Image/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userText2Image/quickAddAvatar":{"post":{"summary":"Quick add avatar from generated image","description":"Create a custom avatar directly from a text to image generation result.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `_id`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad request.\n- `401` — Unauthorized.\n### Related Operations\n- `GET /api/v1/userText2Image/allRecords` — Get all text to image records.\n- `GET /api/v1/userText2Image/{_id}` — Get text to image record detail.\n- `DELETE /api/v1/userText2Image/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Text to Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Text to image record ID","example":"507f1f77bcf86cd799439011"},"gender":{"type":"string","enum":["female","male"],"description":"Avatar gender","example":"female"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}},"example":{"_id":"507f1f77bcf86cd799439011"}}}},"responses":{"200":{"description":"Avatar created successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}},"operationId":"postApiV1UserText2ImageQuickAddAvatar","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userText2Image/quickAddAvatar\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"_id\": \"507f1f77bcf86cd799439011\"\n}'"}]}},"/api/v1/userNanoBanana/start":{"post":{"summary":"Start Nano Banana image generation","description":"Generate images using Nano Banana models with advanced conversational capabilities and NSFW content pre-filtering.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list.\n- `GET /api/v1/userNanoBanana/detail/{id}` — Get task details.\n- `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Nano Banana"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["prompt"],"properties":{"name":{"type":"string","description":"Optional task name.","example":"Beautiful Landscape"},"prompt":{"type":"string","description":"Text prompt for image generation","example":"A serene mountain landscape at sunset with a crystal clear lake"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"model":{"type":"string","description":"Model to use for generation. Options: nano-banana (no resolution control, auto edit mode with images), nano-banana-pro (with resolution control), nano-banana-2 (with resolution control), nano-banana-2-lite (1K only)","enum":["nano-banana","nano-banana-pro","nano-banana-2","nano-banana-2-lite"],"default":"nano-banana-pro","example":"nano-banana-pro"},"input_images":{"type":"array","items":{"type":"string"},"description":"Array of input image URLs (for editing and composition modes)","example":["https://example.com/image1.jpg"]},"aspect_ratio":{"type":"string","description":"Aspect ratio of the generated image. Options: auto, 16:9, 1:1, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 21:9","enum":["auto","16:9","1:1","9:16","4:3","3:4","2:3","3:2","4:5","5:4","21:9"],"default":"auto","example":"auto"},"image_size":{"type":"string","description":"Size of the generated image. Options: 1K, 2K, 4K. Note: supported by nano-banana-pro and nano-banana-2 models; nano-banana-2-lite is always forced to 1K.","enum":["1K","2K","4K"],"default":"1K","example":"1K"},"google_search":{"type":"boolean","description":"Use Google Web Search grounding to generate images based on real-time information. Only supported by nano-banana-2 model.","default":false},"force_generate":{"type":"boolean","description":"Force generation even if NSFW content is detected. Defaults to true for API users, false for web users","default":true},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}}},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"A serene mountain landscape at sunset with a crystal clear lake"}}}},"responses":{"200":{"description":"Nano Banana task started successfully or NSFW content detected","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["_id"],"not":{"required":["nsfw_detected"]},"properties":{"_id":{"type":"string"},"name":{"type":"string"},"prompt":{"type":"string"},"model":{"type":"string"},"current_status":{"type":"string"},"reference_id":{"type":"string"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["nsfw_detected"],"not":{"required":["_id"]},"properties":{"nsfw_detected":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"Content may violate safety guidelines"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}]},"examples":{"task":{"summary":"Task created","value":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"Beautiful Landscape","current_status":"initialized"}}},"nsfw":{"summary":"Content flagged before task creation","value":{"code":0,"data":{"nsfw_detected":true,"message":"Content may violate safety guidelines"}}}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserNanoBananaStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userNanoBanana/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"A serene mountain landscape at sunset with a crystal clear lake\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userNanoBanana/allRecords":{"get":{"summary":"Get Nano Banana task list","description":"Retrieve paginated list of user's Nano Banana image generation tasks.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`, `status`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userNanoBanana/detail/{id}` — Get task details.\n- `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task.\n- `POST /api/v1/userNanoBanana/start` — Start Nano Banana image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Nano Banana"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"list":{"type":"array","items":{"type":"object"}},"total":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{}],"total":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"description":"Number of items per page"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["initialized","processing","completed","failed"],"example":"initialized"},"description":"Filter by task status"}],"operationId":"getApiV1UserNanoBananaAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userNanoBanana/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userNanoBanana/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list.\n- `GET /api/v1/userNanoBanana/detail/{id}` — Get task details.\n- `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Nano Banana"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskNano"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserNanoBananaBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userNanoBanana/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userNanoBanana/detail/{id}":{"get":{"summary":"Get task details","description":"Retrieve detailed information about a specific Nano Banana task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list.\n- `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task.\n- `POST /api/v1/userNanoBanana/start` — Start Nano Banana image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Nano Banana"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskNano"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserNanoBananaDetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userNanoBanana/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userNanoBanana/delete/{id}":{"delete":{"summary":"Delete task","description":"Soft-delete the authenticated user's Nano Banana image task identified by `id`, preserving the stored record while excluding it from normal task lists.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list.\n- `GET /api/v1/userNanoBanana/detail/{id}` — Get task details.\n- `POST /api/v1/userNanoBanana/start` — Start Nano Banana image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Nano Banana"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1UserNanoBananaDeleteId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userNanoBanana/delete/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userPhotobook/start":{"post":{"summary":"Start photobook generation","description":"Create a photobook generation task using one face image and optional location/clothing prompts. The service will generate 4, 8, 12, or 16 final photos depending on total_count.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `face_image_url`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userPhotobook/allRecords` — Get photobook records.\n- `GET /api/v1/userPhotobook/{id}` — Get photobook record detail.\n- `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Photobook"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name for this photobook batch","example":"Summer Travel Album"},"face_image_url":{"type":"string","description":"Source face image URL used for all generated photos","example":"https://example.com/face.jpg"},"location":{"type":"string","description":"Scene or location prompt","example":"Paris street cafe at golden hour"},"clothing":{"type":"string","description":"Clothing prompt applied during the image edit step","example":"elegant white dress"},"total_count":{"type":"integer","description":"Total number of photos to generate","enum":[4,8,12,16],"default":4,"example":8}},"required":["face_image_url"],"example":{"face_image_url":"https://example.com/face.jpg"}},"example":{"face_image_url":"https://example.com/face.jpg"}}}},"responses":{"200":{"description":"Photobook task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"group_id":{"type":"string","example":"pb_group_123"},"batch_index":{"type":"integer","example":0},"total_count":{"type":"integer","example":8},"current_step":{"type":"string","example":"nano_banana"},"current_status":{"type":"string","example":"processing"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","group_id":"pb_group_123","batch_index":0,"total_count":8,"current_step":"nano_banana","current_status":"processing"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserPhotobookStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userPhotobook/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"face_image_url\": \"https://example.com/face.jpg\"\n}'"}]}},"/api/v1/userPhotobook/allRecords":{"get":{"summary":"Get photobook records","description":"Return the authenticated user's photobook-generation records using `pageNum` and `pageSize`, with newest records presented first.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid pagination parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userPhotobook/{id}` — Get photobook record detail.\n- `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record.\n- `POST /api/v1/userPhotobook/start` — Start photobook generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Photobook"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Photobook records retrieved successfully. hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"list":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"current_status":{"type":"string"},"result_image_urls":{"type":"array","items":{"type":"string"}},"collage_png_url":{"type":"string","nullable":true},"collage_jpg_url":{"type":"string","nullable":true},"edited_collage_url":{"type":"string","nullable":true},"split_image_urls":{"type":"array","items":{"type":"string"}}}}},"total":{"type":"integer","example":12}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","current_status":"processing","result_image_urls":["https://example.com/image.jpg"],"collage_png_url":"https://example.com/file","collage_jpg_url":"https://example.com/file","edited_collage_url":"https://example.com/file","split_image_urls":["https://example.com/image.jpg"]}],"total":12},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Page size"}],"operationId":"getApiV1UserPhotobookAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userPhotobook/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userPhotobook/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple photobook tasks at once by providing an array of task IDs. Only records owned by the authenticated user are returned.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userPhotobook/allRecords` — Get photobook records.\n- `GET /api/v1/userPhotobook/{id}` — Get photobook record detail.\n- `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Photobook"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of photobook task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GenerationImageTaskBasic"},{"type":"object","properties":{"collage_png_url":{"type":"string","nullable":true},"collage_jpg_url":{"type":"string","nullable":true},"edited_collage_url":{"type":"string","nullable":true},"split_image_urls":{"type":"array","items":{"type":"string"}}}}]}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"],"collage_png_url":"https://example.com/file","collage_jpg_url":"https://example.com/file","edited_collage_url":"https://example.com/file","split_image_urls":["https://example.com/image.jpg"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserPhotobookBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userPhotobook/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userPhotobook/{id}":{"get":{"summary":"Get photobook record detail","description":"Get one photobook record by id. The endpoint also syncs the latest pipeline status before returning.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Record not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userPhotobook/allRecords` — Get photobook records.\n- `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record.\n- `POST /api/v1/userPhotobook/start` — Start photobook generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Photobook"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Photobook record detail retrieved successfully. hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"current_step":{"type":"string"},"current_status":{"type":"string"},"result_image_urls":{"type":"array","items":{"type":"string"}},"collage_png_url":{"type":"string","nullable":true},"collage_jpg_url":{"type":"string","nullable":true},"edited_collage_url":{"type":"string","nullable":true},"split_image_urls":{"type":"array","items":{"type":"string"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","current_step":"example","current_status":"processing","result_image_urls":["https://example.com/image.jpg"],"collage_png_url":"https://example.com/file","collage_jpg_url":"https://example.com/file","edited_collage_url":"https://example.com/file","split_image_urls":["https://example.com/image.jpg"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Photobook record id"}],"operationId":"getApiV1UserPhotobookId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userPhotobook/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete photobook record","description":"Remove the photobook record identified by `id` only when it belongs to the authenticated user; unrelated photobook records are unchanged.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Photobook record cannot be deleted in its current status (for example, processing)\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Not Found - Photobook record does not exist or is not accessible by the current user.\n### Related Operations\n- `GET /api/v1/userPhotobook/allRecords` — Get photobook records.\n- `GET /api/v1/userPhotobook/{id}` — Get photobook record detail.\n- `POST /api/v1/userPhotobook/start` — Start photobook generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Photobook"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Photobook record deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"message":{"type":"string","example":"success"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Photobook record cannot be deleted in its current status (for example, processing)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Photobook record does not exist or is not accessible by the current user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Photobook record id"}],"operationId":"deleteApiV1UserPhotobookId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userPhotobook/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userGptImage/start":{"post":{"summary":"Start GPT Image generation or editing","description":"Generate images from text or edit existing images using GPT Image (4o Image) model.\n**Features:**\n- Text-to-Image generation\n- Image-to-Image editing (supports up to 16 reference images)\n- High-fidelity visuals with accurate text rendering\n**Output:**\n- Images are stored in R2 storage and expire after 3 days\n- GPT Image 1.5/2 default to JPEG. GPT Image 2.5 defaults to preserving the upstream PNG; auto and transparent backgrounds are never converted to JPEG.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userGptImage/list` — Get GPT Image task list.\n- `GET /api/v1/userGptImage/detail/{id}` — Get task details.\n- `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["GPT Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the image generation task"},"prompt":{"type":"string","description":"Text prompt for image generation (GPT Image 2.5: max 20000 chars; older models: 3000 chars in the web form)"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"input_images":{"type":"array","items":{"type":"string"},"description":"Array of input image URLs for image-to-image editing (up to 16 images)"},"model":{"type":"string","enum":["gpt-image-1.5","gpt-image-2","gpt-image-2.5-flare","gpt-image-2.5-sunburst"],"default":"gpt-image-1.5","description":"Model variant. GPT Image 1.5 uses quality; GPT Image 2 and 2.5 use resolution. Both GPT Image 2.5 variants default to 20/25/45 credits per image for 1K/2K/4K; current prices come from the feature pricing catalog."},"aspect_ratio":{"type":"string","enum":["auto","1:1","9:16","21:9","16:9","4:3","3:2","3:4","2:3","27:16","16:27","9:8","8:9"],"default":"1:1","description":"GPT Image 1.5 supports 1:1/3:2/2:3. GPT Image 2 supports the nine common ratios. GPT Image 2.5 additionally supports 27:16/16:27/9:8/8:9, which are limited to 1K."},"quality":{"type":"string","enum":["medium","high"],"default":"medium","description":"Image quality level. Only used by gpt-image-1.5"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K","description":"GPT Image 2: auto is limited to 1K; 1:1+4K is normalized to 2K. GPT Image 2.5: 27:16/16:27/9:8/8:9 are normalized to 1K; other ratios, including auto and 1:1, support 1K/2K/4K. Billing uses the normalized resolution."},"save_as_png":{"type":"boolean","description":"Preserve the upstream image without re-encoding. GPT Image 2 defaults to false. GPT Image 2.5 defaults to true and requires preservation for auto or transparent backgrounds; opaque background allows false for JPEG. GPT Image 1.5 always uses JPEG."},"background":{"type":"string","enum":["auto","opaque","transparent"],"default":"auto","description":"GPT Image 2.5 only. Auto may produce transparency. Auto and transparent preserve the upstream PNG regardless of save_as_png."},"force_generate":{"type":"boolean","description":"Force generation even if NSFW content is detected"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["name","prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Task","prompt":"high quality, clear, cinematic"}}}},"responses":{"200":{"description":"Task started successfully or NSFW content detected","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"oneOf":[{"$ref":"#/components/schemas/GenerationImageTaskBasic"},{"$ref":"#/components/schemas/GenerationModerationResult"}]},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserGptImageStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userGptImage/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\",\n  \"prompt\": \"high quality, clear, cinematic\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/imageBackgroundRemoval/start":{"post":{"summary":"Start background removal for any image subject","description":"Submit one image containing a person, product, animal, or other foreground subject. The server uses GPT Image 2.5 Flare image editing with transparent PNG output and the existing GPT Image 2.5 pricing for the selected resolution. This is a generative edit, so small subject details may change; it is not a pixel-exact segmentation mask. Poll GET /api/v1/userGptImage/detail/{id} for current_status and image_url, or provide a webhook for terminal status.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `image_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid source image or resolution.\n- `401` — Unauthorized - Invalid or missing JWT token.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image Background Removal"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"image_url":{"type":"string","format":"uri","description":"Publicly accessible HTTP(S) source image URL."},"name":{"type":"string","description":"Optional task name."},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"webhook_url":{"type":"string","format":"uri"},"webhook_token":{"type":"string"}},"required":["image_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"image_url":"https://example.com/image.jpg"}}}},"responses":{"200":{"description":"Task accepted; data includes _id, current_status, coins, and detail_url.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationBackgroundRemovalStartTask"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"],"detail_url":"/api/v1/userGptImage/detail/507f1f77bcf86cd799439011"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid source image or resolution."},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ImageBackgroundRemovalStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/imageBackgroundRemoval/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"image_url\": \"https://example.com/image.jpg\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userGptImage/list":{"get":{"summary":"Get GPT Image task list","description":"Return the authenticated user's GPT Image generation and editing tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userGptImage/detail/{id}` — Get task details.\n- `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task.\n- `POST /api/v1/userGptImage/start` — Start GPT Image generation or editing.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["GPT Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["list","total","page","page_size"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"total":0,"page":1,"page_size":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"page parameter"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"page_size parameter"}],"operationId":"getApiV1UserGptImageList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userGptImage/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userGptImage/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userGptImage/list` — Get GPT Image task list.\n- `GET /api/v1/userGptImage/detail/{id}` — Get task details.\n- `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["GPT Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserGptImageBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userGptImage/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userGptImage/detail/{id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's GPT Image generation or editing task identified by `id`, including its current status and generated image fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userGptImage/list` — Get GPT Image task list.\n- `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task.\n- `POST /api/v1/userGptImage/start` — Start GPT Image generation or editing.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["GPT Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskBasic"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"getApiV1UserGptImageDetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userGptImage/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userGptImage/{id}":{"delete":{"summary":"Delete GPT Image task","description":"Soft-delete the authenticated user's GPT Image task identified by `id`; the task is excluded from subsequent list results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userGptImage/list` — Get GPT Image task list.\n- `GET /api/v1/userGptImage/detail/{id}` — Get task details.\n- `POST /api/v1/userGptImage/start` — Start GPT Image generation or editing.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["GPT Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"success":true,"message":"success","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1UserGptImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userGptImage/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan26Image/start":{"post":{"summary":"Start a new Wan2.6-Image generation task","description":"Create an asynchronous Wan 2.6 image task from a text prompt, with optional input images and generation controls defined by the request schema.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan26Image/list` — Get task list.\n- `GET /api/v1/userWan26Image/detail/{id}` — Get task details.\n- `DELETE /api/v1/userWan26Image/{id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.6 Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string"},"prompt":{"type":"string","description":"Text prompt (max 2000 chars)"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"input_images":{"type":"array","items":{"type":"string"},"description":"Input images for editing (0-4 images)"},"aspect_ratio":{"type":"string","enum":["1:1","3:2","2:3","4:3","3:4","16:9","9:16","21:9"],"default":"1:1"},"negative_prompt":{"type":"string","description":"Negative prompt (max 500 chars)"},"prompt_extend":{"type":"boolean","default":true,"description":"Enable smart prompt rewriting"},"force_generate":{"type":"boolean"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["name","prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Task","prompt":"high quality, clear, cinematic"}}}},"responses":{"200":{"description":"Task started successfully or NSFW content detected. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"oneOf":[{"$ref":"#/components/schemas/GenerationImageTaskBasic"},{"$ref":"#/components/schemas/GenerationModerationResult"}]},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan26ImageStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan26Image/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\",\n  \"prompt\": \"high quality, clear, cinematic\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userWan26Image/list":{"get":{"summary":"Get task list","description":"Return the authenticated user's Wan 2.6 image tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan26Image/detail/{id}` — Get task details.\n- `DELETE /api/v1/userWan26Image/{id}` — Delete task.\n- `POST /api/v1/userWan26Image/start` — Start a new Wan2.6-Image generation task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.6 Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["list","total","page","page_size"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"total":0,"page":1,"page_size":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"page parameter"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"page_size parameter"}],"operationId":"getApiV1UserWan26ImageList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan26Image/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan26Image/detail/{id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's Wan 2.6 image task identified by `id`, including its current status and generated image fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan26Image/list` — Get task list.\n- `DELETE /api/v1/userWan26Image/{id}` — Delete task.\n- `POST /api/v1/userWan26Image/start` — Start a new Wan2.6-Image generation task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.6 Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskBasic"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"getApiV1UserWan26ImageDetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan26Image/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan26Image/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan26Image/list` — Get task list.\n- `GET /api/v1/userWan26Image/detail/{id}` — Get task details.\n- `DELETE /api/v1/userWan26Image/{id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.6 Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan26ImageBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan26Image/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userWan26Image/{id}":{"delete":{"summary":"Delete task","description":"Soft-delete the authenticated user's Wan 2.6 image task identified by `id`; the task is excluded from subsequent list results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan26Image/list` — Get task list.\n- `GET /api/v1/userWan26Image/detail/{id}` — Get task details.\n- `POST /api/v1/userWan26Image/start` — Start a new Wan2.6-Image generation task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.6 Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"success":true,"message":"success","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1UserWan26ImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userWan26Image/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan27Image/start":{"post":{"summary":"Start a new Wan2.7-Image generation task","description":"Create an asynchronous Wan 2.7 image task from a text prompt, with optional input images and generation controls defined by the request schema.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan27Image/list` — Get task list.\n- `GET /api/v1/userWan27Image/detail/{id}` — Get task details.\n- `DELETE /api/v1/userWan27Image/{id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.7 Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string"},"prompt":{"type":"string","description":"Text prompt (max 5000 chars)"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"model":{"type":"string","enum":["wan2.7-image","wan2.7-image-pro"],"default":"wan2.7-image"},"input_images":{"type":"array","items":{"type":"string"},"description":"Input images for editing (0-9 images, max 20MB each)"},"aspect_ratio":{"type":"string","enum":["1:1","3:2","2:3","4:3","3:4","16:9","9:16","21:9"],"default":"1:1"},"bbox_list":{"type":"array","description":"One list per input image, in the same order as input_images. Use [] for an image with no box. Each image supports up to two boxes; each box is [x1, y1, x2, y2] in absolute pixels of the original image, from top-left to bottom-right.","items":{"type":"array","maxItems":2,"items":{"type":"array","minItems":4,"maxItems":4,"items":{"type":"integer","minimum":0}}},"example":[[],[[989,515,1138,681]]]},"force_generate":{"type":"boolean"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["name","prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Task","prompt":"high quality, clear, cinematic"}}}},"responses":{"200":{"description":"Task started successfully or NSFW content detected. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"oneOf":[{"$ref":"#/components/schemas/GenerationImageTaskBasic"},{"$ref":"#/components/schemas/GenerationModerationResult"}]},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan27ImageStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan27Image/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\",\n  \"prompt\": \"high quality, clear, cinematic\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userWan27Image/list":{"get":{"summary":"Get task list","description":"Return the authenticated user's Wan 2.7 image tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan27Image/detail/{id}` — Get task details.\n- `DELETE /api/v1/userWan27Image/{id}` — Delete task.\n- `POST /api/v1/userWan27Image/start` — Start a new Wan2.7-Image generation task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.7 Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["list","total","page","page_size"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"total":0,"page":1,"page_size":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"page parameter"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"page_size parameter"}],"operationId":"getApiV1UserWan27ImageList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan27Image/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan27Image/detail/{id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's Wan 2.7 image task identified by `id`, including its current status and generated image fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan27Image/list` — Get task list.\n- `DELETE /api/v1/userWan27Image/{id}` — Delete task.\n- `POST /api/v1/userWan27Image/start` — Start a new Wan2.7-Image generation task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.7 Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskBasic"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"getApiV1UserWan27ImageDetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan27Image/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan27Image/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan27Image/list` — Get task list.\n- `GET /api/v1/userWan27Image/detail/{id}` — Get task details.\n- `DELETE /api/v1/userWan27Image/{id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.7 Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan27ImageBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan27Image/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userWan27Image/{id}":{"delete":{"summary":"Delete task","description":"Soft-delete the authenticated user's Wan 2.7 image task identified by `id`; the task is excluded from subsequent list results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan27Image/list` — Get task list.\n- `GET /api/v1/userWan27Image/detail/{id}` — Get task details.\n- `POST /api/v1/userWan27Image/start` — Start a new Wan2.7-Image generation task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan2.7 Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"success":true,"message":"success","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1UserWan27ImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userWan27Image/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userQwen2Image/start":{"post":{"summary":"Start a new Qwen image generation/edit task","description":"Create an asynchronous Qwen Image 2.0 or 3.0 task. The server infers image editing when `input_images` contains a valid HTTP(S) image URL and text-to-image generation otherwise.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userQwen2Image/list` — List Qwen image tasks.\n- `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details.\n- `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Qwen Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["name","prompt"],"properties":{"name":{"type":"string","description":"Task name"},"prompt":{"type":"string","description":"Image generation or editing prompt"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"model":{"type":"string","enum":["qwen-image-2.0","qwen-image-2.0-pro","qwen-image-3.0","qwen-image-3.0-pro"],"default":"qwen-image-2.0"},"input_images":{"type":"array","items":{"type":"string"},"description":"Optional public reference image URLs"},"size":{"type":"string","enum":["1024*1024","1328*880","880*1328","1152*864","864*1152","1280*720","720*1280","1512*648","2048*2048","2048*1365","1365*2048","2048*1536","1536*2048","2048*1152","1152*2048"],"description":"1K sizes are supported by all Qwen Image models. 2K sizes (2048*) are supported only by qwen-image-3.0-pro.","default":"1024*1024"},"negative_prompt":{"type":"string","default":""},"prompt_extend":{"type":"boolean","default":true},"force_generate":{"type":"boolean","description":"Explicitly retry an NSFW soft block. Does not bypass other checks."},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}}},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Task","prompt":"high quality, clear, cinematic"}}}},"responses":{"200":{"description":"Task created successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"oneOf":[{"$ref":"#/components/schemas/GenerationImageTaskBasic"},{"$ref":"#/components/schemas/GenerationModerationResult"}]},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserQwen2ImageStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userQwen2Image/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\",\n  \"prompt\": \"high quality, clear, cinematic\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userQwen2Image/list":{"get":{"summary":"List Qwen image tasks","description":"Return the authenticated user's Qwen image generation and editing tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details.\n- `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task.\n- `POST /api/v1/userQwen2Image/start` — Start a new Qwen image generation/edit task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Qwen Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["list","total","page","page_size"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"total":0,"page":1,"page_size":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number. Uses page/page_size, not pageNum/pageSize."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Rows per page. Backend pagination limits are documented separately when available; do not assume max=100."}],"operationId":"getApiV1UserQwen2ImageList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userQwen2Image/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userQwen2Image/detail/{id}":{"get":{"summary":"Get Qwen image task details","description":"Return the authenticated user's Qwen image task identified by `id`, including its current status and generated image fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userQwen2Image/list` — List Qwen image tasks.\n- `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task.\n- `POST /api/v1/userQwen2Image/start` — Start a new Qwen image generation/edit task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Qwen Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskBasic"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"getApiV1UserQwen2ImageDetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userQwen2Image/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userQwen2Image/batchDetail":{"post":{"summary":"Batch get Qwen image task details","description":"Return up to 200 authenticated-user Qwen image tasks matching the submitted `ids`; callers should match records by identifier.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userQwen2Image/list` — List Qwen image tasks.\n- `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details.\n- `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Qwen Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserQwen2ImageBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userQwen2Image/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userQwen2Image/{id}":{"delete":{"summary":"Delete a Qwen image task","description":"Soft-delete the authenticated user's Qwen image task identified by `id`; the task is excluded from subsequent list results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userQwen2Image/list` — List Qwen image tasks.\n- `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details.\n- `POST /api/v1/userQwen2Image/start` — Start a new Qwen image generation/edit task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Qwen Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1UserQwen2ImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userQwen2Image/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFlux2/start":{"post":{"summary":"Start Flux 2 Pro image generation or editing","description":"Generate high-quality images from text or edit existing images using Flux 2 Pro model.\n**Features:**\n- Text-to-Image generation with advanced prompt understanding\n- Image-to-Image editing (supports up to 8 reference images)\n- Character consistency across multiple images\n- Text rendering within images\n- High-quality output with professional-grade results\n**Processing Time:**\n- Usually 20-60 seconds\n**Output:**\n- Images are stored in R2 storage (3days-apac bucket) and expire 3 days after the task is created (createdAt + 3 days, same as `expirationDate`)\n- Download and persist the result to your own storage before it expires; `image_url` is a temporary CDN URL, not a permanent asset address\n- Expired tasks are omitted from the list endpoint; the detail endpoint still returns the record with `isExpired: true`, but its media URLs are no longer downloadable.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid request parameters.\n- `401` — Unauthorized - Invalid or missing token.\n- `402` — Insufficient credits.\n- `500` — Internal server error.\n### Related Operations\n- `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list.\n- `GET /api/v1/userFlux2/detail/{id}` — Get task details.\n- `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Flux 2"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the image generation task","example":"Elon Musk and Mark Zuckerberg boxing"},"prompt":{"type":"string","description":"Text prompt for image generation or editing instruction.\n","example":"Elon Musk and Mark Zuckerberg boxing in a professional ring"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"input_images":{"type":"array","items":{"type":"string"},"description":"Array of input image URLs for image-to-image editing or multi-image composition (up to 8 images).\nWhen provided, automatically switches to image-to-image mode for character consistency.\n","example":["https://example.com/reference1.jpg","https://example.com/reference2.jpg"]},"aspect_ratio":{"type":"string","description":"Aspect ratio of the generated image. Options: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, custom, match_input_image","enum":["1:1","16:9","9:16","4:3","3:4","2:3","3:2","custom","match_input_image"],"default":"9:16","example":"9:16"},"resolution":{"type":"string","description":"Resolution of the generated image.\n- 1K: ~1 megapixel\n- 2K: ~2 megapixels\n","enum":["1K","2K"],"default":"1K","example":"1K"},"force_generate":{"type":"boolean","description":"Force generation even if NSFW content is detected. Defaults to true for API users, false for web users","default":true},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["name","prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"Elon Musk and Mark Zuckerberg boxing","prompt":"Elon Musk and Mark Zuckerberg boxing in a professional ring"}}}},"responses":{"200":{"description":"Flux 2 Pro task started successfully or NSFW content detected","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Task created successfully","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["_id"],"not":{"required":["nsfw_detected"]},"properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","example":"Elon Musk and Mark Zuckerberg boxing"},"prompt":{"type":"string","example":"Elon Musk and Mark Zuckerberg boxing in a professional ring"},"input_images":{"type":"array","items":{"type":"string"}},"aspect_ratio":{"type":"string","example":"9:16"},"resolution":{"type":"string","example":"1K"},"current_status":{"type":"string","enum":["initialized","processing"],"example":"initialized"},"reference_id":{"type":"string","description":"Unique reference ID for tracking"},"coins":{"type":"integer","description":"Credits deducted for this task","example":10},"createdAt":{"type":"string","format":"date-time"},"expirationDate":{"type":"string","format":"date-time","description":"Date when the generated image expires (createdAt + 3 days)"},"expirationDays":{"type":"integer","description":"Retention period in days","example":3},"remainingDays":{"type":"integer","description":"Days left before the result expires","example":3},"isExpired":{"type":"boolean","description":"Whether the result has expired"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},{"type":"object","description":"NSFW content detected response","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["nsfw_detected"],"not":{"required":["_id"]},"properties":{"nsfw_detected":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"Content may violate safety guidelines. Please modify your prompt or set force_generate=true to continue."},"severity":{"type":"string","enum":["low","medium","high"]},"detected_categories":{"type":"array","items":{"type":"string"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}]},"examples":{"task":{"summary":"Task created","value":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"Flux image","current_status":"initialized"}}},"nsfw":{"summary":"Content flagged before task creation","value":{"code":0,"data":{"nsfw_detected":true,"message":"Content may violate safety guidelines"}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserFlux2Start","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userFlux2/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"Elon Musk and Mark Zuckerberg boxing\",\n  \"prompt\": \"Elon Musk and Mark Zuckerberg boxing in a professional ring\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userFlux2/list":{"get":{"summary":"Get Flux 2 Pro task list","description":"Retrieve paginated list of user's Flux 2 Pro image generation tasks.\nTasks are sorted by creation date (newest first).\nOnly returns tasks that haven't expired (3 days retention, counted from createdAt); expired tasks are omitted rather than flagged.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `page`, `page_size`, `status`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFlux2/detail/{id}` — Get task details.\n- `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task.\n- `POST /api/v1/userFlux2/start` — Start Flux 2 Pro image generation or editing.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Flux 2"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"list":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"prompt":{"type":"string"},"aspect_ratio":{"type":"string"},"resolution":{"type":"string"},"image_url":{"type":"string"},"url_show":{"type":"string"},"url_thumb":{"type":"string"},"current_status":{"type":"string"},"coins":{"type":"integer"},"processing_time":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"expirationDate":{"type":"string","format":"date-time","description":"Date when the image expires (createdAt + 3 days)"},"expirationDays":{"type":"integer","example":3},"remainingDays":{"type":"integer","example":2},"isExpired":{"type":"boolean"}}}},"total":{"type":"integer","description":"Total number of tasks","example":42}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","aspect_ratio":"example","resolution":"example","image_url":"https://example.com/image.jpg","url_show":"https://example.com/file","url_thumb":"https://example.com/file","current_status":"processing","coins":1,"processing_time":1,"createdAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","expirationDays":3,"remainingDays":2,"isExpired":false}],"total":42},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number (starting from 1)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"description":"Number of items per page (max 100)"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["initialized","processing","completed","failed"],"example":"initialized"},"description":"Filter by task status"}],"operationId":"getApiV1UserFlux2List","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFlux2/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFlux2/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list.\n- `GET /api/v1/userFlux2/detail/{id}` — Get task details.\n- `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Flux 2"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskBasic"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserFlux2BatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userFlux2/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userFlux2/detail/{id}":{"get":{"summary":"Get task details","description":"Retrieve detailed information about a specific Flux 2 Pro task, including generation status, image URL, and processing time.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list.\n- `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task.\n- `POST /api/v1/userFlux2/start` — Start Flux 2 Pro image generation or editing.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Flux 2"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"prompt":{"type":"string"},"input_images":{"type":"array","items":{"type":"string"}},"aspect_ratio":{"type":"string"},"resolution":{"type":"string"},"image_url":{"type":"string"},"current_status":{"type":"string","enum":["initialized","processing","completed","failed"]},"failed_message":{"type":"string"},"coins":{"type":"integer"},"processing_time":{"type":"integer","description":"Processing time in milliseconds"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expirationDate":{"type":"string","format":"date-time","description":"Date when the image expires (createdAt + 3 days)"},"expirationDays":{"type":"integer","description":"Retention period in days","example":3},"remainingDays":{"type":"integer","description":"Days left before the result expires","example":2},"isExpired":{"type":"boolean","description":"Whether the result has expired"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","input_images":["example"],"aspect_ratio":"example","resolution":"example","image_url":"https://example.com/image.jpg","current_status":"initialized","failed_message":"example","coins":1,"processing_time":1,"createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","expirationDays":3,"remainingDays":2,"isExpired":false},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Task not found"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserFlux2DetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userFlux2/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userFlux2/{id}":{"delete":{"summary":"Delete Flux 2 Pro task","description":"Soft-delete the authenticated user's Flux 2 Pro image task identified by `id`, preserving the stored record while excluding it from normal task lists.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list.\n- `GET /api/v1/userFlux2/detail/{id}` — Get task details.\n- `POST /api/v1/userFlux2/start` — Start Flux 2 Pro image generation or editing.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Flux 2"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"success":true,"message":"success","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1UserFlux2Id","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userFlux2/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userKlingImage/start":{"post":{"summary":"Start Kling 3.0 image generation","description":"Create one or more asynchronous Kling 3.0 image tasks from the prompt and optional reference images, subject to the request's `n` limit.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userKlingImage/list` — List Kling image tasks.\n- `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details.\n- `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Task name"},"prompt":{"type":"string","description":"Image generation prompt"},"creation_mode":{"type":"string","enum":["text-to-image","image-edit"],"description":"Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."},"input_images":{"type":"array","items":{"type":"string"},"description":"Optional public reference image URLs"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4","2:3","3:2","21:9"],"default":"9:16"},"resolution":{"type":"string","enum":["1k","2k"],"default":"1k"},"n":{"type":"integer","minimum":1,"maximum":9}},"required":["name","prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Task","prompt":"high quality, clear, cinematic"}}}},"responses":{"200":{"description":"Task created successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserKlingImageStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userKlingImage/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\",\n  \"prompt\": \"high quality, clear, cinematic\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userKlingImage/list":{"get":{"summary":"List Kling image tasks","description":"Return the authenticated user's Kling image tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details.\n- `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task.\n- `POST /api/v1/userKlingImage/start` — Start Kling 3.0 image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["list","total","page","page_size"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"page_size":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"list":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"total":0,"page":1,"page_size":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number. Uses page/page_size, not pageNum/pageSize."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Rows per page. Backend pagination limits are documented separately when available; do not assume max=100."}],"operationId":"getApiV1UserKlingImageList","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userKlingImage/list\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userKlingImage/batchDetail":{"post":{"summary":"Batch get Kling image task details","description":"Return up to 200 authenticated-user Kling image tasks matching the submitted `ids`; callers should match records by identifier.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userKlingImage/list` — List Kling image tasks.\n- `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details.\n- `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Image"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Task details","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserKlingImageBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userKlingImage/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userKlingImage/detail/{id}":{"get":{"summary":"Get Kling image task details","description":"Return the authenticated user's Kling image task identified by `id`, including its current status and generated image fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userKlingImage/list` — List Kling image tasks.\n- `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task.\n- `POST /api/v1/userKlingImage/start` — Start Kling 3.0 image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskGeneral"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"getApiV1UserKlingImageDetailId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userKlingImage/detail/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userKlingImage/{id}":{"delete":{"summary":"Delete a Kling image task","description":"Soft-delete the authenticated user's Kling image task identified by `id`; the task is excluded from subsequent list results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userKlingImage/list` — List Kling image tasks.\n- `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details.\n- `POST /api/v1/userKlingImage/start` — Start Kling 3.0 image generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Image"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"success":true,"message":"success","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1UserKlingImageId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userKlingImage/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImageEdit/start":{"post":{"summary":"Start image editing task","description":"Product editing is supported. The legacy clothing mode returns business code 100008 (endpoint deprecated); use POST /api/v1/virtualTryOn/start instead. Code 10000 is reserved for insufficient balance.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `edit_type`, `image_urls`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userImageEdit/allRecords` — Get all task records.\n- `GET /api/v1/userImageEdit/{_id}` — Get task details.\n- `DELETE /api/v1/userImageEdit/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image Edit"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the image edit task","default":"","example":"Product Edit"},"edit_type":{"type":"string","enum":["clothing","product"],"description":"Product is supported; clothing is deprecated and returns code 100008.","example":"product"},"image_urls":{"type":"array","minItems":2,"items":{"type":"string","format":"uri","pattern":"^https?://.*"},"description":"Array of image URLs to edit (minimum 2)","example":["https://example.com/image1.jpg","https://example.com/image2.jpg"]},"timeout":{"type":"number","default":120,"description":"Processing timeout in seconds","example":120},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["edit_type","image_urls"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"edit_type":"product","image_urls":["https://example.com/image1.jpg","https://example.com/image2.jpg"]}}}},"responses":{"200":{"description":"Product image edit task started (code 0), or deprecated clothing mode rejected (code 100008). Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"edit_type":{"type":"string"},"image_urls":{"type":"array","items":{"type":"string"}},"current_status":{"type":"string"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","edit_type":"example","image_urls":["https://example.com/image.jpg"],"current_status":"processing","coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserImageEditStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImageEdit/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"edit_type\": \"product\",\n  \"image_urls\": [\n    \"https://example.com/image1.jpg\",\n    \"https://example.com/image2.jpg\"\n  ]\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userImageEdit/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's image-editing tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userImageEdit/{_id}` — Get task details.\n- `DELETE /api/v1/userImageEdit/{_id}` — Delete task.\n- `POST /api/v1/userImageEdit/start` — Start image editing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image Edit"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskLegacy"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1UserImageEditAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userImageEdit/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImageEdit/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userImageEdit/allRecords` — Get all task records.\n- `GET /api/v1/userImageEdit/{_id}` — Get task details.\n- `DELETE /api/v1/userImageEdit/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image Edit"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserImageEditBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImageEdit/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userImageEdit/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's image-editing task identified by `_id`, including its current processing status and generated image fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userImageEdit/allRecords` — Get all task records.\n- `DELETE /api/v1/userImageEdit/{_id}` — Delete task.\n- `POST /api/v1/userImageEdit/start` — Start image editing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image Edit"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationImageTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserImageEditId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userImageEdit/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's image-editing task identified by `_id` from the task history without affecting other generated-image records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userImageEdit/allRecords` — Get all task records.\n- `GET /api/v1/userImageEdit/{_id}` — Get task details.\n- `POST /api/v1/userImageEdit/start` — Start image editing task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image Edit"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1UserImageEditId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userImageEdit/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/start":{"post":{"summary":"Start image to video conversion","description":"Convert an image to video using AI generation with custom prompts.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userImage2Video/allRecords` — List image to video tasks.\n- `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail.\n- `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the image to video task","example":"My Image Animation"},"image_url":{"type":"string","description":"URL of the source image. Required for image-to-video; omit for text-to-video and reference-to-video.","example":"https://example.com/image.jpg"},"prompt":{"type":"string","description":"Generation prompt","example":"Make the person in the image wave their hand"},"negative_prompt":{"type":"string","description":"Negative prompt to avoid unwanted features","example":"blurry, distorted, static"},"lora":{"type":"string","description":"Lora ID. If provided, prompt/negative_prompt can be omitted (prompt will be overwritten by lora preset on backend)."},"generation_mode":{"type":"string","enum":["image-to-video","text-to-video","reference-to-video"],"default":"image-to-video","description":"Generation mode. Text and reference modes require a2e-v2 or a2e-v2-flash and a nonempty prompt up to 2000 characters. Reference mode accepts video_time of 3, 4, 5, 10 or 15; text mode accepts 5, 10 or 15."},"generation_params":{"type":"object","description":"Text/reference parameters. Omit for image-to-video. Reference mode requires at least one asset; text mode accepts none.","properties":{"aspect_ratio":{"type":"string","enum":["1:1","2:3","3:2","3:4","4:3","9:16","16:9","21:9"],"default":"16:9"},"reference_assets":{"type":"array","maxItems":12,"description":"At most 9 images, 3 videos and 3 audio files. Video and audio clips must each last 2–15 seconds, with at most 15 seconds total per type.","items":{"type":"object","required":["asset_id","type","url"],"properties":{"asset_id":{"type":"string","description":"Unique reference identifier, such as image_1, video_1 or audio_1."},"type":{"type":"string","enum":["image","video","audio"]},"url":{"type":"string","format":"uri"},"duration_seconds":{"type":"number","minimum":2,"maximum":15,"description":"Required for audio. Video duration is measured by the server."}}}}}},"model_type":{"type":"string","enum":["GENERAL","FLF2V"],"default":"GENERAL","description":"Model type for generation"},"model_version":{"type":"string","enum":["a2e","a2e-v2","a2e-v2-flash"],"description":"Algorithm model version. When omitted, Ultra users default to a2e-v2 and other roles default to a2e. a2e-v2 costs more per second; a2e-v2-flash uses a2e pricing. V2 models are not covered by plan waivers."},"auto_add_audio":{"type":"boolean","description":"Whether to add audio. Defaults to false for a2e (paid ThinkSound post-processing) and true for a2e-v2/a2e-v2-flash (native audio with no ThinkSound surcharge)."},"end_image_url":{"type":"string","description":"End image URL (required for FLF2V model)","example":"https://example.com/end_image.jpg"},"extend_prompt":{"type":"boolean","default":true,"description":"Whether to extend the prompt automatically"},"number_of_images":{"type":"integer","minimum":1,"maximum":8,"default":1,"description":"Number of videos to generate at once","example":1},"video_time":{"type":"integer","minimum":3,"maximum":20,"default":5,"description":"Requested video time in integer seconds; billing uses this value. Image-to-video and first-last-frame (FLF2V) support 3-20 seconds; video extension supports 5-20 seconds. Reference mode supports 3, 4, 5, 10 or 15 seconds; text mode supports 5, 10 or 15. V1 3/4-second videos use 49/65 frames at 16fps; V1 durations above 5 seconds retain 5-second segment rounding. V2 output duration rounds up to the next supported 17k+5 frame count at 24fps.","example":5},"video_length":{"type":"integer","minimum":1,"maximum":1000,"description":"(Deprecated) Video length in frames. Prefer video_time. Backend converts frames to seconds internally.","example":81},"skip_face_enhance":{"type":"boolean","default":false,"description":"Whether to skip face similarity enhancement. Defaults to false (enhancing face similarity)."},"mask_face":{"type":"boolean","description":"Web NSFW preflight result. Set true only after the user confirms masking a detected human face."},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Accepted for backward compatibility only. This endpoint has no backend CSAM detection; moderation comes from the algorithm upstream and this flag is not forwarded to it, so setting it does not bypass an upstream 1004."}},"required":[]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Image Animation","image_url":"https://example.com/image.jpg","prompt":"Make the person in the image wave their hand","negative_prompt":"blurry, distorted, static","model_type":"GENERAL","extend_prompt":true,"number_of_images":1,"video_time":5,"skip_face_enhance":false,"mask_face":false}}}},"responses":{"200":{"description":"Image to video task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"image_url":{"type":"string"},"current_status":{"type":"string"},"result_url":{"type":"string"},"cover_url":{"type":"string"},"mask_face":{"type":"boolean","description":"Whether clients should display the privacy-processed input image as the task cover"},"model_type":{"type":"string"},"end_image_url":{"type":"string"},"extend_prompt":{"type":"boolean"},"lora":{"type":"string"},"video_time":{"type":"number"},"video_length":{"type":"number"},"coins":{"type":"number"},"remainingDays":{"type":"number"},"expirationDate":{"type":"string"},"isExpired":{"type":"boolean"},"expirationDays":{"type":"number"},"total_videos":{"type":"number","description":"Present only when number_of_images > 1"},"all_records":{"type":"array","description":"Present only when number_of_images > 1","items":{"type":"object"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","current_status":"processing","result_url":"https://example.com/file","cover_url":"https://example.com/file","mask_face":false,"model_type":"example","end_image_url":"https://example.com/image.jpg","extend_prompt":true,"lora":"example","video_time":5,"video_length":1,"coins":1,"remainingDays":1,"expirationDate":"2026-01-01T00:00:00Z","isExpired":false,"expirationDays":1,"total_videos":1,"all_records":[{}]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserImage2VideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Image Animation\",\n  \"image_url\": \"https://example.com/image.jpg\",\n  \"prompt\": \"Make the person in the image wave their hand\",\n  \"negative_prompt\": \"blurry, distorted, static\",\n  \"model_type\": \"GENERAL\",\n  \"extend_prompt\": true,\n  \"number_of_images\": 1,\n  \"video_time\": 5,\n  \"skip_face_enhance\": false,\n  \"mask_face\": false\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userImage2Video/allRecords":{"get":{"summary":"List image to video tasks","description":"List current user's image to video tasks (only non-expired records will be returned).\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail.\n- `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.\n- `POST /api/v1/userImage2Video/start` — Start image to video conversion.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list fetched successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"count":{"type":"number"},"rows":{"type":"array","items":{"type":"object"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"count":1,"rows":[{}]},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"pageSize parameter"}],"operationId":"getApiV1UserImage2VideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userImage2Video/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userImage2Video/allRecords` — List image to video tasks.\n- `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail.\n- `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},{"type":"object","properties":{"display_result_url":{"type":"string","description":"Preferred playback/download URL: the completed auto-audio result when auto_audio_status is completed, otherwise result_url (the silent original)."},"auto_add_audio":{"type":"boolean"},"auto_audio_status":{"type":"string","description":"off when auto audio is not requested or the model uses native audio; otherwise pending until the audio task reports its status."},"auto_audio_task_id":{"type":"string","nullable":true},"auto_audio_result_url":{"type":"string","description":"Completed video with generated audio; empty until available."},"auto_audio_failed_code":{"type":"string"},"auto_audio_failed_message":{"type":"string"},"model_version":{"type":"string"}}}]}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"display_result_url":"https://example.com/file","auto_add_audio":false,"auto_audio_status":"processing","auto_audio_task_id":"507f1f77bcf86cd799439011","auto_audio_result_url":"https://example.com/audio.mp3","auto_audio_failed_code":"example","auto_audio_failed_message":"example","model_version":"example"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserImage2VideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userImage2Video/avgProcessingTime":{"get":{"summary":"Get image-to-video processing estimates","description":"Get image-to-video processing estimates.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared.\n- `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded.\n- `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","properties":{"avgProcessingTime":{"type":"number"},"avgProcessingTimeFLF2V":{"type":"number"},"avgProcessingTimeUnlimited":{"type":"number"},"unlimitedQueueLevel":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"avgProcessingTime":1,"avgProcessingTimeFLF2V":1,"avgProcessingTimeUnlimited":1,"unlimitedQueueLevel":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserImage2VideoAvgProcessingTime","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userImage2Video/avgProcessingTime\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/unlimitedQueueLevel":{"get":{"summary":"Get image-to-video unlimited queue level","description":"Get image-to-video unlimited queue level.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared.\n- `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded.\n- `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","properties":{"level":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"level":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1UserImage2VideoUnlimitedQueueLevel","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userImage2Video/unlimitedQueueLevel\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/{_id}/markShared":{"post":{"summary":"Mark an image-to-video task as shared","description":"Mark an image-to-video task as shared.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Records the named client interaction for the identified task.\n- The operation does not regenerate or otherwise modify the task's media output.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded.\n- `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied.\n- `GET /api/v1/userImage2Video/avgProcessingTime` — Get image-to-video processing estimates.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","nullable":true},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"postApiV1UserImage2VideoIdMarkShared","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011/markShared\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/{_id}/markDownloaded":{"post":{"summary":"Mark an image-to-video task as downloaded","description":"Mark an image-to-video task as downloaded.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Records the named client interaction for the identified task.\n- The operation does not regenerate or otherwise modify the task's media output.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared.\n- `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied.\n- `GET /api/v1/userImage2Video/avgProcessingTime` — Get image-to-video processing estimates.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","nullable":true},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"postApiV1UserImage2VideoIdMarkDownloaded","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011/markDownloaded\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/{_id}/markCopied":{"post":{"summary":"Mark an image-to-video task as copied","description":"Mark an image-to-video task as copied.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Records the named client interaction for the identified task.\n- The operation does not regenerate or otherwise modify the task's media output.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared.\n- `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded.\n- `GET /api/v1/userImage2Video/avgProcessingTime` — Get image-to-video processing estimates.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","nullable":true},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"postApiV1UserImage2VideoIdMarkCopied","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011/markCopied\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/{_id}":{"get":{"summary":"Get image to video task detail","description":"Get one image to video task detail by id.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Not Found - Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userImage2Video/allRecords` — List image to video tasks.\n- `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.\n- `POST /api/v1/userImage2Video/start` — Start image to video conversion.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail fetched successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserImage2VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete an image to video task","description":"Soft-delete the user's image-to-video task. `initialized` is queued, not terminal: it can be deleted with a coin refund only after at least 60 seconds from creation. Before then, or while `sent`, `pending`, or `processing`, deletion returns HTTP 400 / code 30101. `completed`, `failed`, and `blocked` (including legacy `block`) can be deleted without this refund. Deletion does not guarantee physical media removal.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userImage2Video/allRecords` — List image to video tasks.\n- `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail.\n- `POST /api/v1/userImage2Video/start` — Start image to video conversion.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Empty object; this response is not a refund receipt."},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"deleteApiV1UserImage2VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userImage2Video/prompt_extension":{"post":{"summary":"Extend prompt for image to video","description":"Extend a prompt for general image-to-video with LLM.\nChoose JSON (default) or SSE by setting stream: true or Accept: text/event-stream.\nSSE responses have Content-Type: text/event-stream; charset=utf-8 and HTTP 200.\nEvery frame is data: <JSON> followed by two newlines. There are no SSE event: or id: lines; dispatch on the JSON type field.\nZero or more delta events contain text: the entire current visible preview, not a token to append. Replace the preview with each snapshot.\nSuccess sends result with data.prompt (English for generation) and data.prompt_localized (lang for display), then done, then closes.\nFailure after streaming starts sends error with code (string or number), message, and trace_id, then closes without result/done. HTTP 200 alone does not prove success.\nValidation/authentication and other failures before streaming starts use the normal JSON HTTP error response (for example 400/401). Check HTTP status and Content-Type before parsing.\nClient disconnection aborts upstream work. No terminal frame, replay, automatic retry, or resume ID is guaranteed after a disconnect; discard an incomplete preview or explicitly start a new POST.\ncURL streaming example (replace token and accessible image URL; FLF2V also requires end_image_url):\n```sh\ncurl -N -X POST \"https://headswap.app/api/v1/userImage2Video/prompt_extension\" \\\n  -H 'Authorization: Bearer YOUR_A2E_API_KEY' \\\n  -H 'Content-Type: application/json' -H 'Accept: text/event-stream' \\\n  --data '{\"reference_id\": \"client-request\", \"image_url\": \"https://example.invalid/start.png\", \"prompt\": \"A moving camera\", \"negative_prompt\": \"\", \"lang\": \"en\", \"stream\": true}'\n```\nMinimal POST response parser (UTF-8 chunks and SSE frame boundaries can split arbitrarily):\n```js\nasync function readPromptExtension(response, onPreview = () => {}) {\n  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);\n  if (!response.headers.get('content-type')?.includes('text/event-stream')) return (await response.json()).data;\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '', result;\n  try {\n    while (true) {\n      const chunk = await reader.read();\n      buffer += decoder.decode(chunk.value, { stream: !chunk.done });\n      let boundary;\n      while ((boundary = /\\r?\\n\\r?\\n/.exec(buffer))) {\n        const block = buffer.slice(0, boundary.index);\n        buffer = buffer.slice(boundary.index + boundary[0].length);\n        const data = block.split(/\\r?\\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\\n');\n        if (!data) continue;\n        const event = JSON.parse(data);\n        if (event.type === 'delta') onPreview(event.text);\n        if (event.type === 'result') result = event.data;\n        if (event.type === 'error') throw Object.assign(new Error(event.message), { code: event.code, trace_id: event.trace_id });\n        if (event.type === 'done') {\n          if (!result) throw new Error('Missing result before done');\n          return result;\n        }\n      }\n      if (chunk.done) throw new Error('Stream ended before done');\n    }\n  } finally {\n    await reader.cancel();\n  }\n}\n```\nCall readPromptExtension with a fetch POST response and a preview callback. Pass an AbortController signal to fetch and call abort() to disconnect; keep the returned final data rather than the preview.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `reference_id`, `image_url`, `prompt`, `negative_prompt`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `422` — JSON mode - LLM returned invalid prompt format (code LLM_INVALID_RESPONSE). In SSE mode this is a terminal error data frame under HTTP 200.\n- `500` — JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200.\n### Related Operations\n- `GET /api/v1/userImage2Video/allRecords` — List image to video tasks.\n- `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail.\n- `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"image_url":{"type":"string","example":"https://example.com/image.jpg"},"prompt":{"type":"string","example":"high quality, clear, cinematic"},"negative_prompt":{"type":"string","example":"blurry, low quality, watermark, distorted"},"lang":{"type":"string","default":"en","example":"en"},"max_length":{"type":"integer","description":"Optional hard character limit for generated prompts. This is not a target length.","example":1},"stream":{"type":"boolean","description":"Set to true for SSE; Accept text/event-stream also selects SSE. False or omitted with a JSON Accept returns JSON.","example":false},"template":{"type":"string","enum":["default","cinematic"],"default":"default","description":"Prompt style. \"default\" keeps the original single-shot rewrite. \"cinematic\" returns a multi-shot film structure (scene bible, SHOT 1..N, Audio), intended for models that support cuts and audio.\n","example":"default"},"shot_count":{"type":"integer","default":2,"description":"Number of shots for the cinematic template. Any integer is accepted; the server clamps out-of-range values to 1-4. Ignored by the default template.\n","example":2},"with_audio":{"type":"boolean","default":true,"description":"Whether the cinematic template appends an Audio section. Ignored by the default template.","example":true}},"required":["reference_id","image_url","prompt","negative_prompt"],"example":{"reference_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/image.jpg","prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted"}},"example":{"reference_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/image.jpg","prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted"}}}},"responses":{"200":{"description":"JSON prompt result or SSE stream; a stream error can occur after HTTP 200.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"data":{"type":"object","required":["prompt","prompt_localized"],"properties":{"prompt":{"type":"string","description":"English prompt for generation."},"prompt_localized":{"type":"string","description":"Display prompt in the requested lang; English locales use the English prompt."}}},"trace_id":{"type":"string","description":"Request trace identifier when supplied by the response middleware."}}},"example":{"code":0,"data":{"prompt":"high quality, clear, cinematic","prompt_localized":"high quality, clear, cinematic"},"trace_id":"507f1f77bcf86cd799439011"}},"text/event-stream":{"schema":{"type":"string","description":"UTF-8 SSE frames containing JSON data; use x-sse-data-schema for each decoded data payload.","x-sse-data-schema":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["delta"]},"text":{"type":"string","description":"Cumulative visible preview; replace rather than append."}}},{"type":"object","required":["type","data"],"properties":{"type":{"type":"string","enum":["result"]},"data":{"type":"object","required":["prompt","prompt_localized"],"properties":{"prompt":{"type":"string","description":"Final English generation prompt."},"prompt_localized":{"type":"string","description":"Final display prompt in the requested language."}}}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["done"]}}},{"type":"object","required":["type","code","message","trace_id"],"properties":{"type":{"type":"string","enum":["error"]},"code":{"oneOf":[{"type":"string"},{"type":"number"}]},"message":{"type":"string","description":"User-visible error; internal failures may be masked."},"trace_id":{"type":"string","description":"Request trace identifier for support."}}}]}},"examples":{"success":{"summary":"Preview snapshots, then result and done","value":"data: {\"type\":\"delta\",\"text\":\"A\"}\n\ndata: {\"type\":\"delta\",\"text\":\"A moving camera\"}\n\ndata: {\"type\":\"result\",\"data\":{\"prompt\":\"A moving camera\",\"prompt_localized\":\"A moving camera\"}}\n\ndata: {\"type\":\"done\"}\n\n"},"error":{"summary":"Stream business failure (HTTP status remains 200)","value":"data: {\"type\":\"error\",\"code\":\"LLM_INVALID_RESPONSE\",\"message\":\"LLM returned invalid format\",\"trace_id\":\"request-trace\"}\n\n"}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"JSON mode - LLM returned invalid prompt format (code LLM_INVALID_RESPONSE). In SSE mode this is a terminal error data frame under HTTP 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserImage2VideoPromptExtension","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/prompt_extension\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"reference_id\": \"507f1f77bcf86cd799439011\",\n  \"image_url\": \"https://example.com/image.jpg\",\n  \"prompt\": \"high quality, clear, cinematic\",\n  \"negative_prompt\": \"blurry, low quality, watermark, distorted\"\n}'"}]}},"/api/v1/userImage2Video/flf2v_prompt_extension":{"post":{"summary":"Extend prompt for FLF2V image to video","description":"Extend an FLF2V prompt with LLM; end_image_url is required.\nChoose JSON (default) or SSE by setting stream: true or Accept: text/event-stream.\nSSE responses have Content-Type: text/event-stream; charset=utf-8 and HTTP 200.\nEvery frame is data: <JSON> followed by two newlines. There are no SSE event: or id: lines; dispatch on the JSON type field.\nZero or more delta events contain text: the entire current visible preview, not a token to append. Replace the preview with each snapshot.\nSuccess sends result with data.prompt (English for generation) and data.prompt_localized (lang for display), then done, then closes.\nFailure after streaming starts sends error with code (string or number), message, and trace_id, then closes without result/done. HTTP 200 alone does not prove success.\nValidation/authentication and other failures before streaming starts use the normal JSON HTTP error response (for example 400/401). Check HTTP status and Content-Type before parsing.\nClient disconnection aborts upstream work. No terminal frame, replay, automatic retry, or resume ID is guaranteed after a disconnect; discard an incomplete preview or explicitly start a new POST.\ncURL streaming example (replace token and accessible image URL; FLF2V also requires end_image_url):\n```sh\ncurl -N -X POST \"https://headswap.app/api/v1/userImage2Video/flf2v_prompt_extension\" \\\n  -H 'Authorization: Bearer YOUR_A2E_API_KEY' \\\n  -H 'Content-Type: application/json' -H 'Accept: text/event-stream' \\\n  --data '{\"reference_id\": \"client-request\", \"image_url\": \"https://example.invalid/start.png\", \"prompt\": \"A moving camera\", \"negative_prompt\": \"\", \"lang\": \"en\", \"stream\": true, \"end_image_url\": \"https://example.invalid/end.png\"}'\n```\nMinimal POST response parser (UTF-8 chunks and SSE frame boundaries can split arbitrarily):\n```js\nasync function readPromptExtension(response, onPreview = () => {}) {\n  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);\n  if (!response.headers.get('content-type')?.includes('text/event-stream')) return (await response.json()).data;\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '', result;\n  try {\n    while (true) {\n      const chunk = await reader.read();\n      buffer += decoder.decode(chunk.value, { stream: !chunk.done });\n      let boundary;\n      while ((boundary = /\\r?\\n\\r?\\n/.exec(buffer))) {\n        const block = buffer.slice(0, boundary.index);\n        buffer = buffer.slice(boundary.index + boundary[0].length);\n        const data = block.split(/\\r?\\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\\n');\n        if (!data) continue;\n        const event = JSON.parse(data);\n        if (event.type === 'delta') onPreview(event.text);\n        if (event.type === 'result') result = event.data;\n        if (event.type === 'error') throw Object.assign(new Error(event.message), { code: event.code, trace_id: event.trace_id });\n        if (event.type === 'done') {\n          if (!result) throw new Error('Missing result before done');\n          return result;\n        }\n      }\n      if (chunk.done) throw new Error('Stream ended before done');\n    }\n  } finally {\n    await reader.cancel();\n  }\n}\n```\nCall readPromptExtension with a fetch POST response and a preview callback. Pass an AbortController signal to fetch and call abort() to disconnect; keep the returned final data rather than the preview.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `reference_id`, `image_url`, `end_image_url`, `prompt`, `negative_prompt`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `422` — JSON mode - LLM returned invalid prompt format (code LLM_INVALID_RESPONSE). In SSE mode this is a terminal error data frame under HTTP 200.\n- `500` — JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200.\n### Related Operations\n- `GET /api/v1/userImage2Video/allRecords` — List image to video tasks.\n- `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail.\n- `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.","tags":["Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"image_url":{"type":"string","example":"https://example.com/image.jpg"},"end_image_url":{"type":"string","example":"https://example.com/image.jpg"},"prompt":{"type":"string","example":"high quality, clear, cinematic"},"negative_prompt":{"type":"string","example":"blurry, low quality, watermark, distorted"},"lang":{"type":"string","default":"en","example":"en"},"max_length":{"type":"integer","description":"Optional hard character limit for generated prompts. This is not a target length.","example":1},"stream":{"type":"boolean","description":"Set to true for SSE; Accept text/event-stream also selects SSE. False or omitted with a JSON Accept returns JSON.","example":false}},"required":["reference_id","image_url","end_image_url","prompt","negative_prompt"],"example":{"reference_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/image.jpg","end_image_url":"https://example.com/image.jpg","prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted"}},"example":{"reference_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/image.jpg","end_image_url":"https://example.com/image.jpg","prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted"}}}},"responses":{"200":{"description":"JSON prompt result or SSE stream; a stream error can occur after HTTP 200.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"data":{"type":"object","required":["prompt","prompt_localized"],"properties":{"prompt":{"type":"string","description":"English prompt for generation."},"prompt_localized":{"type":"string","description":"Display prompt in the requested lang; English locales use the English prompt."}}},"trace_id":{"type":"string","description":"Request trace identifier when supplied by the response middleware."}}},"example":{"code":0,"data":{"prompt":"high quality, clear, cinematic","prompt_localized":"high quality, clear, cinematic"},"trace_id":"507f1f77bcf86cd799439011"}},"text/event-stream":{"schema":{"type":"string","description":"UTF-8 SSE frames containing JSON data; use x-sse-data-schema for each decoded data payload.","x-sse-data-schema":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["delta"]},"text":{"type":"string","description":"Cumulative visible preview; replace rather than append."}}},{"type":"object","required":["type","data"],"properties":{"type":{"type":"string","enum":["result"]},"data":{"type":"object","required":["prompt","prompt_localized"],"properties":{"prompt":{"type":"string","description":"Final English generation prompt."},"prompt_localized":{"type":"string","description":"Final display prompt in the requested language."}}}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["done"]}}},{"type":"object","required":["type","code","message","trace_id"],"properties":{"type":{"type":"string","enum":["error"]},"code":{"oneOf":[{"type":"string"},{"type":"number"}]},"message":{"type":"string","description":"User-visible error; internal failures may be masked."},"trace_id":{"type":"string","description":"Request trace identifier for support."}}}]}},"examples":{"success":{"summary":"Preview snapshots, then result and done","value":"data: {\"type\":\"delta\",\"text\":\"A\"}\n\ndata: {\"type\":\"delta\",\"text\":\"A moving camera\"}\n\ndata: {\"type\":\"result\",\"data\":{\"prompt\":\"A moving camera\",\"prompt_localized\":\"A moving camera\"}}\n\ndata: {\"type\":\"done\"}\n\n"},"error":{"summary":"Stream business failure (HTTP status remains 200)","value":"data: {\"type\":\"error\",\"code\":\"LLM_INVALID_RESPONSE\",\"message\":\"LLM returned invalid format\",\"trace_id\":\"request-trace\"}\n\n"}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"JSON mode - LLM returned invalid prompt format (code LLM_INVALID_RESPONSE). In SSE mode this is a terminal error data frame under HTTP 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserImage2VideoFlf2vPromptExtension","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userImage2Video/flf2v_prompt_extension\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"reference_id\": \"507f1f77bcf86cd799439011\",\n  \"image_url\": \"https://example.com/image.jpg\",\n  \"end_image_url\": \"https://example.com/image.jpg\",\n  \"prompt\": \"high quality, clear, cinematic\",\n  \"negative_prompt\": \"blurry, low quality, watermark, distorted\"\n}'"}]}},"/api/v1/userWan25/start":{"post":{"summary":"Start Wan video generation","description":"Start a Wan video generation task. This endpoint supports Wan 2.5 image-to-video, Wan 2.6 image-to-video and Wan 2.7 multi-mode video generation.\nFor Wan 2.7, set `model` to `wan2.7-i2v` and select the generation mode with `task_type`:\n- `text_to_video`: text prompt only. Do not provide image/video material.\n- `first_frame`: image-to-video from one first-frame image. Requires `image_url`.\n- `first_last_frame`: image-to-video with first and last frame control. Requires `image_url` and `last_frame_url`.\n- `reference_image`: reference-to-video. Requires 1 to 5 ordered image/video entries in `reference_media`; legacy pure-image clients may continue using `reference_image_urls`.\n- `video_extend`: extend an existing video clip. Requires `first_clip_url`; optional `last_frame_url`.\n- `video_edit`: edit an existing video. Requires `edit_video_url`; optional `reference_image_urls` with up to 3 image URLs.\n`text_to_video`, `first_last_frame`, `reference_image`, `video_extend` and `video_edit` are only available when `model=wan2.7-i2v`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Optional display name for the task","example":"My Wan Video"},"image_url":{"type":"string","description":"Source image URL. Required for `first_frame` and `first_last_frame`.","example":"https://example.com/image.jpg"},"prompt":{"type":"string","description":"Generation prompt","example":"Make the person in the image wave their hand"},"negative_prompt":{"type":"string","description":"Negative prompt to avoid unwanted features","example":"blurry, distorted"},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5","description":"Video duration in seconds. Wan 2.6 and Wan 2.7 accept any integer from 2 to 15, except: reference_image drops to 2-10 when a reference video is present, and video_edit uses 5-10. Wan 2.5 only supports 5/10."},"resolution":{"type":"string","enum":["480p","720p","1080p"],"default":"720p","description":"Video resolution"},"ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4"],"default":"16:9","description":"Video aspect ratio. Only used by Wan 2.7 `text_to_video` and `reference_image`."},"enable_prompt_expansion":{"type":"boolean","default":false,"description":"Whether to enable prompt rewriting using LLM"},"multi_shots":{"type":"boolean","default":false,"description":"Enable intelligent multi-shot segmentation (only active when enable_prompt_expansion is true)"},"model":{"type":"string","enum":["wan2.5-i2v-preview","wan2.6-i2v","wan2.6-i2v-flash","wan2.7-i2v"],"default":"wan2.5-i2v-preview","description":"AI model version (wan2.6-i2v and wan2.7-i2v require VIP/Max user, wan2.6-i2v-flash is available to all users)"},"task_type":{"type":"string","enum":["text_to_video","first_frame","first_last_frame","reference_image","video_extend","video_edit"],"default":"first_frame","description":"Wan 2.7 generation mode. Only used when `model=wan2.7-i2v`."},"last_frame_url":{"type":"string","description":"Last-frame image URL. Required for `first_last_frame`; optional for `video_extend`.","example":"https://example.com/last-frame.jpg"},"first_clip_url":{"type":"string","description":"Existing video clip URL. Required for Wan 2.7 `video_extend`.","example":"https://example.com/clip.mp4"},"edit_video_url":{"type":"string","description":"Input video URL. Required for Wan 2.7 `video_edit`.","example":"https://example.com/input-video.mp4"},"reference_image_urls":{"type":"array","items":{"type":"string"},"description":"Legacy pure-image reference URLs for Wan 2.7 `reference_image`; optional for `video_edit` (up to 3 images).","example":["https://example.com/reference-1.jpg","https://example.com/reference-2.jpg"]},"reference_media":{"type":"array","minItems":1,"maxItems":5,"description":"Ordered Wan2.7 reference-to-video media. Input videos are billed together with output duration according to the official 5-second input cap.","items":{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","enum":["reference_image","reference_video"]},"url":{"type":"string"},"duration":{"type":"number","description":"Reference video duration in seconds. The server probes metadata when omitted."}}}},"seed":{"type":"number","minimum":0,"maximum":2147483647,"description":"Random seed for reproducibility. Value must be in the range [0, 2147483647]. If not specified, system generates a random seed."},"audio":{"type":"boolean","default":true,"description":"Whether to generate audio for the video"},"audio_url":{"type":"string","description":"URL of audio file to use for first-frame/first-last-frame video generation. Supports WAV/MP3, 3-30s duration, max 15MB. If longer than video duration, audio will be truncated.","example":"https://example.com/audio.mp3"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt"],"x-duration-options-by-task-type":{"text_to_video":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"first_frame":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"first_last_frame":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"reference_image":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"video_extend":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"video_edit":["5","6","7","8","9","10"]},"anyOf":[{"title":"Wan 2.5 first frame","type":"object","properties":{"model":{"type":"string","enum":["wan2.5-i2v-preview"]},"task_type":{"type":"string","enum":["first_frame"],"default":"first_frame"},"duration":{"type":"string","enum":["5","10"],"default":"5"}}},{"title":"Wan 2.6 first frame","type":"object","properties":{"model":{"type":"string","enum":["wan2.6-i2v","wan2.6-i2v-flash"]},"task_type":{"type":"string","enum":["first_frame"]},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"}}},{"title":"Wan 2.7 text to video","type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v"]},"task_type":{"type":"string","enum":["text_to_video"]},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"}}},{"title":"Wan 2.7 first frame","type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v"]},"task_type":{"type":"string","enum":["first_frame"]},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"}}},{"title":"Wan 2.7 first and last frame","type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v"]},"task_type":{"type":"string","enum":["first_last_frame"]},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"}}},{"title":"Wan 2.7 reference image","type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v"]},"task_type":{"type":"string","enum":["reference_image"]},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"}}},{"title":"Wan 2.7 video extension","type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v"]},"task_type":{"type":"string","enum":["video_extend"]},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"}}},{"title":"Wan 2.7 video edit","type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v"]},"task_type":{"type":"string","enum":["video_edit"]},"duration":{"type":"string","enum":["5","6","7","8","9","10"],"default":"5"}}}]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Wan 2.7 Reference Video","model":"wan2.7-i2v","task_type":"reference_image","reference_image_urls":["https://example.com/reference-1.jpg","https://example.com/reference-2.jpg"],"prompt":"Create a cinematic video matching the subject and visual style of the reference images","negative_prompt":"blurry, distorted","duration":"5","resolution":"720p","ratio":"16:9","enable_prompt_expansion":false}}}},"responses":{"200":{"description":"Wan video task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"image_url":{"type":"string"},"current_status":{"type":"string"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","current_status":"processing","coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan25Start","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan25/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Wan 2.7 Reference Video\",\n  \"model\": \"wan2.7-i2v\",\n  \"task_type\": \"reference_image\",\n  \"reference_image_urls\": [\n    \"https://example.com/reference-1.jpg\",\n    \"https://example.com/reference-2.jpg\"\n  ],\n  \"prompt\": \"Create a cinematic video matching the subject and visual style of the reference images\",\n  \"negative_prompt\": \"blurry, distorted\",\n  \"duration\": \"5\",\n  \"resolution\": \"720p\",\n  \"ratio\": \"16:9\",\n  \"enable_prompt_expansion\": false\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userWan25/allRecords":{"get":{"summary":"Get all Wan 2.5 tasks","description":"Return the authenticated user's Wan 2.5 image-to-video tasks using the requested pagination controls, including current status and available output metadata.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan25/{_id}` — Get Wan 2.5 task details.\n- `DELETE /api/v1/userWan25/{_id}` — Delete a Wan 2.5 task.\n- `POST /api/v1/userWan25/batchDetail` — Batch query task details.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{}],"count":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"Number of items per page"}],"operationId":"getApiV1UserWan25AllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan25/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan25/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan25/allRecords` — Get all Wan 2.5 tasks.\n- `GET /api/v1/userWan25/{_id}` — Get Wan 2.5 task details.\n- `DELETE /api/v1/userWan25/{_id}` — Delete a Wan 2.5 task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan25BatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan25/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userWan25/{_id}":{"get":{"summary":"Get Wan 2.5 task details","description":"Return the authenticated user's Wan 2.5 image-to-video task identified by `_id`, including its generation settings, current status, and available video output.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan25/allRecords` — Get all Wan 2.5 tasks.\n- `DELETE /api/v1/userWan25/{_id}` — Delete a Wan 2.5 task.\n- `POST /api/v1/userWan25/batchDetail` — Batch query task details.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"image_url":{"type":"string"},"prompt":{"type":"string"},"current_status":{"type":"string"},"result_url":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","prompt":"high quality, clear, cinematic","current_status":"processing","result_url":"https://example.com/file"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1UserWan25Id","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan25/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete a Wan 2.5 task","description":"Remove the authenticated user's Wan 2.5 image-to-video task identified by `_id` from normal task history without affecting unrelated tasks.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan25/allRecords` — Get all Wan 2.5 tasks.\n- `GET /api/v1/userWan25/{_id}` — Get Wan 2.5 task details.\n- `POST /api/v1/userWan25/batchDetail` — Batch query task details.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"deleteApiV1UserWan25Id","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userWan25/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan26R2V/start":{"post":{"summary":"Start reference-to-video generation","description":"Generate a video from reference images/videos using Wan 2.6 R2V Flash.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`, `reference_urls`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks.\n- `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details.\n- `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan 2.6 R2V Flash"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"model":{"type":"string","enum":["wan2.6-r2v-flash","wan2.6-r2v"],"default":"wan2.6-r2v-flash","description":"Model variant (flash=faster+cheaper, standard=higher quality audio-only)"},"name":{"type":"string","description":"Task name"},"reference_urls":{"type":"array","items":{"type":"string"},"description":"Array of reference image/video URLs (max 5)"},"prompt":{"type":"string","description":"Generation prompt (use character1, character2 to reference inputs)"},"duration":{"type":"string","enum":["2","3","4","5","6","7","8","9","10"],"default":"5","description":"Output duration in seconds. Any integer from 2 to 10, matching the upstream model."},"resolution":{"type":"string","enum":["720p","1080p"],"default":"720p","description":"Resolution tier, combined with aspect_ratio to determine actual size"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4"],"default":"16:9","description":"Aspect ratio for the output video"},"shot_type":{"type":"string","enum":["single","multi"],"default":"single"},"audio":{"type":"boolean","default":true},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt","reference_urls"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"high quality, clear, cinematic","reference_urls":["https://example.com/file"]}}}},"responses":{"200":{"description":"Task started successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan26R2VStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan26R2V/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"high quality, clear, cinematic\",\n  \"reference_urls\": [\n    \"https://example.com/file\"\n  ]\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userWan26R2V/allRecords":{"get":{"summary":"Get all R2V tasks","description":"Return the authenticated user's Wan 2.6 reference-to-video tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details.\n- `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task.\n- `POST /api/v1/userWan26R2V/start` — Start reference-to-video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan 2.6 R2V Flash"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"pageSize parameter"}],"operationId":"getApiV1UserWan26R2VAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan26R2V/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan26R2V/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks.\n- `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details.\n- `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan 2.6 R2V Flash"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan26R2VBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan26R2V/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userWan26R2V/{_id}":{"get":{"summary":"Get R2V task details","description":"Return the authenticated user's Wan 2.6 reference-to-video task identified by `_id`, including its current status and video output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks.\n- `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task.\n- `POST /api/v1/userWan26R2V/start` — Start reference-to-video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan 2.6 R2V Flash"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"getApiV1UserWan26R2VId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan26R2V/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete a R2V task","description":"Soft-delete the authenticated user's Wan 2.6 reference-to-video task identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks.\n- `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details.\n- `POST /api/v1/userWan26R2V/start` — Start reference-to-video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan 2.6 R2V Flash"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"deleteApiV1UserWan26R2VId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userWan26R2V/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWanSpicy/start":{"post":{"summary":"Start Wan Spicy image-to-video generation","description":"Start a Wan Spicy image-to-video task via mulerouter.ai/carrothub.\n- wan2.7-i2v-spicy: with audio support, resolution 720p/1080p, duration 2-15 seconds.\n- wan2.2-i2v-spicy: no audio, resolution 480p/720p, duration 5 or 8 seconds.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`, `image_url`, `resolution`, `duration`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks.\n- `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details.\n- `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"model":{"type":"string","enum":["wan2.7-i2v-spicy","wan2.2-i2v-spicy"],"default":"wan2.7-i2v-spicy","description":"Model variant (2.7 supports audio, 2.2 no audio)"},"name":{"type":"string","description":"Optional display name for the task"},"prompt":{"type":"string","description":"Generation prompt"},"negative_prompt":{"type":"string","description":"Negative prompt (only valid when model = wan2.7-i2v-spicy)"},"image_url":{"type":"string","description":"Reference image URL (https only)"},"audio_url":{"type":"string","description":"Audio URL (https, .wav/.mp3, only valid when model = wan2.7-i2v-spicy)"},"resolution":{"type":"string","enum":["480p","720p","1080p"],"description":"Resolution tier (wan2.7 720p/1080p, wan2.2 480p/720p)"},"duration":{"type":"number","description":"Output duration in seconds (wan2.7 2-15, wan2.2 5 or 8)"},"prompt_extend":{"type":"boolean","default":true},"seed":{"type":"integer","description":"Random seed"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Skip pre-charge minor-suspect prompt for the input image"}},"required":["prompt","image_url","resolution","duration"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"high quality, clear, cinematic","image_url":"https://example.com/image.jpg","resolution":"480p","duration":5}}}},"responses":{"200":{"description":"Task started successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWanSpicyStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWanSpicy/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"high quality, clear, cinematic\",\n  \"image_url\": \"https://example.com/image.jpg\",\n  \"resolution\": \"480p\",\n  \"duration\": 5\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userWanSpicy/allRecords":{"get":{"summary":"Get all Wan Spicy tasks","description":"Return the authenticated user's Wan Spicy image-to-video tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details.\n- `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task.\n- `POST /api/v1/userWanSpicy/start` — Start Wan Spicy image-to-video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"pageSize parameter"}],"operationId":"getApiV1UserWanSpicyAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWanSpicy/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWanSpicy/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks.\n- `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details.\n- `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWanSpicyBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWanSpicy/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userWanSpicy/{_id}":{"get":{"summary":"Get Wan Spicy task details","description":"Return the authenticated user's Wan Spicy image-to-video task identified by `_id`, including its current status and video output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks.\n- `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task.\n- `POST /api/v1/userWanSpicy/start` — Start Wan Spicy image-to-video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"getApiV1UserWanSpicyId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWanSpicy/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete a Wan Spicy task","description":"Soft-delete the authenticated user's Wan Spicy image-to-video task identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks.\n- `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details.\n- `POST /api/v1/userWanSpicy/start` — Start Wan Spicy image-to-video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan Image to Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"deleteApiV1UserWanSpicyId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userWanSpicy/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userHappyhorseVideo/start":{"post":{"summary":"Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)","description":"Generate a video using HappyHorse models on Alibaba DashScope. If model_version is omitted, new tasks keep the legacy 1.0 behavior.\nSupported modes:\n  - t2v: text → video (happyhorse-1.0-t2v / happyhorse-1.1-t2v)\n  - i2v: image first_frame → video (happyhorse-1.0-i2v / happyhorse-1.1-i2v)\n  - r2v: reference images → video (happyhorse-1.0-r2v / happyhorse-1.1-r2v)\n  - video-edit: video + reference images → edited video (happyhorse-1.0-video-edit)\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `mode`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks.\n- `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details.\n- `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["HappyHorse Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["t2v","i2v","r2v","video-edit"],"description":"Generation mode"},"name":{"type":"string","description":"Task name"},"model_version":{"type":"string","enum":["1.0","1.1"],"default":"1.0","description":"Model version for t2v / i2v / r2v. video-edit always uses 1.0. HappyHorse 1.1 additionally supports more aspect ratios and 480P/720P/1080P; duration is 3-15s for both versions."},"prompt":{"type":"string","description":"Required for t2v / r2v / video-edit; optional for i2v"},"image_url":{"type":"string","description":"First frame image URL (i2v only)"},"reference_image_urls":{"type":"array","items":{"type":"string"},"description":"Reference images (r2v requires 1-9; video-edit allows 0-5)"},"edit_video_url":{"type":"string","description":"Input video URL (video-edit only)"},"input_video_seconds":{"type":"number","description":"Frontend-detected input video duration in seconds (used to estimate coins for video-edit)"},"duration":{"type":"string","enum":["3","4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5","description":"Output duration (seconds). Integer 3-15 for both model versions. Ignored for video-edit (decided by input video)."},"resolution":{"type":"string","enum":["480P","720P","1080P"],"default":"720P","description":"Output resolution. 480P is only supported by HappyHorse 1.1 t2v / i2v / r2v; 1.0 and video-edit support 720P / 1080P."},"ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4","4:5","5:4","9:21","21:9"],"default":"16:9","description":"Aspect ratio (t2v / r2v only). model_version=1.0 supports 16:9, 9:16, 1:1, 4:3, 3:4; model_version=1.1 also supports 4:5, 5:4, 9:21, 21:9."},"audio_setting":{"type":"string","enum":["auto","origin"],"default":"auto","description":"Audio control (video-edit only). auto = model decides; origin = keep input video audio."},"seed":{"type":"integer","description":"Random seed [0, 2147483647]"},"watermark":{"type":"boolean","default":true,"description":"DashScope watermark switch"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["mode"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"mode":"t2v"}}}},"responses":{"200":{"description":"Task created successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserHappyhorseVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userHappyhorseVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"mode\": \"t2v\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userHappyhorseVideo/allRecords":{"get":{"summary":"List HappyHorse tasks","description":"Return the authenticated user's HappyHorse text-to-video, image-to-video, reference-to-video, and video-edit tasks using pagination.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details.\n- `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task.\n- `POST /api/v1/userHappyhorseVideo/start` — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["HappyHorse Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"pageSize parameter"}],"operationId":"getApiV1UserHappyhorseVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userHappyhorseVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userHappyhorseVideo/batchDetail":{"post":{"summary":"Batch query task details","description":"Return up to 200 authenticated-user HappyHorse video tasks matching the submitted `ids`; callers should match records by identifier.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks.\n- `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details.\n- `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["HappyHorse Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserHappyhorseVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userHappyhorseVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/userHappyhorseVideo/{_id}":{"get":{"summary":"Get HappyHorse task details","description":"Return the authenticated user's HappyHorse video task identified by `_id`, including its mode, current status, and video output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks.\n- `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task.\n- `POST /api/v1/userHappyhorseVideo/start` — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["HappyHorse Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"getApiV1UserHappyhorseVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userHappyhorseVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete a HappyHorse task","description":"Soft-delete the authenticated user's HappyHorse video task identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks.\n- `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details.\n- `POST /api/v1/userHappyhorseVideo/start` — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["HappyHorse Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"deleteApiV1UserHappyhorseVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userHappyhorseVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/talkingPhoto/start":{"post":{"summary":"Start talking photo generation","description":"Create an asynchronous talking-photo task from the submitted portrait image and audio or text input, then return the task record used to monitor video generation.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `image_url`, `prompt`, `negative_prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/talkingPhoto/allRecords` — Get all task records.\n- `GET /api/v1/talkingPhoto/{_id}` — Get task details.\n- `DELETE /api/v1/talkingPhoto/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Photo"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the talking photo task","example":"My Talking Photo"},"image_url":{"type":"string","description":"URL of the source image","example":"https://example.com/photo.jpg"},"audio_url":{"type":"string","description":"Optional audio URL","example":"https://example.com/audio.mp3"},"duration":{"type":"integer","description":"Duration in seconds","minimum":1,"maximum":20,"default":3,"example":5},"prompt":{"type":"string","description":"Generation prompt","example":"Make this person smile and speak"},"negative_prompt":{"type":"string","description":"Negative prompt to avoid unwanted features","example":"blurry, distorted"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["name","image_url","prompt","negative_prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Talking Photo","image_url":"https://example.com/photo.jpg","prompt":"Make this person smile and speak","negative_prompt":"blurry, distorted"}}}},"responses":{"200":{"description":"Talking photo task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"image_url":{"type":"string"},"current_status":{"type":"string"},"duration":{"type":"number"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","current_status":"processing","duration":5,"coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1TalkingPhotoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/talkingPhoto/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Talking Photo\",\n  \"image_url\": \"https://example.com/photo.jpg\",\n  \"prompt\": \"Make this person smile and speak\",\n  \"negative_prompt\": \"blurry, distorted\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/talkingPhoto/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's talking-photo tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/talkingPhoto/{_id}` — Get task details.\n- `DELETE /api/v1/talkingPhoto/{_id}` — Delete task.\n- `POST /api/v1/talkingPhoto/start` — Start talking photo generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Photo"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTalkingVideoTask"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"audio_result_url":"https://example.com/audio.mp3"}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1TalkingPhotoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/talkingPhoto/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/talkingPhoto/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/talkingPhoto/allRecords` — Get all task records.\n- `GET /api/v1/talkingPhoto/{_id}` — Get task details.\n- `DELETE /api/v1/talkingPhoto/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Photo"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTalkingVideoTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"audio_result_url":"https://example.com/audio.mp3"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1TalkingPhotoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/talkingPhoto/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/talkingPhoto/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's talking-photo task identified by `_id`, including its current processing status and available video output.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/talkingPhoto/allRecords` — Get all task records.\n- `DELETE /api/v1/talkingPhoto/{_id}` — Delete task.\n- `POST /api/v1/talkingPhoto/start` — Start talking photo generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Photo"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationTalkingVideoTask"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"audio_result_url":"https://example.com/audio.mp3"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1TalkingPhotoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/talkingPhoto/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's talking-photo task identified by `_id` from the task history without affecting other generated videos.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/talkingPhoto/allRecords` — Get all task records.\n- `GET /api/v1/talkingPhoto/{_id}` — Get task details.\n- `POST /api/v1/talkingPhoto/start` — Start talking photo generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Photo"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1TalkingPhotoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/talkingPhoto/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/talkingVideo/start":{"post":{"summary":"Start talking video generation","description":"Create an asynchronous talking-video task from a source video and audio. Billing uses the actual audio duration (up to 120 seconds), not the source video duration or the optional duration field. For an API quote, send input_audio_duration in generation/quote's requestBody.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `video_url`, `audio_url`, `prompt`, `negative_prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/talkingVideo/allRecords` — Get all task records.\n- `GET /api/v1/talkingVideo/{_id}` — Get task details.\n- `DELETE /api/v1/talkingVideo/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the talking video task","example":"My Talking Video"},"video_url":{"type":"string","description":"URL of the source video","example":"https://example.com/video.mp4"},"audio_url":{"type":"string","description":"Required source audio URL","example":"https://example.com/audio.mp3"},"duration":{"type":"integer","description":"Fallback duration when the server cannot read audio metadata; normally billing uses the duration of audio_url.","default":3,"example":5},"prompt":{"type":"string","description":"Generation prompt","example":"Make this person smile and speak"},"negative_prompt":{"type":"string","description":"Negative prompt to avoid unwanted features","example":"blurry, distorted"}},"required":["name","video_url","audio_url","prompt","negative_prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Talking Video","video_url":"https://example.com/video.mp4","audio_url":"https://example.com/audio.mp3","duration":5,"prompt":"Make this person smile and speak","negative_prompt":"blurry, distorted"}}}},"responses":{"200":{"description":"Talking video task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"video_url":{"type":"string"},"current_status":{"type":"string"},"duration":{"type":"number"},"coins":{"type":"number"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","video_url":"https://example.com/video.mp4","current_status":"processing","duration":5,"coins":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1TalkingVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/talkingVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Talking Video\",\n  \"video_url\": \"https://example.com/video.mp4\",\n  \"audio_url\": \"https://example.com/audio.mp3\",\n  \"duration\": 5,\n  \"prompt\": \"Make this person smile and speak\",\n  \"negative_prompt\": \"blurry, distorted\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/talkingVideo/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's talking-video tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/talkingVideo/{_id}` — Get task details.\n- `DELETE /api/v1/talkingVideo/{_id}` — Delete task.\n- `POST /api/v1/talkingVideo/start` — Start talking video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTalkingVideoTask"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"audio_result_url":"https://example.com/audio.mp3"}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1TalkingVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/talkingVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/talkingVideo/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/talkingVideo/allRecords` — Get all task records.\n- `GET /api/v1/talkingVideo/{_id}` — Get task details.\n- `DELETE /api/v1/talkingVideo/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationTalkingVideoTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"audio_result_url":"https://example.com/audio.mp3"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1TalkingVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/talkingVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/talkingVideo/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's talking-video task identified by `_id`, including its current processing status and available video output.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/talkingVideo/allRecords` — Get all task records.\n- `DELETE /api/v1/talkingVideo/{_id}` — Delete task.\n- `POST /api/v1/talkingVideo/start` — Start talking video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationTalkingVideoTask"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"audio_result_url":"https://example.com/audio.mp3"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1TalkingVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/talkingVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's talking-video task identified by `_id` from the task history without affecting other generated videos.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/talkingVideo/allRecords` — Get all task records.\n- `GET /api/v1/talkingVideo/{_id}` — Get task details.\n- `POST /api/v1/talkingVideo/start` — Start talking video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Talking Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1TalkingVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/talkingVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/virtualTryOn/start":{"post":{"summary":"Start virtual try-on task","description":"Start a virtual try-on task with clothing images on person photos.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `image_urls`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records.\n- `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail.\n- `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Virtual Try-On"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the virtual try-on task","default":"","example":"Summer Dress Try-On"},"image_urls":{"type":"array","minItems":2,"maxItems":4,"items":{"type":"string","format":"uri","pattern":"^https?://.*"},"description":"Array of 2 image URLs - [0] person image, [1] clothing image","example":["https://example.com/person.jpg","https://example.com/dress.jpg"]},"timeout":{"type":"number","default":120,"description":"Processing timeout in seconds","example":120},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["image_urls"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"Summer Dress Try-On","image_urls":["https://example.com/person.jpg","https://example.com/dress.jpg"],"timeout":120}}}},"responses":{"200":{"description":"Virtual try-on task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"image_urls":{"type":"array","items":{"type":"string"},"description":"Input image URLs"},"current_status":{"type":"string","description":"Current task status"},"coins":{"type":"number","description":"Coins required for the task"},"createdAt":{"type":"string","format":"date-time","description":"Task creation timestamp"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_urls":["https://example.com/image.jpg"],"current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1VirtualTryOnStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/virtualTryOn/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"Summer Dress Try-On\",\n  \"image_urls\": [\n    \"https://example.com/person.jpg\",\n    \"https://example.com/dress.jpg\"\n  ],\n  \"timeout\": 120\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/virtualTryOn/allRecords":{"get":{"summary":"Get all virtual try-on records","description":"Retrieve paginated list of virtual try-on tasks for the current user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail.\n- `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task.\n- `POST /api/v1/virtualTryOn/start` — Start virtual try-on task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Virtual Try-On"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Virtual try-on records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"image_urls":{"type":"array","items":{"type":"string"},"description":"Input image URLs"},"result_image_url":{"type":"string","description":"Result image URL"},"current_status":{"type":"string","description":"Current task status"},"coins":{"type":"number","description":"Coins required for the task"},"createdAt":{"type":"string","format":"date-time","description":"Task creation timestamp"}}}},"total":{"type":"integer","description":"Total number of records"},"pageNum":{"type":"integer","description":"Current page number"},"pageSize":{"type":"integer","description":"Number of items per page"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z"}],"total":1,"pageNum":1,"pageSize":10},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"Number of items per page"}],"operationId":"getApiV1VirtualTryOnAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/virtualTryOn/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/virtualTryOn/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records.\n- `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail.\n- `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Virtual Try-On"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVirtualTryOnTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5,"task_type":"image","result_image_url":"https://example.com/image.jpg"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1VirtualTryOnBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/virtualTryOn/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/virtualTryOn/{_id}":{"get":{"summary":"Get virtual try-on task detail","description":"Retrieve detailed information of a virtual try-on task by its ID.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records.\n- `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task.\n- `POST /api/v1/virtualTryOn/start` — Start virtual try-on task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Virtual Try-On"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Virtual try-on task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"image_urls":{"type":"array","items":{"type":"string"},"description":"Input image URLs"},"result_image_url":{"type":"string","description":"Result image URL"},"current_status":{"type":"string","description":"Current task status"},"coins":{"type":"number","description":"Coins required for the task"},"createdAt":{"type":"string","format":"date-time","description":"Task creation timestamp"},"failed_message":{"type":"string","description":"Error message if task failed"},"failed_code":{"type":"string","description":"Error code if task failed"},"version":{"type":"string","description":"Task version"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z","failed_message":"example","failed_code":"example","version":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Virtual try-on task ID"}],"operationId":"getApiV1VirtualTryOnId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/virtualTryOn/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete virtual try-on task","description":"Remove the authenticated user's virtual try-on task identified by `_id` from the task history without affecting other generated try-on results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records.\n- `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail.\n- `POST /api/v1/virtualTryOn/start` — Start virtual try-on task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Virtual Try-On"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Virtual try-on task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Deletion result"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Virtual try-on task ID"}],"operationId":"deleteApiV1VirtualTryOnId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/virtualTryOn/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/transactionRecord/creditsHistory":{"get":{"summary":"Get credits history","description":"Retrieve paginated credits transaction history for the authenticated user. Positive amounts are credit grants or purchases; negative amounts are credit consumption.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`, `is_consumption`, `startDate`, `endDate`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid query parameters.\n- `401` — Unauthorized - Invalid or missing token.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Credits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Credits history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"amount":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"transferTypeTranslation":{"type":"object"},"description":{"type":"string"},"metadata":{"type":"object"}}}},"count":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","amount":1,"createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","transferTypeTranslation":{},"description":"example","metadata":{}}],"count":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number, starting from 1."},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":10,"example":10},"description":"Number of records per page."},{"name":"is_consumption","in":"query","required":false,"schema":{"type":"boolean","example":false},"description":"When true, only returns consumption records; when false, only returns credit income records."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","example":"2026-01-01T00:00:00Z"},"description":"Inclusive ISO date-time lower bound for createdAt."},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","example":"2026-01-01T00:00:00Z"},"description":"Inclusive ISO date-time upper bound for createdAt."}],"operationId":"getApiV1TransactionRecordCreditsHistory","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/transactionRecord/creditsHistory\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/r2/upload-presigned-url":{"post":{"summary":"Get pre-signed upload URL","description":"Generate a pre-signed R2 PUT URL for direct browser/client upload.\nIf bucket is omitted, files are uploaded to 3days-apac by default.\nurlPrefix changes the leading object-key path and defaults to adam2eve outside site runtimes.\ncdnDomain changes the CDN domain suffix and defaults to the existing makefun.ai behavior outside site runtimes.\nSite runtimes reject urlPrefix and cdnDomain overrides to preserve isolated storage routing.\nThe returned key is scoped to {urlPrefix}/{env}/user/{user_id}/.\nUse cdnUrl as the public file URL after the PUT upload succeeds.\nAPI-token calls are charged per successfully issued presigned URL using the current `r2` entry from GET /api/v1/feature-pricing; this is not a per-byte upload charge. The balance is checked before URL generation and debited after the URL is created.\nThe subsequent client PUT is separate. A failed PUT does not automatically refund the presigning fee; requesting a replacement URL can incur another fee. Normal logged-in web/app calls are free.\nPUT upload contract (also applies to the legacy alias):\n- Only the A2E request for this URL uses Authorization: Bearer. Send the raw file bytes to uploadUrl with HTTP PUT; do not use JSON or multipart/form-data.\n- The uploadUrl query already authenticates the PUT. Use a separate unauthenticated HTTP client: do not forward Authorization or manually add x-amz-* headers.\n- Send Content-Type matching the requested contentType. Preserve the complete uploadUrl, including all query bytes and its R2 host; do not rewrite it to cdnUrl.\n- fileSize and contentLength are optional outside site runtimes. Omit them for a minimal upload; never copy a placeholder byte count.\n- If you provide a positive integer size, Content-Length must equal that actual file byte count. Outside site runtimes, contentLength takes priority over fileSize; site runtimes ignore contentLength and always bind the PUT to the validated fileSize. A chunked request without that bound Content-Length will fail.\n- Site runtimes can require fileSize; use the actual byte count there. expiresIn is URL validity, not object retention. Use cdnUrl only after PUT succeeds.\nTwo-step cURL example (requires curl and jq):\n```sh\ncurl -X POST \"https://headswap.app/api/v1/r2/upload-presigned-url\" \\\n  -H 'Authorization: Bearer YOUR_A2E_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"key\":\"upload.png\",\"purpose\":\"STAGING\",\"contentType\":\"image/png\",\"expiresIn\":300}' \\\n  --fail-with-body --output /tmp/a2e-upload-response.json\nupload_url=$(jq -er '.data.uploadUrl' /tmp/a2e-upload-response.json)\ncurl -X PUT \"$upload_url\" -H 'Content-Type: image/png' \\\n  --data-binary @upload.png --fail-with-body\n```\nReplace YOUR_A2E_API_KEY and upload.png with your own API key and file.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `key`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/r2/get_upload_presigned_url` — Get pre-signed upload URL.","tags":["Miscellaneous"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"key parameter","example":"example_key"},"bucket":{"type":"string","deprecated":true,"description":"R2 bucket. Defaults to 3days-apac. Deprecated, use purpose instead.","example":"3days-apac"},"purpose":{"type":"string","enum":["STAGING","RESULT_SHORT","RESULT","SHORT_CACHE"],"description":"Storage purpose. The backend maps it to the physical bucket. Ignored when bucket is provided.","example":"STAGING"},"urlPrefix":{"type":"string","description":"Leading object-key path outside site runtimes. Site runtimes reject this override.","example":"adam2eve"},"cdnDomain":{"type":"string","description":"CDN domain suffix outside site runtimes. Site runtimes reject this override.","example":"makefun.ai"},"expiresIn":{"type":"integer","minimum":60,"maximum":600,"default":300,"description":"Upload URL validity in seconds","example":60},"contentType":{"type":"string","description":"MIME type to bind to the upload request.","example":"image/png"},"fileSize":{"type":"number","description":"Optional actual file size in bytes. A positive safe integer binds Content-Length; the PUT must send exactly this many raw bytes.","example":1},"contentLength":{"type":"number","description":"Optional actual Content-Length in bytes. A positive safe integer binds the PUT length; takes priority over fileSize outside site runtimes. Site runtimes ignore it and sign with fileSize.","example":1}},"required":["key"],"example":{"key":"example_key"}},"example":{"key":"upload.png","purpose":"STAGING","expiresIn":60,"contentType":"image/png"}}}},"responses":{"200":{"description":"Operation completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/R2UploadPresignedUrlResponse"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1R2UploadPresignedUrl","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/r2/upload-presigned-url\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"key\": \"upload.png\",\n  \"purpose\": \"STAGING\",\n  \"expiresIn\": 60,\n  \"contentType\": \"image/png\"\n}'"}]}},"/api/v1/thinkSound/start":{"post":{"summary":"Start ThinkSound generation","description":"Generate audio-visual content from video using AI with customizable parameters.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `video_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters or video format.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records.\n- `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task.\n- `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["ThinkSound"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the ThinkSound task","example":"My Audio-Visual Generation"},"video_url":{"type":"string","description":"URL of the source video (must be .mp4, .avi, .mov, or .mkv)","example":"https://example.com/video.mp4"},"caption":{"type":"string","description":"Caption for the generation","default":"","example":"Generate audio for this silent video"},"cot_description":{"type":"string","description":"Chain of thought description","default":"","example":"Detailed description of the audio generation process"},"seed":{"type":"number","description":"Random seed for reproducible results","example":12345}},"required":["video_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"video_url":"https://example.com/video.mp4"}}}},"responses":{"200":{"description":"ThinkSound generation started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string"},"video_url":{"type":"string"},"current_status":{"type":"string"},"coins":{"type":"number"},"reference_id":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","video_url":"https://example.com/video.mp4","current_status":"processing","coins":1,"reference_id":"507f1f77bcf86cd799439011"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters or video format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ThinkSoundStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/thinkSound/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"video_url\": \"https://example.com/video.mp4\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/thinkSound/{_id}":{"delete":{"summary":"Delete ThinkSound task","description":"Remove the authenticated user's ThinkSound generation task identified by `_id` from the task history without affecting other generated-audio records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records.\n- `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details.\n- `POST /api/v1/thinkSound/start` — Start ThinkSound generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["ThinkSound"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ThinkSound task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Deletion result"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the ThinkSound task to delete"}],"operationId":"deleteApiV1ThinkSoundId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/thinkSound/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"get":{"summary":"Get ThinkSound task details","description":"Retrieve detailed information about a specific ThinkSound generation task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID format.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records.\n- `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task.\n- `POST /api/v1/thinkSound/start` — Start ThinkSound generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["ThinkSound"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ThinkSound task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"video_url":{"type":"string","description":"Original video URL"},"caption":{"type":"string","description":"Task caption"},"cot_description":{"type":"string","description":"Chain of thought description"},"seed":{"type":"number","description":"Random seed used"},"current_status":{"type":"string","description":"Current processing status"},"result_url":{"type":"string","description":"Generated result URL"},"coins":{"type":"number","description":"Cost in coins"},"reference_id":{"type":"string","description":"External reference ID"},"createdAt":{"type":"string","format":"date-time"},"failed_message":{"type":"string","description":"Failure message if error occurred"},"failed_code":{"type":"string","description":"Failure code if error occurred"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","video_url":"https://example.com/video.mp4","caption":"example","cot_description":"example","seed":1,"current_status":"processing","result_url":"https://example.com/file","coins":1,"reference_id":"507f1f77bcf86cd799439011","createdAt":"2026-01-01T00:00:00Z","failed_message":"example","failed_code":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"ID of the ThinkSound task"}],"operationId":"getApiV1ThinkSoundId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/thinkSound/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/thinkSound/allRecords":{"get":{"summary":"Get all ThinkSound records","description":"Retrieve paginated list of ThinkSound generation tasks for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid pagination parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task.\n- `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details.\n- `POST /api/v1/thinkSound/start` — Start ThinkSound generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["ThinkSound"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ThinkSound records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"video_url":{"type":"string"},"current_status":{"type":"string"},"result_url":{"type":"string"},"coins":{"type":"number"},"createdAt":{"type":"string","format":"date-time"}}}},"total":{"type":"integer","description":"Total number of records"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","video_url":"https://example.com/video.mp4","current_status":"processing","result_url":"https://example.com/file","coins":1,"createdAt":"2026-01-01T00:00:00Z"}],"total":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number (starts from 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"Number of records per page"}],"operationId":"getApiV1ThinkSoundAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/thinkSound/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/thinkSound/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records.\n- `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task.\n- `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["ThinkSound"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationAudioTaskThinkSound"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","audio_url":"https://example.com/audio.mp3","result_url":"https://example.com/file"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ThinkSoundBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/thinkSound/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/seedAudio/speakers":{"get":{"summary":"List Seed Audio speakers","description":"Returns the preset Seed TTS 2.0 speakers that can be used as a `speaker` reference. The list is cached server-side for 10 minutes. Anonymous access is allowed on the standard runtime; the Cheap boundary requires a bearer token.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Reads the requested information without creating a generation task.\n- Use the returned fields as documented; availability may depend on the caller and current resource state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - A bearer token was supplied but is invalid, or the Cheap boundary received no token.\n- `503` — Speaker list credentials are not configured or the provider is temporarily unavailable.\n### Related Operations\n- `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records.\n- `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail.\n- `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{},{"bearerAuth":[]}],"responses":{"200":{"description":"Speaker list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioSpeakerListResponse"}}}},"401":{"description":"Unauthorized - A bearer token was supplied but is invalid, or the Cheap boundary received no token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Speaker list credentials are not configured or the provider is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1SeedAudioSpeakers","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedAudio/speakers\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/seedAudio/start":{"post":{"summary":"Start an asynchronous Seed Audio task","description":"Same request contract and billing rules as `/api/v1/seedAudio/generate`. Advance quotes through `/api/v1/generation/quote` are not supported; obtain the user's acceptance of the reservation and actual-duration settlement rules before submitting generation directly. The task is queued immediately; poll `GET /api/v1/seedAudio/{_id}` until `current_status` becomes `completed` or `failed`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `text_prompt`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Too many unfinished Seed Audio tasks for the current user.\n### Related Operations\n- `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records.\n- `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail.\n- `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["text_prompt"],"properties":{"text_prompt":{"type":"string","maxLength":3000,"example":"high quality, clear, cinematic"},"references":{"type":"array","description":"Use either one image reference, or up to three audio references in total, where `audio_url` and `speaker` entries may be combined. Image references cannot be mixed with audio or speaker references.","anyOf":[{"maxItems":1,"items":{"type":"object","additionalProperties":false,"required":["image_url"],"properties":{"image_url":{"type":"string"}}}},{"maxItems":3,"items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["audio_url"],"properties":{"audio_url":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["speaker"],"properties":{"speaker":{"type":"string"}}}]}}],"example":[{"image_url":"https://example.com/image.jpg"}]},"display_text":{"type":"string","maxLength":2100,"example":"example"},"performance_direction":{"type":"string","maxLength":800,"example":"example"},"audio_config":{"type":"object","properties":{"speech_rate":{"type":"integer","minimum":-50,"maximum":100,"example":-50},"loudness_rate":{"type":"integer","minimum":-50,"maximum":100,"example":-50},"pitch_rate":{"type":"integer","minimum":-12,"maximum":12,"example":-12}},"example":{}}},"example":{"text_prompt":"high quality, clear, cinematic"}},"examples":{"no_reference":{"summary":"Start without a reference","value":{"text_prompt":"Gentle rain in a quiet forest","references":[]}},"image_reference":{"summary":"Start from one image","value":{"text_prompt":"Birdsong in this forest","references":[{"image_url":"https://example.com/forest.png"}]}},"audio_references":{"summary":"Start with audio and speaker references","value":{"text_prompt":"A calm narration","references":[{"audio_url":"https://example.com/reference.wav"},{"speaker":"speaker-id"}]}}}}}},"responses":{"200":{"description":"Task accepted and queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioTaskResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many unfinished Seed Audio tasks for the current user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1SeedAudioStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedAudio/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"text_prompt\": \"Gentle rain in a quiet forest\",\n  \"references\": []\n}'"}]}},"/api/v1/seedAudio/generate":{"post":{"summary":"Generate custom audio with Seed Audio","description":"Queues a Seed Audio task. Advance quotes through `/api/v1/generation/quote` are not supported because the actual output duration is unknown before generation. Do not request or retry an advance quote; explain the reservation and settlement rules and obtain the user's acceptance before submitting this request. The current runtime unit price and the 120-credit reservation are snapshotted when the task is submitted. The reservation is not the final price. After success, billing is recalculated from the original output duration rounded up; unused credits are refunded and any additional charge is limited to the user's remaining balance. Failed tasks receive a full refund.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `text_prompt`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Too many unfinished Seed Audio tasks for the current user.\n### Related Operations\n- `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records.\n- `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail.\n- `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["text_prompt"],"properties":{"text_prompt":{"type":"string","maxLength":3000,"example":"high quality, clear, cinematic"},"references":{"type":"array","description":"Use either one image reference, or up to three audio references in total, where `audio_url` and `speaker` entries may be combined. Image references cannot be mixed with audio or speaker references.","anyOf":[{"maxItems":1,"items":{"type":"object","additionalProperties":false,"required":["image_url"],"properties":{"image_url":{"type":"string"}}}},{"maxItems":3,"items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["audio_url"],"properties":{"audio_url":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["speaker"],"properties":{"speaker":{"type":"string"}}}]}}],"example":[{"image_url":"https://example.com/image.jpg"}]},"display_text":{"type":"string","maxLength":2100,"example":"example"},"performance_direction":{"type":"string","maxLength":800,"example":"example"},"audio_config":{"type":"object","properties":{"speech_rate":{"type":"integer","minimum":-50,"maximum":100,"example":-50},"loudness_rate":{"type":"integer","minimum":-50,"maximum":100,"example":-50},"pitch_rate":{"type":"integer","minimum":-12,"maximum":12,"example":-12}},"example":{}}},"example":{"text_prompt":"high quality, clear, cinematic"}},"examples":{"no_reference":{"summary":"Generate without a reference","value":{"text_prompt":"Gentle rain in a quiet forest","references":[]}},"image_reference":{"summary":"Generate from one image","value":{"text_prompt":"Birdsong in this forest","references":[{"image_url":"https://example.com/forest.png"}]}},"audio_references":{"summary":"Generate with audio and speaker references","value":{"text_prompt":"A calm narration","references":[{"audio_url":"https://example.com/reference.wav"},{"speaker":"speaker-id"}]}}}}}},"responses":{"200":{"description":"Task accepted and queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioTaskResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many unfinished Seed Audio tasks for the current user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1SeedAudioGenerate","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedAudio/generate\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"text_prompt\": \"Gentle rain in a quiet forest\",\n  \"references\": []\n}'"}]}},"/api/v1/seedAudio/allRecords":{"get":{"summary":"Get all Seed Audio records","description":"Retrieve the paginated Seed Audio task history of the current user, newest first.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail.\n- `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task.\n- `GET /api/v1/seedAudio/speakers` — List Seed Audio speakers.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Seed Audio records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioTaskListResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"example":20},"description":"Number of items per page"}],"operationId":"getApiV1SeedAudioAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedAudio/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/seedAudio/batchDetail":{"post":{"summary":"Batch query Seed Audio task details","description":"Query up to 200 tasks of the current user at once by task ID. Unknown or foreign IDs are silently omitted.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records.\n- `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail.\n- `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","maxItems":200,"items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioTaskArrayResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1SeedAudioBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedAudio/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/seedAudio/{_id}":{"get":{"summary":"Get Seed Audio task detail","description":"Poll a Seed Audio task by its ID. `result_url` is populated once `current_status` is `completed`; `failed_code` and `failed_message` explain a `failed` task, which is fully refunded.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Seed Audio record not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records.\n- `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task.\n- `GET /api/v1/seedAudio/speakers` — List Seed Audio speakers.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Seed Audio task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioTaskResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Seed Audio record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Seed Audio task ID"}],"operationId":"getApiV1SeedAudioId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedAudio/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete Seed Audio task","description":"Remove the authenticated user's Seed Audio task from the history. A queued (`initialized`) task is canceled and refunded first; a `processing` task cannot be deleted until it finishes.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — The task is still processing and cannot be deleted yet.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Seed Audio record not found.\n### Related Operations\n- `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records.\n- `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail.\n- `GET /api/v1/seedAudio/speakers` — List Seed Audio speakers.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["TTS and Voice Clone"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Seed Audio task deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedAudioTaskResponse"}}}},"400":{"description":"The task is still processing and cannot be deleted yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Seed Audio record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Seed Audio task ID"}],"operationId":"deleteApiV1SeedAudioId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/seedAudio/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/motionTransfer/start":{"post":{"summary":"Start motion transfer task","description":"Start a motion transfer task to transfer motion from video to image.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `image_url`, `video_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records.\n- `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail.\n- `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Motion Transfer"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the motion transfer task","default":"","example":"Dance Motion Transfer"},"image_url":{"type":"string","format":"uri","pattern":"^https?://.*","description":"Reference image URL for motion transfer","example":"https://example.com/person.jpg"},"video_url":{"type":"string","format":"uri","pattern":"^https?://.*","description":"Control video URL for motion source","example":"https://example.com/dance.mp4"},"positive_prompt":{"type":"string","description":"Positive prompt for motion transfer","example":"high quality motion transfer, natural pose transition, smooth movement"},"negative_prompt":{"type":"string","description":"Negative prompt for motion transfer","example":"blurry, distorted limbs, unnatural poses, deformation"},"timeout":{"type":"number","default":300,"description":"Processing timeout in seconds","example":300},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["image_url","video_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"image_url":"https://example.com/person.jpg","video_url":"https://example.com/dance.mp4"}}}},"responses":{"200":{"description":"Motion transfer task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"image_url":{"type":"string","description":"Reference image URL"},"video_url":{"type":"string","description":"Control video URL"},"positive_prompt":{"type":"string","description":"Positive prompt used"},"negative_prompt":{"type":"string","description":"Negative prompt used"},"current_status":{"type":"string","description":"Current task status"},"coins":{"type":"number","description":"Coins required for the task"},"createdAt":{"type":"string","format":"date-time","description":"Task creation timestamp"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","positive_prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted","current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1MotionTransferStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/motionTransfer/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"image_url\": \"https://example.com/person.jpg\",\n  \"video_url\": \"https://example.com/dance.mp4\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/motionTransfer/allRecords":{"get":{"summary":"Get all motion transfer records","description":"Retrieve paginated list of motion transfer tasks for the current user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail.\n- `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task.\n- `POST /api/v1/motionTransfer/start` — Start motion transfer task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Motion Transfer"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Motion transfer records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"image_url":{"type":"string","description":"Reference image URL"},"video_url":{"type":"string","description":"Control video URL"},"result_video_url":{"type":"string","description":"Result video URL"},"positive_prompt":{"type":"string","description":"Positive prompt used"},"negative_prompt":{"type":"string","description":"Negative prompt used"},"current_status":{"type":"string","description":"Current task status"},"coins":{"type":"number","description":"Coins required for the task"},"createdAt":{"type":"string","format":"date-time","description":"Task creation timestamp"}}}},"total":{"type":"integer","description":"Total number of records"},"pageNum":{"type":"integer","description":"Current page number"},"pageSize":{"type":"integer","description":"Number of items per page"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","positive_prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted","current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z"}],"total":1,"pageNum":1,"pageSize":10},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"Number of items per page"}],"operationId":"getApiV1MotionTransferAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/motionTransfer/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/motionTransfer/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records.\n- `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail.\n- `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Motion Transfer"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1MotionTransferBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/motionTransfer/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/motionTransfer/{_id}":{"get":{"summary":"Get motion transfer task detail","description":"Retrieve detailed information of a motion transfer task by its ID.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records.\n- `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task.\n- `POST /api/v1/motionTransfer/start` — Start motion transfer task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Motion Transfer"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Motion transfer task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID"},"name":{"type":"string","description":"Task name"},"image_url":{"type":"string","description":"Reference image URL"},"video_url":{"type":"string","description":"Control video URL"},"result_video_url":{"type":"string","description":"Result video URL"},"positive_prompt":{"type":"string","description":"Positive prompt used"},"negative_prompt":{"type":"string","description":"Negative prompt used"},"current_status":{"type":"string","description":"Current task status"},"coins":{"type":"number","description":"Coins required for the task"},"createdAt":{"type":"string","format":"date-time","description":"Task creation timestamp"},"failed_message":{"type":"string","description":"Error message if task failed"},"failed_code":{"type":"string","description":"Error code if task failed"},"version":{"type":"string","description":"Task version"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","positive_prompt":"high quality, clear, cinematic","negative_prompt":"blurry, low quality, watermark, distorted","current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z","failed_message":"example","failed_code":"example","version":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Motion transfer task ID"}],"operationId":"getApiV1MotionTransferId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/motionTransfer/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete motion transfer task","description":"Remove the authenticated user's motion-transfer task identified by `_id` from the task history without affecting other generated videos.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records.\n- `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail.\n- `POST /api/v1/motionTransfer/start` — Start motion transfer task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Motion Transfer"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Motion transfer task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Deletion result"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Motion transfer task ID"}],"operationId":"deleteApiV1MotionTransferId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/motionTransfer/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/actorSwap/start":{"post":{"summary":"Start actor swap task","description":"Generate actor swap video by swapping actor from image to video.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `image_url`, `video_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/actorSwap/allRecords` — Get all task records.\n- `GET /api/v1/actorSwap/{_id}` — Get task details.\n- `DELETE /api/v1/actorSwap/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Actor Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the actor swap task","example":"My Actor Swap"},"image_url":{"type":"string","description":"URL of the reference actor image","format":"uri","example":"https://example.com/actor.jpg"},"video_url":{"type":"string","description":"URL of the control video","format":"uri","example":"https://example.com/video.mp4"},"prompt":{"type":"string","description":"Positive prompt for generation","example":"high quality, realistic"},"negative_prompt":{"type":"string","description":"Negative prompt to avoid unwanted features","example":"blurry, distorted"},"timeout":{"type":"integer","description":"Timeout in seconds","default":300,"example":300},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["image_url","video_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Actor Swap","image_url":"https://example.com/actor.jpg","video_url":"https://example.com/video.mp4","prompt":"high quality, realistic","negative_prompt":"blurry, distorted","timeout":300}}}},"responses":{"200":{"description":"Actor swap task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"image_url":{"type":"string"},"video_url":{"type":"string"},"current_status":{"type":"string"},"coins":{"type":"number"},"createdAt":{"type":"string","format":"date-time"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","image_url":"https://example.com/image.jpg","video_url":"https://example.com/video.mp4","current_status":"processing","coins":1,"createdAt":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ActorSwapStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/actorSwap/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Actor Swap\",\n  \"image_url\": \"https://example.com/actor.jpg\",\n  \"video_url\": \"https://example.com/video.mp4\",\n  \"prompt\": \"high quality, realistic\",\n  \"negative_prompt\": \"blurry, distorted\",\n  \"timeout\": 300\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/actorSwap/allRecords":{"get":{"summary":"Get all task records","description":"Return the authenticated user's actor-swap tasks, newest first, using the requested page number and page size.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/actorSwap/{_id}` — Get task details.\n- `DELETE /api/v1/actorSwap/{_id}` — Delete task.\n- `POST /api/v1/actorSwap/start` — Start actor swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Actor Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","example":10},"description":"Page size"}],"operationId":"getApiV1ActorSwapAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/actorSwap/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/actorSwap/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/actorSwap/allRecords` — Get all task records.\n- `GET /api/v1/actorSwap/{_id}` — Get task details.\n- `DELETE /api/v1/actorSwap/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Actor Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ActorSwapBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/actorSwap/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/actorSwap/{_id}":{"get":{"summary":"Get task details","description":"Return the authenticated user's actor-swap task identified by `_id`, including its current processing status and available video output.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/actorSwap/allRecords` — Get all task records.\n- `DELETE /api/v1/actorSwap/{_id}` — Delete task.\n- `POST /api/v1/actorSwap/start` — Start actor swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Actor Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1ActorSwapId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/actorSwap/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's actor-swap task identified by `_id` from the task history without affecting other generated videos.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/actorSwap/allRecords` — Get all task records.\n- `GET /api/v1/actorSwap/{_id}` — Get task details.\n- `POST /api/v1/actorSwap/start` — Start actor swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Actor Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1ActorSwapId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/actorSwap/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/productAvatar/start":{"post":{"summary":"Generate product avatar with AI (Async)","description":"Generate a product image by combining product and person images with customizable positioning and styling. This endpoint returns an image, not a video.\n**⚠️ IMPORTANT: This is an ASYNCHRONOUS operation**\n### Async Workflow\n1. **Submit Task** - Call this endpoint to create a new generation task\n   - Returns immediately with task `_id` and status `initialized`\n   - Task is queued for processing\n2. **Processing States** - The task goes through these states:\n   - `initialized` → Task created, waiting in queue\n   - `sent` → Task submitted to AI service\n   - `pending` → Task received by AI service\n   - `processing` → AI is generating the image\n   - `completed` → Generation finished successfully\n   - `failed` → Generation failed (check `failed_message`)\n3. **Get Results** - Poll for task status and results:\n   - Use `GET /api/v1/productAvatar/{_id}` to check status\n   - Use `GET /api/v1/productAvatar/allRecords` to list all tasks\n   - When `current_status` is `completed`, `result_image_url` contains the generated image\n4. **Timeout Handling**:\n   - Tasks timeout after 2 hours and automatically fail\n   - Credits are automatically refunded on timeout or failure\n### Best Practices\n- Poll every 3-5 seconds to check task status\n- Handle both `completed` and `failed` states\n- Store the returned `_id` to query results later.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `image_urls`, `product_rect`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters or missing required fields.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks.\n- `GET /api/v1/productAvatar/{_id}` — Query task status and get result.\n- `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Product Avatar"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name for the product avatar generation task (optional)","example":"My Product Avatar"},"image_urls":{"type":"array","description":"Array of image URLs - [0] product image, [1] person image","minItems":2,"maxItems":2,"items":{"type":"string","format":"uri","pattern":"^https?://.+","description":"Image URL (must be HTTP/HTTPS)"},"example":["https://example.com/product.jpg","https://example.com/person.jpg"]},"product_rect":{"type":"object","description":"Product placement on image_urls[1]. Coordinates use that person's original image pixel dimensions, with (0, 0) at the top-left. x and y identify the unrotated product box's top-left; the workflow uses x, y, rotation, and scale. Width and height remain required but currently do not change the generated output.","required":["x","y","width","height","rotation","scale"],"properties":{"x":{"type":"number","description":"Left edge of the unrotated product box, in pixels from the left of the original image_urls[1] image.","example":100},"y":{"type":"number","description":"Top edge of the unrotated product box, in pixels from the top of the original image_urls[1] image.","example":150},"width":{"type":"number","description":"Product box width in person-image pixels, normally original product-image width multiplied by scale; required but currently ignored by the generation workflow.","example":200},"height":{"type":"number","description":"Product box height in person-image pixels, normally original product-image height multiplied by scale; required but currently ignored by the generation workflow.","example":300},"rotation":{"type":"number","description":"Rotation angle in degrees","example":0},"scale":{"type":"number","description":"Multiplier applied to the original product image dimensions before placement.","example":1}}},"prompt":{"type":"string","description":"Additional prompt for AI generation (optional)","example":"Professional product showcase"},"timeout":{"type":"number","description":"Processing timeout in seconds","default":120,"example":120},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["image_urls","product_rect"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"name":"My Product Avatar","image_urls":["https://example.com/product.jpg","https://example.com/person.jpg"],"product_rect":{"x":100,"y":150,"width":200,"height":300,"rotation":0,"scale":1},"prompt":"Professional product showcase","timeout":120}}}},"responses":{"200":{"description":"Product avatar generation started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Product avatar generation result","properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Task name","example":"My Product Avatar"},"current_status":{"type":"string","description":"Current processing status. Possible values - initialized, sent, pending, processing, completed, failed","enum":["initialized","sent","pending","processing","completed","failed"],"example":"initialized"},"coins":{"type":"number","description":"Cost in credits","example":10}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Product Avatar","current_status":"initialized","coins":10},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ProductAvatarStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/productAvatar/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Product Avatar\",\n  \"image_urls\": [\n    \"https://example.com/product.jpg\",\n    \"https://example.com/person.jpg\"\n  ],\n  \"product_rect\": {\n    \"x\": 100,\n    \"y\": 150,\n    \"width\": 200,\n    \"height\": 300,\n    \"rotation\": 0,\n    \"scale\": 1\n  },\n  \"prompt\": \"Professional product showcase\",\n  \"timeout\": 120\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/productAvatar/allRecords":{"get":{"summary":"List all product avatar tasks","description":"Retrieve a paginated list of all product avatar generation tasks for the authenticated user.\nUse this endpoint to monitor task progress and retrieve results.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/productAvatar/{_id}` — Query task status and get result.\n- `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task.\n- `POST /api/v1/productAvatar/start` — Generate product avatar with AI (Async)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Product Avatar"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved task list. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","example":"My Product Avatar"},"image_urls":{"type":"array","items":{"type":"string"},"example":["https://example.com/product.jpg","https://example.com/person.jpg"]},"result_image_url":{"type":"string","example":"https://example.com/result.jpg"},"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed"],"example":"completed"},"coins":{"type":"number","example":10},"createdAt":{"type":"string","format":"date-time"},"failed_message":{"type":"string","example":""},"failed_code":{"type":"string","example":""}}}},"total":{"type":"integer","example":25},"pageNum":{"type":"integer","example":1},"pageSize":{"type":"integer","example":10}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Product Avatar","image_urls":["https://example.com/product.jpg","https://example.com/person.jpg"],"result_image_url":"https://example.com/result.jpg","current_status":"completed","coins":10,"createdAt":"2026-01-01T00:00:00Z","failed_message":"","failed_code":""}],"total":25,"pageNum":1,"pageSize":10},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number (starting from 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"Number of items per page"}],"operationId":"getApiV1ProductAvatarAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/productAvatar/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/productAvatar/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks.\n- `GET /api/v1/productAvatar/{_id}` — Query task status and get result.\n- `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Product Avatar"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationImageTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","creation_mode":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_image_url":"https://example.com/image.jpg","result_image_urls":["https://example.com/image.jpg"],"input_images":["example"]}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1ProductAvatarBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/productAvatar/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/productAvatar/{_id}":{"get":{"summary":"Query task status and get result","description":"Retrieve detailed information about a specific product avatar generation task.\nUse this endpoint to poll for task status and get the result when completed.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks.\n- `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task.\n- `POST /api/v1/productAvatar/start` — Generate product avatar with AI (Async)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Product Avatar"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","example":"My Product Avatar"},"image_urls":{"type":"array","items":{"type":"string"},"example":["https://example.com/product.jpg","https://example.com/person.jpg"]},"result_image_url":{"type":"string","description":"Generated image URL (available when status is completed)","example":"https://example.com/result.jpg"},"current_status":{"type":"string","description":"Current task status","enum":["initialized","sent","pending","processing","completed","failed"],"example":"completed"},"coins":{"type":"number","example":10},"createdAt":{"type":"string","format":"date-time"},"failed_message":{"type":"string","description":"Error message if status is failed","example":""},"failed_code":{"type":"string","description":"Error code if status is failed","example":""},"hasRefundCoin":{"type":"boolean","description":"Whether credits have been refunded","example":false},"prompt":{"type":"string","description":"The prompt used for generation","example":"Professional product showcase"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Product Avatar","image_urls":["https://example.com/product.jpg","https://example.com/person.jpg"],"result_image_url":"https://example.com/result.jpg","current_status":"completed","coins":10,"createdAt":"2026-01-01T00:00:00Z","failed_message":"","failed_code":"","hasRefundCoin":false,"prompt":"Professional product showcase"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID returned from the start endpoint"}],"operationId":"getApiV1ProductAvatarId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/productAvatar/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete a product avatar task","description":"Soft delete a product avatar task. The task data will be marked as deleted but not removed from the database.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid task ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks.\n- `GET /api/v1/productAvatar/{_id}` — Query task status and get result.\n- `POST /api/v1/productAvatar/start` — Generate product avatar with AI (Async)\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Product Avatar"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","example":{}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid task ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID to delete"}],"operationId":"deleteApiV1ProductAvatarId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/productAvatar/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/headSwap/start":{"post":{"summary":"Start head swap generation","description":"Generate a head swap result by replacing the head in a target image/video with a source head.\n**Supported modes:**\n- **Image to Image**: Provide an image as `target_image_url` to get a head-swapped image\n- **Image to Video**: Provide a video as `target_image_url` to get a head-swapped video (max 15 seconds)\n**Content moderation:**\n- CSAM detection is performed on input images\n- If confirmed CSAM intent is detected together with age < 10, the request will be rejected with code 1003\n- If suspected CSAM is detected, set `minor_suspected_skip: true` to proceed\n- Head swap sends no user prompt to the detector, so a low apparent age alone does not trigger 1003\n**Async workflow:**\n1. Task is created with status `initialized`\n2. Task is queued and sent to algorithm service (status: `sent`)\n3. Algorithm processes the task (status: `processing`)\n4. Result is ready (status: `completed`) or failed (status: `failed`)\n5. Use `/api/v1/headSwap/{_id}` to poll for status updates.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `image_url`, `target_image_url`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid request parameters or insufficient coins.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `403` — Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor)\n### Related Operations\n- `GET /api/v1/headSwap/allRecords` — Get all head swap records.\n- `GET /api/v1/headSwap/{_id}` — Get head swap task detail.\n- `DELETE /api/v1/headSwap/{_id}` — Delete head swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Head Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"image_url":{"type":"string","description":"URL of the source head image (the head to be transplanted)","format":"uri","example":"https://example.com/head.jpg"},"target_image_url":{"type":"string","description":"URL of the target body image or video (where the head will be placed)","format":"uri","example":"https://example.com/body.jpg"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Skip the suspected CSAM warning. Use with caution.","example":false}},"required":["image_url","target_image_url"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"image_url":"https://example.com/head.jpg","target_image_url":"https://example.com/body.jpg"}}}},"responses":{"200":{"description":"Head swap task started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID for polling status","example":"507f1f77bcf86cd799439011"},"image_url":{"type":"string","description":"Source head image URL","example":"https://example.com/head.jpg"},"target_image_url":{"type":"string","description":"Target body image/video URL","example":"https://example.com/body.jpg"},"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed"],"description":"Current task status","example":"initialized"},"coins":{"type":"number","description":"Coins consumed for this task","example":5},"createdAt":{"type":"string","format":"date-time","description":"Task creation time","example":"2025-01-15T10:30:00.000Z"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/head.jpg","target_image_url":"https://example.com/body.jpg","current_status":"initialized","coins":5,"createdAt":"2025-01-15T10:30:00.000Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid request parameters or insufficient coins"},"401":{"description":"Unauthorized - Invalid or missing bearer token"},"403":{"description":"Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor)"}},"operationId":"postApiV1HeadSwapStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/headSwap/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"image_url\": \"https://example.com/head.jpg\",\n  \"target_image_url\": \"https://example.com/body.jpg\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/headSwap/allRecords":{"get":{"summary":"Get all head swap records","description":"Get a paginated list of the current user's head swap tasks.\nResults are sorted by creation time (newest first) and filtered by expiration.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/headSwap/{_id}` — Get head swap task detail.\n- `DELETE /api/v1/headSwap/{_id}` — Delete head swap task.\n- `POST /api/v1/headSwap/start` — Start head swap generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Head Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Head swap records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"image_url":{"type":"string","description":"Source head image URL","example":"https://example.com/head.jpg"},"target_image_url":{"type":"string","description":"Target body image URL","example":"https://example.com/body.jpg"},"result_url":{"type":"string","description":"Result image/video URL (available when completed)","example":"https://example.com/result.jpg"},"cover_url":{"type":"string","description":"Cover image URL for video results","example":"https://example.com/cover.jpg"},"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked"],"description":"Current task status","example":"completed"},"coins":{"type":"number","description":"Coins consumed for this task","example":5},"createdAt":{"type":"string","format":"date-time","description":"Task creation time","example":"2025-01-15T10:30:00.000Z"},"failed_message":{"type":"string","description":"Error message if task failed"},"failed_code":{"type":"number","description":"Error code if task failed"},"remainingDays":{"type":"number","description":"Days until result expires","example":27},"isExpiringSoon":{"type":"boolean","description":"Whether result is expiring soon (< 3 days)","example":false}}}},"total":{"type":"number","description":"Total number of records","example":25}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/head.jpg","target_image_url":"https://example.com/body.jpg","result_url":"https://example.com/result.jpg","cover_url":"https://example.com/cover.jpg","current_status":"completed","coins":5,"createdAt":"2025-01-15T10:30:00.000Z","failed_message":"example","failed_code":1,"remainingDays":27,"isExpiringSoon":false}],"total":25},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1},"description":"Page number (starts from 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"description":"Number of items per page"}],"operationId":"getApiV1HeadSwapAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/headSwap/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/headSwap/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/headSwap/allRecords` — Get all head swap records.\n- `GET /api/v1/headSwap/{_id}` — Get head swap task detail.\n- `DELETE /api/v1/headSwap/{_id}` — Delete head swap task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Head Swap"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1HeadSwapBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/headSwap/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/headSwap/{_id}":{"get":{"summary":"Get head swap task detail","description":"Get detailed information of a specific head swap task by ID.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid task ID format.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/headSwap/allRecords` — Get all head swap records.\n- `DELETE /api/v1/headSwap/{_id}` — Delete head swap task.\n- `POST /api/v1/headSwap/start` — Start head swap generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Head Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: explicitly not refunded; omitted: unknown, including legacy records without a stored flag). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"image_url":{"type":"string","description":"Source head image URL","example":"https://example.com/head.jpg"},"target_image_url":{"type":"string","description":"Target body image/video URL","example":"https://example.com/body.jpg"},"result_url":{"type":"string","description":"Result image/video URL (available when completed)","example":"https://example.com/result.jpg"},"cover_url":{"type":"string","description":"Cover image URL for video results","example":"https://example.com/cover.jpg"},"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked"],"description":"Current task status","example":"completed"},"coins":{"type":"number","description":"Coins consumed for this task","example":5},"createdAt":{"type":"string","format":"date-time","description":"Task creation time","example":"2025-01-15T10:30:00.000Z"},"failed_message":{"type":"string","description":"Error message if task failed"},"failed_code":{"type":"number","description":"Error code if task failed (1003 = minor detected)"},"hasRefundCoin":{"type":"boolean","description":"Whether coins have been refunded","example":false},"remainingDays":{"type":"number","description":"Days until result expires","example":27},"isExpiringSoon":{"type":"boolean","description":"Whether result is expiring soon (< 3 days)","example":false}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","image_url":"https://example.com/head.jpg","target_image_url":"https://example.com/body.jpg","result_url":"https://example.com/result.jpg","cover_url":"https://example.com/cover.jpg","current_status":"completed","coins":5,"createdAt":"2025-01-15T10:30:00.000Z","failed_message":"example","failed_code":1,"hasRefundCoin":false,"remainingDays":27,"isExpiringSoon":false},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid task ID format"},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Head swap task ID (MongoDB ObjectId)"}],"operationId":"getApiV1HeadSwapId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/headSwap/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete head swap task","description":"Delete a head swap task by ID.\n**Status behavior:**\n- `initialized`: Queued, not terminal. Can be soft-deleted with a coin refund only after at least 60 seconds from task creation; before then returns HTTP 400 with code 30101\n- `sent/pending/processing`: Cannot be deleted, returns 400 error (task is processing)\n- `completed/failed/blocked` (including legacy `block`): Can be soft-deleted without this refund\nDeletion marks the task as deleted; it does not guarantee physical media removal.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/headSwap/allRecords` — Get all head swap records.\n- `GET /api/v1/headSwap/{_id}` — Get head swap task detail.\n- `POST /api/v1/headSwap/start` — Start head swap generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Head Swap"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task soft-deleted successfully; the response data is an empty object, not a refund receipt","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","description":"Empty object; refund behavior follows the queued-status rule above."},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101"},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Head swap task ID (MongoDB ObjectId)"}],"operationId":"deleteApiV1HeadSwapId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/headSwap/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/veoVideo/start":{"post":{"summary":"Start Veo 3.1 video generation","description":"Generate videos using Google DeepMind's Veo 3.1 AI model. Supports text-to-video, image-to-video, and reference-based generation.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/veoVideo/batchDetail` — Batch query task details.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Veo Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the video generation task (optional, auto-generated if not provided)","example":"My Veo Video"},"prompt":{"type":"string","description":"Text prompt describing the video content. Can be empty to use default placeholder text.","example":"Two person street interview in New York City. Sample Dialogue: Host: \"Did you hear the news?\" Person: \"Yes! Veo 3.1 is now available through this API.\""},"generationType":{"type":"string","enum":["TEXT_2_VIDEO","FIRST_AND_LAST_FRAMES_2_VIDEO","REFERENCE_2_VIDEO"],"description":"Type of generation (TEXT_2_VIDEO for text-only, FIRST_AND_LAST_FRAMES_2_VIDEO for image frames, REFERENCE_2_VIDEO for reference images)","default":"TEXT_2_VIDEO","example":"TEXT_2_VIDEO"},"imageUrls":{"type":"array","items":{"type":"string"},"description":"Image URLs for image-to-video generation. For FIRST_AND_LAST_FRAMES_2_VIDEO mode, 1-2 images (start/end frames). For REFERENCE_2_VIDEO mode, 1-3 reference images.","example":["https://example.com/start_frame.jpg","https://example.com/end_frame.jpg"]},"model":{"type":"string","enum":["veo3","veo3_fast"],"description":"Generation model (veo3 for quality, veo3_fast for speed)","default":"veo3_fast","example":"veo3_fast"},"aspectRatio":{"type":"string","enum":["16:9","9:16","Auto"],"description":"Video aspect ratio (Auto will determine automatically)","default":"Auto","example":"16:9"},"watermark":{"type":"string","description":"Custom watermark text (optional)","example":"MyBrand"},"seeds":{"type":"number","description":"Random seed for reproducible generation (10000-99999, optional)","example":12345},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"Two person street interview in New York City. Sample Dialogue: Host: \"Did you hear the news?\" Person: \"Yes! Veo 3.1 is now available through this API.\""}}}},"responses":{"200":{"description":"Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"message":{"type":"string","example":"success"},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Task name","example":"My Veo Video"},"prompt":{"type":"string","description":"Generation prompt","example":"Two person street interview"},"generationType":{"type":"string","description":"Generation type","example":"TEXT_2_VIDEO"},"model":{"type":"string","description":"Model used","example":"veo3_fast"},"aspectRatio":{"type":"string","description":"Aspect ratio","example":"16:9"},"current_status":{"type":"string","description":"Current task status (initialized, submitted, generating, completed, failed)","example":"initialized"},"coins":{"type":"number","description":"Credits consumed","example":80},"createdAt":{"type":"string","format":"date-time","description":"Task creation time","example":"2025-10-23T12:00:00.000Z"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"message":"success","data":{"_id":"507f1f77bcf86cd799439011","name":"My Veo Video","prompt":"Two person street interview","generationType":"TEXT_2_VIDEO","model":"veo3_fast","aspectRatio":"16:9","current_status":"initialized","coins":80,"createdAt":"2025-10-23T12:00:00.000Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1VeoVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/veoVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"Two person street interview in New York City. Sample Dialogue: Host: \\\"Did you hear the news?\\\" Person: \\\"Yes! Veo 3.1 is now available through this API.\\\"\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/veoVideo/allRecords":{"get":{"summary":"Get all Veo video records","description":"Retrieve paginated list of user's Veo video generation records.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/veoVideo/{_id}` — Get Veo video detail.\n- `DELETE /api/v1/veoVideo/{_id}` — Delete Veo video record.\n- `GET /api/v1/veoVideo/{_id}/1080p` — Get 1080P HD video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Veo Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskVeo"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"Number of records per page"}],"operationId":"getApiV1VeoVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/veoVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/veoVideo/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `POST /api/v1/veoVideo/start` — Start Veo 3.1 video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Veo Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskVeo"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1VeoVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/veoVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/veoVideo/{_id}":{"get":{"summary":"Get Veo video detail","description":"Retrieve detailed information of a specific Veo video generation record.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/veoVideo/allRecords` — Get all Veo video records.\n- `DELETE /api/v1/veoVideo/{_id}` — Delete Veo video record.\n- `GET /api/v1/veoVideo/{_id}/1080p` — Get 1080P HD video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Veo Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Video detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskVeo"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Video record ID"}],"operationId":"getApiV1VeoVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/veoVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete Veo video record","description":"Soft-delete the authenticated user's Veo video task identified by `_id`, preserving the stored record while excluding it from normal task lists.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/veoVideo/allRecords` — Get all Veo video records.\n- `GET /api/v1/veoVideo/{_id}` — Get Veo video detail.\n- `GET /api/v1/veoVideo/{_id}/1080p` — Get 1080P HD video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Veo Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Video record deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Video record ID"}],"operationId":"deleteApiV1VeoVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/veoVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/veoVideo/{_id}/1080p":{"get":{"summary":"Get 1080P HD video","description":"Retrieve 1080P high-definition version of the video (only available for 16:9 aspect ratio)\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Reads the requested information without creating a generation task.\n- Use the returned fields as documented; availability may depend on the caller and current resource state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid aspect ratio or missing task ID.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/veoVideo/allRecords` — Get all Veo video records.\n- `GET /api/v1/veoVideo/{_id}` — Get Veo video detail.\n- `DELETE /api/v1/veoVideo/{_id}` — Delete Veo video record.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Veo Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"1080P video retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","properties":{"hd_video_url":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"hd_video_url":"https://example.com/video.mp4"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"202":{"description":"1080P video is being processed, please try again later"},"400":{"description":"Invalid aspect ratio or missing task ID"},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Video record ID"}],"operationId":"getApiV1VeoVideoId1080p","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/veoVideo/507f1f77bcf86cd799439011/1080p\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/klingVideo/start":{"post":{"summary":"Start Kling video generation","description":"Generate videos using Kling Official API.\n**Modes:**\n- `text-to-video` – generate video from text prompt\n- `image-to-video` – generate video from an image (+ optional end frame in PRO)\n- `motion-control` – transfer motion from a video onto an image\n**Versions:** `2.6` (5s/10s) and `3.0` (standard/fast: 3s–15s)\n**Quality:** `std` (Standard), `pro` (Professional), or `4k` (Kling 3.0 Native 4K for text/image video).\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `mode`, `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/klingVideo/allRecords` — Get all Kling video records.\n- `GET /api/v1/klingVideo/{_id}` — Get Kling video detail.\n- `PUT /api/v1/klingVideo/{_id}` — Update Kling video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the video generation task","example":"My Kling Video"},"mode":{"type":"string","enum":["text-to-video","image-to-video","motion-control"],"description":"Generation mode: text-to-video, image-to-video, or motion-control","example":"image-to-video"},"prompt":{"type":"string","description":"Text prompt describing the desired video","example":"A beautiful sunset over the ocean"},"version":{"type":"string","enum":["2.6","3.0"],"description":"Kling model version. 2.6 supports 5s/10s, 3.0 supports 5s/10s/15s","default":"2.6","example":"3.0"},"model_version":{"type":"string","enum":["standard","fast"],"description":"Kling 3.0 model variant. fast requires version=3.0, supports text-to-video/image-to-video, supports 3–15s, and uses resolution instead of quality_mode=4k.","default":"standard","example":"fast"},"resolution":{"type":"string","enum":["720p","1080p"],"description":"Output resolution for model_version=fast","default":"720p","example":"720p"},"quality_mode":{"type":"string","enum":["std","pro","4k"],"description":"Quality mode. 4K is only available for Kling 3.0 text-to-video and image-to-video","default":"std","example":"std"},"duration":{"type":"string","enum":["3","4","5","6","7","8","9","10","11","12","13","14","15"],"description":"Video duration in seconds. Kling 2.6 supports 5s/10s; Kling 3.0 supports 3–15s.","default":"5","example":"5"},"image_url":{"type":"string","description":"Input image URL (required for image-to-video and motion-control modes)","example":"https://example.com/input.jpg"},"video_url":{"type":"string","description":"Input video URL (required for motion-control mode)","example":"https://example.com/input.mp4"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1"],"description":"Video aspect ratio (text-to-video mode only)","default":"16:9","example":"16:9"},"sound":{"type":"boolean","description":"Enable audio generation. For v2.6 only available in PRO mode (STD does not support sound). v3.0 supports sound in STD/PRO. 4K is billed as a separate quality tier.","default":false,"example":false},"end_image_url":{"type":"string","description":"End frame image URL (image-to-video + PRO mode only). Cannot be used with sound in v2.6","example":"https://example.com/end_frame.jpg"},"character_orientation":{"type":"string","enum":["video","image"],"description":"Character orientation for motion-control mode. 'image' limits duration to 3-10s, 'video' allows 3-30s","default":"video","example":"video"},"negative_prompt":{"type":"string","description":"Negative prompt to avoid certain elements","example":"blurry, low quality"},"seed":{"type":"number","description":"Random seed for reproducibility","example":12345},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["mode","prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"mode":"image-to-video","prompt":"A beautiful sunset over the ocean"}}}},"responses":{"200":{"description":"Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"message":{"type":"string","example":"success"},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"message":"success","data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters"},"401":{"description":"Unauthorized - Invalid or missing bearer token"}},"operationId":"postApiV1KlingVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/klingVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"mode\": \"image-to-video\",\n  \"prompt\": \"A beautiful sunset over the ocean\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/klingVideo/allRecords":{"get":{"summary":"Get all Kling video records","description":"Retrieve all Kling video generation records for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/klingVideo/{_id}` — Get Kling video detail.\n- `PUT /api/v1/klingVideo/{_id}` — Update Kling video name.\n- `DELETE /api/v1/klingVideo/{_id}` — Delete Kling video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved records. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"message":{"type":"string","example":"success"},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"message":"success","data":{"rows":[{}],"count":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Items per page"}],"operationId":"getApiV1KlingVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/klingVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/klingVideo/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/klingVideo/allRecords` — Get all Kling video records.\n- `GET /api/v1/klingVideo/{_id}` — Get Kling video detail.\n- `PUT /api/v1/klingVideo/{_id}` — Update Kling video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskKling"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1KlingVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/klingVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/klingVideo/{_id}":{"get":{"summary":"Get Kling video detail","description":"Get detailed information about a specific Kling video generation task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/klingVideo/allRecords` — Get all Kling video records.\n- `PUT /api/v1/klingVideo/{_id}` — Update Kling video name.\n- `DELETE /api/v1/klingVideo/{_id}` — Delete Kling video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskKling"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1KlingVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/klingVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"put":{"summary":"Update Kling video name","description":"Rename the authenticated user's Kling video task identified by `_id`; generation settings, processing status, and output media are unchanged.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n- Send an `application/json` body. Required fields: `name`.\n### Behavior\n- Updates the identified resource using the fields accepted by the request schema and the operation's access controls.\n- Fields omitted from the request retain their existing values unless the schema states otherwise.\n- Read the returned record or call the detail operation to confirm the persisted state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/klingVideo/allRecords` — Get all Kling video records.\n- `GET /api/v1/klingVideo/{_id}` — Get Kling video detail.\n- `DELETE /api/v1/klingVideo/{_id}` — Delete Kling video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name for the task","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}},"example":{"name":"My Task"}}}},"responses":{"200":{"description":"Name updated successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"putApiV1KlingVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https://headswap.app/api/v1/klingVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\"\n}'"}]},"delete":{"summary":"Delete Kling video","description":"Remove the authenticated user's Kling video task identified by `_id` from normal task history without affecting unrelated tasks.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/klingVideo/allRecords` — Get all Kling video records.\n- `GET /api/v1/klingVideo/{_id}` — Get Kling video detail.\n- `PUT /api/v1/klingVideo/{_id}` — Update Kling video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"deleteApiV1KlingVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/klingVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/klingOmni/start":{"post":{"summary":"Start Kling Omni video generation","description":"Generate videos using Kling Omni API (model: kling-v3-omni).\nThis is a simplified wrapper around the official Kling API.\n**Key Features:**\n- Multi-reference images: up to 7 images, use `<<<image_N>>>` tags in prompt\n- Multi-shot editing: AI Director (intelligence) or manual (customize) storyboard\n- Native sound generation via `sound` parameter\n- Flexible duration: 3–15 seconds\n**Simplified vs Official API:**\n- `image_list`: accepts `string[]` (image URLs); official uses `[{image_url, type?}]`, auto-converted on server\n- `sound`: accepts `boolean`; official uses `\"on\"/\"off\"`, auto-converted on server\n- `multi_prompt`: items need `prompt` + `duration`; server auto-adds `index` field for official API\n- `prompt` is required when `multi_shot=false` or `shot_type=intelligence`\n- `multi_prompt` total duration must equal `duration` when `shot_type=customize`\n- `element_ids`: `string[]` of Element `asset_id` values (not `_id`). Create an Element with `POST /api/v1/klingAssets/elements` (`name`, frontal `image_url`, 1–3 `reference_image_urls`), poll `GET /api/v1/klingAssets` until `status` is `succeed`, then pass its `asset_id`. With `image_list`, at most 3 Elements are allowed.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records.\n- `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail.\n- `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Omni"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Task name (internal use)","example":"My Kling Omni Video"},"prompt":{"type":"string","description":"Text prompt. Use <<<image_N>>> to reference images. Required when multi_shot=false or shot_type=intelligence.","example":"<<<image_1>>> walks towards <<<image_2>>> in a sunny park"},"image_list":{"type":"array","items":{"type":"string"},"description":"Reference image URLs (up to 7, jpg/jpeg/png, max 10MB). Simplified: pass URLs directly; server converts to official [{image_url}] format.","example":["https://example.com/ref1.jpg"]},"element_ids":{"type":"array","items":{"type":"string"},"description":"Kling Elements to include, as an array of `asset_id` strings (not the record `_id`). Create an Element with POST /api/v1/klingAssets/elements, then poll GET /api/v1/klingAssets until its `status` is succeed and read `asset_id`. Only your own succeeded Elements are accepted; duplicate IDs are rejected; with image_list, at most 3 Elements are allowed.","example":["860412385741664324"]},"mode":{"type":"string","enum":["std","pro"],"description":"Video generation mode. std=standard (720p), pro=professional (1080p)","default":"std"},"duration":{"type":"string","description":"Video duration in seconds (3–15)","default":"5"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1"],"default":"16:9"},"sound":{"type":"boolean","description":"Enable native sound generation. Simplified: pass boolean; server converts to official 'on'/'off'.","default":false},"multi_shot":{"type":"boolean","description":"Enable multi-shot mode","default":false},"shot_type":{"type":"string","enum":["intelligence","customize"],"description":"Shot type. Required when multi_shot=true."},"multi_prompt":{"type":"array","description":"Manual storyboard (required when shot_type=customize, 1–6 items, total duration must equal duration). Server auto-adds index field for official API.","items":{"type":"object","required":["prompt","duration"],"properties":{"prompt":{"type":"string","description":"Prompt for this shot (max 512 chars)","example":"<<<image_1>>> stands up and waves"},"duration":{"type":"string","description":"Duration in seconds","example":"3"}}}}},"required":[]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{}}}},"responses":{"200":{"description":"Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"message":{"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/KlingOmniTask"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"message":"success","data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","image_list":["example"],"mode":"std","duration":"example","aspect_ratio":"16:9","sound":false,"multi_shot":false,"shot_type":"intelligence","multi_prompt":[{"prompt":"high quality, clear, cinematic","duration":"example"}],"multi_shot_mode":"off","current_status":"initialized","result_url":"https://example.com/file","cover_url":"https://example.com/file","coins":1,"is_downloaded":false,"is_previewed":false,"failed_code":"example","failed_message":"example","failed_reason":"example","createdAt":"2026-01-01T00:00:00Z","remainingDays":1,"expirationDate":"2026-01-01T00:00:00Z","isExpired":false,"expirationDays":1,"shareId":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters"},"401":{"description":"Unauthorized - Invalid or missing bearer token"}},"operationId":"postApiV1KlingOmniStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/klingOmni/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/klingOmni/allRecords":{"get":{"summary":"Get all Kling Omni video records","description":"Retrieve paginated list of Kling Omni video generation tasks for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail.\n- `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name.\n- `DELETE /api/v1/klingOmni/{_id}` — Delete Kling Omni video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Omni"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Records retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/KlingOmniTask"}},"count":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","image_list":["example"],"mode":"std","duration":"example","aspect_ratio":"16:9","sound":false,"multi_shot":false,"shot_type":"intelligence","multi_prompt":[{"prompt":"high quality, clear, cinematic","duration":"example"}],"multi_shot_mode":"off","current_status":"initialized","result_url":"https://example.com/file","cover_url":"https://example.com/file","coins":1,"is_downloaded":false,"is_previewed":false,"failed_code":"example","failed_message":"example","failed_reason":"example","createdAt":"2026-01-01T00:00:00Z","remainingDays":1,"expirationDate":"2026-01-01T00:00:00Z","isExpired":false,"expirationDays":1,"shareId":"example"}],"count":1},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Number of records per page"}],"operationId":"getApiV1KlingOmniAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/klingOmni/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/klingOmni/batchDetail":{"post":{"summary":"Batch get Kling Omni video details","description":"Get details of multiple Kling Omni tasks by their IDs (max 200).\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records.\n- `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail.\n- `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Omni"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"$ref":"#/components/schemas/KlingOmniTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","image_list":["example"],"mode":"std","duration":"example","aspect_ratio":"16:9","sound":false,"multi_shot":false,"shot_type":"intelligence","multi_prompt":[{"prompt":"high quality, clear, cinematic","duration":"example"}],"multi_shot_mode":"off","current_status":"initialized","result_url":"https://example.com/file","cover_url":"https://example.com/file","coins":1,"is_downloaded":false,"is_previewed":false,"failed_code":"example","failed_message":"example","failed_reason":"example","createdAt":"2026-01-01T00:00:00Z","remainingDays":1,"expirationDate":"2026-01-01T00:00:00Z","isExpired":false,"expirationDays":1,"shareId":"example"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1KlingOmniBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/klingOmni/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/klingOmni/{_id}":{"get":{"summary":"Get Kling Omni video detail","description":"Get detailed information about a specific Kling Omni video generation task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records.\n- `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name.\n- `DELETE /api/v1/klingOmni/{_id}` — Delete Kling Omni video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Omni"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"$ref":"#/components/schemas/KlingOmniTask"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","image_list":["example"],"mode":"std","duration":"example","aspect_ratio":"16:9","sound":false,"multi_shot":false,"shot_type":"intelligence","multi_prompt":[{"prompt":"high quality, clear, cinematic","duration":"example"}],"multi_shot_mode":"off","current_status":"initialized","result_url":"https://example.com/file","cover_url":"https://example.com/file","coins":1,"is_downloaded":false,"is_previewed":false,"failed_code":"example","failed_message":"example","failed_reason":"example","createdAt":"2026-01-01T00:00:00Z","remainingDays":1,"expirationDate":"2026-01-01T00:00:00Z","isExpired":false,"expirationDays":1,"shareId":"example"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Task not found"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1KlingOmniId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/klingOmni/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"put":{"summary":"Update Kling Omni video name","description":"Rename the authenticated user's Kling Omni video task identified by `_id`; generation settings, processing status, and output media are unchanged.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n- Send an `application/json` body. Required fields: `name`.\n### Behavior\n- Updates the identified resource using the fields accepted by the request schema and the operation's access controls.\n- Fields omitted from the request retain their existing values unless the schema states otherwise.\n- Read the returned record or call the detail operation to confirm the persisted state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records.\n- `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail.\n- `DELETE /api/v1/klingOmni/{_id}` — Delete Kling Omni video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Omni"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name for the task","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}},"example":{"name":"My Task"}}}},"responses":{"200":{"description":"Updated successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"putApiV1KlingOmniId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https://headswap.app/api/v1/klingOmni/507f1f77bcf86cd799439011\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\"\n}'"}]},"delete":{"summary":"Delete Kling Omni video","description":"Soft-delete the authenticated user's Kling Omni video task identified by `_id`, preserving the stored record while excluding it from normal task lists.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records.\n- `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail.\n- `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Omni"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"deleteApiV1KlingOmniId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/klingOmni/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/klingAssets":{"get":{"summary":"List the authenticated user's Kling Elements and voices","description":"Returns the caller's Elements and voices (newest first, up to 1000). Pending assets are refreshed from Kling on each call, so poll this endpoint after creating an asset. Only Elements with `kind` element and `status` succeed can be used; pass their `asset_id` (not `_id`) in Kling Omni `element_ids`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- No request body or operation-specific parameters are required.\n### Behavior\n- Reads the requested information without creating a generation task.\n- Use the returned fields as documented; availability may depend on the caller and current resource state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/klingAssets/{id}` — Remove an owned Kling asset.\n- `POST /api/v1/klingAssets/voices` — Create a Kling custom voice.\n- `POST /api/v1/klingAssets/elements` — Create a Kling Element.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Assets"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Asset list returned","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Record ID; use it with DELETE /api/v1/klingAssets/{id}."},"kind":{"type":"string","enum":["element","voice"]},"name":{"type":"string"},"category":{"type":"string","description":"Element category (Elements only)."},"status":{"type":"string","enum":["submitted","processing","succeed","failed"]},"asset_id":{"type":"string","description":"Kling asset ID, filled in when status is succeed. Pass this value in Kling Omni element_ids (Elements) or Element voice_id (voices)."},"failed_message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","kind":"element","name":"My Task","category":"example","status":"submitted","asset_id":"507f1f77bcf86cd799439011","failed_message":"example","createdAt":"2026-01-01T00:00:00Z"}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApiV1KlingAssets","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/klingAssets\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/klingAssets/voices":{"post":{"summary":"Create a Kling custom voice","description":"Submit a 5 to 30 second voice sample. Poll the asset list until status is succeed before referencing its asset_id from an Element. Invalid audio URLs are cached for 180 seconds without extending the TTL on repeated requests. First and cached probe failures return the source failure reason in msg, retaining the existing HTTP 400 and code 500; no voice task or charge is created. A different full URL is probed immediately.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `voice_url`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Voice sample audio probe failed; code stays 500 and msg includes the audio source failure reason. No voice task or charge is created.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/klingAssets/{id}` — Remove an owned Kling asset.\n- `POST /api/v1/klingAssets/elements` — Create a Kling Element.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Assets"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":20,"description":"Voice name (max 20 characters).","example":"My Task"},"voice_url":{"type":"string","format":"uri","description":"Audio sample URL, 5 to 30 seconds long.","example":"https://example.com/file"}},"required":["name","voice_url"],"example":{"name":"My Task","voice_url":"https://example.com/file"}},"example":{"name":"My Task","voice_url":"https://example.com/file"}}}},"responses":{"200":{"description":"Voice creation submitted; `asset_id` is filled in once `status` becomes succeed","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Record ID; use it with DELETE /api/v1/klingAssets/{id}."},"kind":{"type":"string","enum":["element","voice"]},"name":{"type":"string"},"category":{"type":"string","description":"Element category (Elements only)."},"status":{"type":"string","enum":["submitted","processing","succeed","failed"]},"asset_id":{"type":"string","description":"Kling asset ID, filled in when status is succeed. Pass this value in Kling Omni element_ids (Elements) or Element voice_id (voices)."},"failed_message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","kind":"element","name":"My Task","category":"example","status":"submitted","asset_id":"507f1f77bcf86cd799439011","failed_message":"example","createdAt":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Voice sample audio probe failed; code stays 500 and msg includes the audio source failure reason. No voice task or charge is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":500,"msg":"Invalid audio URL: HTTP 404 Not Found. Check that the URL is accessible."}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1KlingAssetsVoices","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/klingAssets/voices\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\",\n  \"voice_url\": \"https://example.com/file\"\n}'"}]}},"/api/v1/klingAssets/elements":{"post":{"summary":"Create a Kling Element","description":"Submit an Element from a frontal image and one to three reference images. Poll the asset list until status is succeed, then pass its asset_id in Kling Omni element_ids.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `name`, `image_url`, `reference_image_urls`.\n### Behavior\n- Validates the submitted payload and performs the operation described by the request schema.\n- Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid input or unavailable voice.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `DELETE /api/v1/klingAssets/{id}` — Remove an owned Kling asset.\n- `POST /api/v1/klingAssets/voices` — Create a Kling custom voice.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Assets"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":20,"description":"Element name (max 20 characters).","example":"Lily"},"image_url":{"type":"string","format":"uri","description":"Frontal image URL.","example":"https://example.com/image.jpg"},"reference_image_urls":{"type":"array","minItems":1,"maxItems":3,"description":"One to three additional image URLs of the same subject from other angles.","items":{"type":"string","format":"uri","example":"https://example.com/image.jpg"},"example":["https://example.com/side.jpg"]},"voice_id":{"type":"string","description":"Optional asset_id of a completed voice owned by this user.","example":"507f1f77bcf86cd799439011"},"category":{"type":"string","enum":["characters","animals","items","costumes","scenes","effects","others"],"default":"characters","description":"Element category.","example":"characters"},"description":{"type":"string","maxLength":100,"description":"Optional text description of the Element (max 100 characters).","example":"example"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.","example":false}},"required":["name","image_url","reference_image_urls"],"example":{"name":"Lily","image_url":"https://example.com/image.jpg","reference_image_urls":["https://example.com/side.jpg"]}},"example":{"name":"Lily","image_url":"https://example.com/image.jpg","reference_image_urls":["https://example.com/side.jpg"]}}}},"responses":{"200":{"description":"Element creation submitted; `asset_id` is filled in once `status` becomes succeed","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Record ID; use it with DELETE /api/v1/klingAssets/{id}."},"kind":{"type":"string","enum":["element","voice"]},"name":{"type":"string"},"category":{"type":"string","description":"Element category (Elements only)."},"status":{"type":"string","enum":["submitted","processing","succeed","failed"]},"asset_id":{"type":"string","description":"Kling asset ID, filled in when status is succeed. Pass this value in Kling Omni element_ids (Elements) or Element voice_id (voices)."},"failed_message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","kind":"element","name":"My Task","category":"example","status":"submitted","asset_id":"507f1f77bcf86cd799439011","failed_message":"example","createdAt":"2026-01-01T00:00:00Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid input or unavailable voice"},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1KlingAssetsElements","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/klingAssets/elements\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"Lily\",\n  \"image_url\": \"https://example.com/image.jpg\",\n  \"reference_image_urls\": [\n    \"https://example.com/side.jpg\"\n  ]\n}'"}]}},"/api/v1/klingAssets/{id}":{"delete":{"summary":"Remove an owned Kling asset","description":"Remove an owned Kling asset.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `POST /api/v1/klingAssets/voices` — Create a Kling custom voice.\n- `POST /api/v1/klingAssets/elements` — Create a Kling Element.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Kling Assets"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Asset removed","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["_id","deleted"],"properties":{"_id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","deleted":true},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"id parameter"}],"operationId":"deleteApiV1KlingAssetsId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/klingAssets/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/grokVideo/start":{"post":{"summary":"Start Grok Imagine video generation","description":"Generate videos using Grok Imagine. Supports both text-to-video and image-to-video modes.\n**Modes:**\n- `text-to-video`: Generate video from a text prompt. Requires `prompt`.\n- `image-to-video`: Generate video from a reference image. Requires at least one image in `image_urls` (or `image_url`).\n**Duration:** `6`, `10`, or `15` seconds.\n**Model version:** `legacy` (default) uses the existing Grok Imagine path. `1.5` uses Grok Imagine Video 1.5 and only supports `image-to-video`.\n**Mode:** `fun`, `normal` (default), or `spicy`.\nThis is an asynchronous API. After calling this endpoint, poll `/api/v1/grokVideo/{_id}` to check task status until `current_status` becomes `completed` or `failed`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list.\n- `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail.\n- `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Grok Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the video generation task (optional, for identifying the task)","example":"My Grok Video"},"model_type":{"type":"string","enum":["text-to-video","image-to-video"],"description":"Generation mode. `text-to-video` generates video from text prompt, `image-to-video` generates video from a reference image.","default":"text-to-video","example":"text-to-video"},"model_version":{"type":"string","enum":["legacy","1.5"],"description":"Model version. `1.5` uses Grok Imagine Video 1.5 and only supports image-to-video.","default":"legacy","example":"1.5"},"prompt":{"type":"string","description":"Text prompt describing the video content. Required for text-to-video mode, optional for image-to-video mode.","example":"A cat playing with a ball of yarn in a cozy living room, warm lighting, cinematic style"},"mode":{"type":"string","enum":["fun","normal","spicy"],"description":"Generation style mode. For image-to-video, upstream may fallback spicy to normal.","default":"normal","example":"normal"},"image_urls":{"type":"array","items":{"type":"string"},"description":"Array of reference image URLs for image-to-video mode. At least one image is required when `model_type` is `image-to-video`.","example":["https://example.com/reference.jpg"]},"image_url":{"type":"string","description":"Single reference image URL (alternative to `image_urls`). Will be prepended to `image_urls` array.","example":"https://example.com/image.jpg"},"aspect_ratio":{"type":"string","enum":["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3"],"description":"Video aspect ratio. Legacy text-to-video supports 1:1/16:9/9:16; legacy image-to-video can additionally accept 4:3/3:4/3:2/2:3 depending on the selected generation path. Grok 1.5 accepts the full list including auto.","default":"16:9","example":"16:9"},"duration":{"type":"string","enum":["6","10","15"],"description":"Video duration in seconds.","default":"6","example":"6"},"nsfw_checker":{"type":"boolean","description":"Whether to enable additional NSFW checking for Grok 1.5.","default":false},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":[]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{}}}},"responses":{"200":{"description":"Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"message":{"type":"string","example":"success"},"data":{"type":"object","properties":{"_id":{"type":"string","description":"Task ID","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Task name","example":"My Grok Video"},"model_type":{"type":"string","description":"Generation mode","example":"text-to-video"},"prompt":{"type":"string","description":"Generation prompt","example":"A cat playing with yarn"},"aspect_ratio":{"type":"string","description":"Video aspect ratio","example":"16:9"},"resolution":{"type":"string","description":"Output video resolution","example":"480p"},"duration":{"type":"string","description":"Video duration in seconds","example":"5"},"current_status":{"type":"string","description":"Current task status (initialized, sent, pending, processing, completed, failed, blocked)","example":"initialized"},"coins":{"type":"number","description":"Credits consumed","example":20},"createdAt":{"type":"string","format":"date-time","description":"Task creation time","example":"2025-10-23T12:00:00.000Z"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"message":"success","data":{"_id":"507f1f77bcf86cd799439011","name":"My Grok Video","model_type":"text-to-video","prompt":"A cat playing with yarn","aspect_ratio":"16:9","resolution":"480p","duration":"5","current_status":"initialized","coins":20,"createdAt":"2025-10-23T12:00:00.000Z"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1GrokVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/grokVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/grokVideo/allRecords":{"get":{"summary":"Get Grok Video task list","description":"Retrieve paginated list of user's Grok Imagine video generation tasks, ordered by creation time (newest first).\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail.\n- `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task.\n- `POST /api/v1/grokVideo/start` — Start Grok Imagine video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Grok Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"}},"count":{"type":"integer","description":"Total number of records","example":42}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{}],"count":42},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number (starts from 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"Number of items per page"}],"operationId":"getApiV1GrokVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/grokVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/grokVideo/batchDetail":{"post":{"summary":"Batch query task details","description":"Query details for multiple tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list.\n- `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail.\n- `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Grok Video"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Batch details retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskGrok"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1GrokVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/grokVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/grokVideo/{_id}":{"get":{"summary":"Get Grok Video task detail","description":"Retrieve detailed information of a specific Grok Imagine video generation task by ID. Use this endpoint to poll task status after creation.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list.\n- `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task.\n- `POST /api/v1/grokVideo/start` — Start Grok Imagine video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Grok Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail retrieved successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object","properties":{"_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"current_status":{"type":"string","description":"Task status","example":"completed"},"result_url":{"type":"string","description":"Generated video URL (available when completed)","example":"https://cdn.example.com/video.mp4"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","current_status":"completed","result_url":"https://cdn.example.com/video.mp4"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID (MongoDB ObjectId)"}],"operationId":"getApiV1GrokVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/grokVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete Grok Video task","description":"Remove the authenticated user's Grok Imagine video task identified by `_id` from normal task history without affecting unrelated tasks.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized.\n### Related Operations\n- `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list.\n- `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail.\n- `POST /api/v1/grokVideo/start` — Start Grok Imagine video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Grok Video"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"message":{"type":"string","example":"success"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"message":"success","trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID (MongoDB ObjectId)"}],"operationId":"deleteApiV1GrokVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/grokVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/hailuoVideo/start":{"post":{"summary":"Start Hailuo video generation","description":"Generate videos using Hailuo. Only supports image-to-video mode.\n**Required:** `prompt` and at least one non-blank `image_url` or `image_urls` entry. A non-empty `image_url` takes precedence over `image_urls`; otherwise the first non-empty `image_urls` entry is used and must not be whitespace-only, and later entries are ignored.\n**Duration:** `6` or `10` seconds.\n**Resolution:** `768P` (default) or `1080P` (not available for 10s).\nThis is an asynchronous API. After calling this endpoint, poll `/api/v1/hailuoVideo/{_id}` to check task status.\nModel tiers: standard/pro. Valid duration/resolution pairs: 6s+768P, 6s+1080P, 10s+768P; 10s+1080P is rejected. At least one non-blank image_url or image_urls entry is required.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list.\n- `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail.\n- `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Hailuo Video Generation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Task name (optional)","example":"My Hailuo Video"},"prompt":{"type":"string","description":"Text prompt describing the video content. Required.","example":"A cat playing with a ball of yarn"},"image_urls":{"type":"array","items":{"type":"string"},"description":"Array of reference image URLs. At least one is required.","example":["https://example.com/image.jpg"]},"image_url":{"type":"string","description":"Single reference image URL (alternative to image_urls)."},"resolution":{"type":"string","enum":["768P","1080P"],"description":"Output video resolution. 1080P is not supported for 10s duration.","default":"768P"},"duration":{"type":"string","enum":["6","10"],"description":"Video duration in seconds.","default":"6"},"model":{"type":"string","enum":["standard","pro"],"default":"standard","description":"Pricing/model tier; independent from resolution."},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt"],"description":"prompt is required, plus at least one non-blank image_url OR image_urls entry. 10s+1080P is not supported.","anyOf":[{"required":["image_url"],"properties":{"image_url":{"type":"string","pattern":"\\S"}}},{"required":["image_urls"],"properties":{"image_url":{"type":"string","enum":[""]},"image_urls":{"type":"array","minItems":1,"items":{"type":"string"},"not":{"items":{"pattern":"^\\s*$"}}}}}],"not":{"required":["duration","resolution"],"properties":{"duration":{"enum":["10",10]},"resolution":{"enum":["1080P"]}}}},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"A cat playing with a ball of yarn","image_url":"https://example.com/image.jpg"}}}},"responses":{"200":{"description":"Task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1HailuoVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/hailuoVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"A cat playing with a ball of yarn\",\n  \"image_url\": \"https://example.com/image.jpg\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/hailuoVideo/allRecords":{"get":{"summary":"Get Hailuo Video task list","description":"Return the authenticated user's Hailuo video-generation tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail.\n- `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task.\n- `POST /api/v1/hailuoVideo/start` — Start Hailuo video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Hailuo Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskGeneral"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"pageSize parameter"}],"operationId":"getApiV1HailuoVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/hailuoVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/hailuoVideo/batchDetail":{"post":{"summary":"Batch query Hailuo Video task details","description":"Query details for multiple of the authenticated user's Hailuo video tasks at once by providing an array of task IDs.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list.\n- `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail.\n- `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Hailuo Video Generation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs to query","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskGeneral"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1HailuoVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/hailuoVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/hailuoVideo/{_id}":{"get":{"summary":"Get Hailuo Video task detail","description":"Return the authenticated user's Hailuo video task identified by `_id`, including its current status and video output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list.\n- `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task.\n- `POST /api/v1/hailuoVideo/start` — Start Hailuo video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Hailuo Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskGeneral"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"getApiV1HailuoVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/hailuoVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete Hailuo Video task","description":"Soft-delete the authenticated user's Hailuo video task identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list.\n- `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail.\n- `POST /api/v1/hailuoVideo/start` — Start Hailuo video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Hailuo Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"deleteApiV1HailuoVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/hailuoVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/minimaxH3Video/start":{"post":{"summary":"Start MiniMax H3 video generation","description":"Generate videos using MiniMax H3. Supports three modes via `mode`:\n`text-to-video`, `image-to-video` (first/last frame) and `reference-to-video` (reference images/videos/audios).\n**Required:** `prompt`. For `image-to-video`, `first_frame_url` is required.\nFor `reference-to-video`, at least one of `reference_image_urls` / `reference_video_urls` / `reference_audio_urls` is required.\n**Duration:** integer seconds between `4` and `15`.\n**Resolution:** `768P` or `2K` (default).\n**Aspect ratio:** for `text-to-video` one of `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`;\n`reference-to-video` additionally supports `adaptive` (default). Ignored for `image-to-video`.\nThis is an asynchronous API. After calling this endpoint, poll `/api/v1/minimaxH3Video/{_id}` to check task status.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list.\n- `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail.\n- `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["MiniMax H3 Video Generation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Task name (optional)","example":"My MiniMax H3 Video"},"mode":{"type":"string","enum":["text-to-video","image-to-video","reference-to-video"],"description":"Generation mode.","default":"text-to-video"},"prompt":{"type":"string","description":"Text prompt describing the video content. Required.","example":"A cinematic sunrise over snowy mountains"},"first_frame_url":{"type":"string","description":"First frame image URL. Required for image-to-video."},"last_frame_url":{"type":"string","description":"Last frame image URL (optional, image-to-video only)."},"reference_image_urls":{"type":"array","items":{"type":"string"},"description":"Reference image URLs (reference-to-video only)."},"reference_video_urls":{"type":"array","items":{"type":"string"},"description":"Reference video URLs (reference-to-video only)."},"reference_audio_urls":{"type":"array","items":{"type":"string"},"description":"Reference audio URLs (reference-to-video only)."},"resolution":{"type":"string","enum":["768P","2K"],"description":"Output video resolution.","default":"2K"},"duration":{"type":"string","description":"Video duration in seconds (4-15).","default":"12"},"aspect_ratio":{"type":"string","enum":["adaptive","21:9","16:9","4:3","1:1","3:4","9:16"],"description":"Output aspect ratio (text-to-video / reference-to-video)."},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"A cinematic sunrise over snowy mountains"}}}},"responses":{"200":{"description":"Task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1MinimaxH3VideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/minimaxH3Video/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"A cinematic sunrise over snowy mountains\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/minimaxH3Video/allRecords":{"get":{"summary":"Get MiniMax H3 Video task list","description":"Return the authenticated user's MiniMax H3 video-generation tasks using the requested pagination controls.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail.\n- `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task.\n- `POST /api/v1/minimaxH3Video/start` — Start MiniMax H3 video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["MiniMax H3 Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task list. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskMinimax"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":10,"example":10},"description":"pageSize parameter"}],"operationId":"getApiV1MinimaxH3VideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/minimaxH3Video/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/minimaxH3Video/batchDetail":{"post":{"summary":"Batch query MiniMax H3 Video task details","description":"Return details for several of the authenticated user's MiniMax H3 video tasks in one request.\nDuplicate ids are removed and at most 200 ids are processed per call.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list.\n- `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail.\n- `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["MiniMax H3 Video Generation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Task ids to query. An empty array returns an empty result.","example":["0123456789abcdef01234567"]}},"required":["ids"],"example":{"ids":["0123456789abcdef01234567"]}},"example":{"ids":["0123456789abcdef01234567"]}}}},"responses":{"200":{"description":"Task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskMinimax"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1MinimaxH3VideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/minimaxH3Video/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"0123456789abcdef01234567\"\n  ]\n}'"}]}},"/api/v1/minimaxH3Video/{_id}":{"get":{"summary":"Get MiniMax H3 Video task detail","description":"Return the authenticated user's MiniMax H3 video task identified by `_id`, including its current status and video output fields.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list.\n- `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task.\n- `POST /api/v1/minimaxH3Video/start` — Start MiniMax H3 video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["MiniMax H3 Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task detail. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskMinimax"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"getApiV1MinimaxH3VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/minimaxH3Video/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete MiniMax H3 Video task","description":"Soft-delete the authenticated user's MiniMax H3 video task identified by `_id`.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list.\n- `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail.\n- `POST /api/v1/minimaxH3Video/start` — Start MiniMax H3 video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["MiniMax H3 Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"deleteApiV1MinimaxH3VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/minimaxH3Video/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/seedanceVideo/start":{"post":{"summary":"Start Seedance 1.5 Pro video generation","description":"Generate videos using BytePlus ModelArk Seedance 1.5 Pro. Supports 3 modes - text-to-video, image-to-video, first-last-frames.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Bad Request - Invalid parameters.\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records.\n- `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail.\n- `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 1.5 Pro"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the video generation task","example":"My Seedance Video"},"mode":{"type":"string","enum":["text-to-video","image-to-video"],"description":"Generation mode. For first-last-frames usage, send mode=image-to-video together with image_url + end_image_url; the backend will normalize it.","default":"text-to-video","example":"image-to-video"},"prompt":{"type":"string","description":"Text prompt describing the desired video","example":"A girl holding a fox, the girl opens her eyes..."},"image_url":{"type":"string","description":"Input image URL (required for image-to-video mode; also used as the first frame in first-last-frames usage)","example":"https://example.com/input.jpg"},"end_image_url":{"type":"string","description":"Last frame image URL. When provided together with image_url, mode is automatically treated as first-last-frames.","example":"https://example.com/last.jpg"},"duration":{"type":"string","enum":["5","10"],"description":"Video duration in seconds","default":"5"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1"],"description":"Video aspect ratio","default":"16:9"},"resolution":{"type":"string","enum":["480p","720p"],"description":"Video resolution","default":"720p"},"camera_fixed":{"type":"boolean","description":"Whether the camera is fixed","default":false},"generate_audio":{"type":"boolean","description":"Whether to generate audio","default":false},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."}},"required":["prompt"]},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"A girl holding a fox, the girl opens her eyes..."}}}},"responses":{"200":{"description":"Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Bad Request - Invalid parameters"},"401":{"description":"Unauthorized - Invalid or missing bearer token"}},"operationId":"postApiV1SeedanceVideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedanceVideo/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"A girl holding a fox, the girl opens her eyes...\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/seedanceVideo/allRecords":{"get":{"summary":"Get all Seedance video records","description":"Retrieve all Seedance video generation records for the authenticated user.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail.\n- `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name.\n- `DELETE /api/v1/seedanceVideo/{_id}` — Delete Seedance video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 1.5 Pro"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved records. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Items per page"}],"operationId":"getApiV1SeedanceVideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedanceVideo/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/seedanceVideo/batchDetail":{"post":{"summary":"Batch get Seedance 1.5 task details","description":"Return details for up to 200 distinct task IDs owned by the authenticated user. An empty ids array returns an empty list.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records.\n- `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail.\n- `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 1.5 Pro"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"example":["507f1f77bcf86cd799439011"]}},"required":[],"example":{}},"example":{}}}},"responses":{"200":{"description":"Task details returned. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1SeedanceVideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedanceVideo/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{}'"}]}},"/api/v1/seedanceVideo/{_id}":{"get":{"summary":"Get Seedance video detail","description":"Get detailed information about a specific Seedance video generation task.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records.\n- `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name.\n- `DELETE /api/v1/seedanceVideo/{_id}` — Delete Seedance video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 1.5 Pro"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully retrieved task details. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"getApiV1SeedanceVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedanceVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"put":{"summary":"Update Seedance video name","description":"Rename the authenticated user's Seedance video task identified by `_id`; generation settings, processing status, and output media are unchanged.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n- Send an `application/json` body. Required fields: `name`.\n### Behavior\n- Updates the identified resource using the fields accepted by the request schema and the operation's access controls.\n- Fields omitted from the request retain their existing values unless the schema states otherwise.\n- Read the returned record or call the detail operation to confirm the persisted state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records.\n- `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail.\n- `DELETE /api/v1/seedanceVideo/{_id}` — Delete Seedance video.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 1.5 Pro"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name for the task","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}},"example":{"name":"My Task"}}}},"responses":{"200":{"description":"Name updated successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"putApiV1SeedanceVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https://headswap.app/api/v1/seedanceVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\"\n}'"}]},"delete":{"summary":"Delete Seedance video","description":"Remove the authenticated user's Seedance video task identified by `_id` from normal task history without affecting unrelated tasks.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found.\n### Related Operations\n- `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records.\n- `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail.\n- `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 1.5 Pro"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found"}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID"}],"operationId":"deleteApiV1SeedanceVideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/seedanceVideo/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/seedance2Video/start":{"post":{"summary":"Start Seedance 2.x video generation","description":"Generate videos with Seedance 2.0 (standard/mini/fast) or Seedance 2.5 (model_version=2.5). Supports text-to-video, image-to-video, first-last-frames, and reference modes. Image / video / audio inputs must be public URLs (asset:// URIs are not accepted from clients). Seedance 2.5 raises the limits: single-shot output up to 30s (2.0: 15s), up to 30 reference images / 10 reference videos / 10 reference audios (2.0: 9 / 3 / 3), reference video total duration up to 30s, resolution up to 1080p, and audio-only references are allowed (2.0 requires at least one image or video).\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `prompt`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/seedance2Video/allRecords` — Get all records.\n- `GET /api/v1/seedance2Video/{_id}` — Get task detail.\n- `PUT /api/v1/seedance2Video/{_id}` — Rename task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 2.x"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["prompt"],"properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["text-to-video","image-to-video","first-last-frames","reference"],"default":"text-to-video","description":"image-to-video uses image_url (+ optional last_frame_url); first-last-frames uses first_frame_url + last_frame_url; reference accepts any combination of reference_urls (image) / video_urls / audio_urls. On Seedance 2.0 audio cannot be used alone and must accompany at least one image or video reference; on Seedance 2.5 audio-only references are supported."},"model_version":{"type":"string","enum":["standard","mini","fast","2.5"],"default":"standard","description":"standard / mini / fast select a Seedance 2.0 tier. \"2.5\" selects Seedance 2.5, which currently has a single tier and higher input limits (see duration / reference_urls / video_urls / audio_urls)."},"omni_reference_task_type":{"type":"string","enum":["reference","edit","extend"],"description":"Seedance 2.5 reference-mode task hint. edit uses ratio=adaptive and duration=-1; extend uses ratio=adaptive; reference keeps the requested ratio and duration. edit currently accepts exactly one video_url. auto is intentionally not exposed because its output duration is unknown before billing."},"prompt":{"type":"string"},"image_url":{"type":"string","description":"First frame for image-to-video mode."},"first_frame_url":{"type":"string","description":"Required for first-last-frames mode."},"last_frame_url":{"type":"string","description":"Optional last frame for image-to-video; required for first-last-frames."},"reference_urls":{"type":"array","items":{"type":"string"},"maxItems":30,"description":"Reference images for reference mode. Max 9 on Seedance 2.0, max 30 on Seedance 2.5."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Reference videos (mp4/mov). Seedance 2.0: max 3 clips, each 2-15s, total <= 15 × number_of_videos seconds. Seedance 2.5: max 10 clips with a combined cap of 30s; omni_reference_task_type=edit currently requires exactly one clip. The server always probes video_urls (public hosts only, with separate connection/download/parse limits) as the authoritative duration for billing."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Reference audios (mp3/wav). Seedance 2.0: max 3 clips, each 2-15s, total <=15s, and audio cannot be used standalone (at least one image or video reference is required). Seedance 2.5: max 10 clips and audio-only references are allowed."},"input_video_duration":{"type":"number","minimum":2,"maximum":45.5,"description":"Optional client estimate of the total reference-video duration in seconds. This value is never trusted for final billing: the server always probes video_urls and bills on max(measured, this value), so passing a smaller number does not lower the price. Must be within [2, 15 × number_of_videos] on Seedance 2.0 and within [2, 30] on Seedance 2.5."},"duration":{"type":"integer","oneOf":[{"enum":[-1]},{"minimum":4,"maximum":30}],"default":5,"description":"Output length in seconds. Max 15 on Seedance 2.0; max 30 on Seedance 2.5. Seedance 2.5 edit tasks require -1."},"aspect_ratio":{"type":"string","enum":["adaptive","21:9","16:9","4:3","1:1","3:4","9:16"],"default":"16:9"},"resolution":{"type":"string","enum":["480p","720p","1080p","4k"],"default":"720p","description":"Only the standard tier of Seedance 2.0 supports 4k. Seedance 2.5 supports 480p / 720p / 1080p. The fast / mini tiers of Seedance 2.0 are limited to 480p / 720p."},"generate_audio":{"type":"boolean","default":true,"description":"Defaults to true to match billing (audio is included); pass false explicitly to disable."},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Skip soft minor-suspect block (code 1004); hard CSAM block (code 1003) is always enforced."}}},{"$ref":"#/components/schemas/WebhookInput"}]},"example":{"prompt":"high quality, clear, cinematic"}}}},"responses":{"200":{"description":"Task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1Seedance2VideoStart","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedance2Video/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"prompt\": \"high quality, clear, cinematic\"\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/seedance2Video/allRecords":{"get":{"summary":"Get all records","description":"List the current user's Seedance 2.0 video tasks with pagination.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedance2Video/{_id}` — Get task detail.\n- `PUT /api/v1/seedance2Video/{_id}` — Rename task.\n- `DELETE /api/v1/seedance2Video/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 2.x"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"Page number (1-based)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"example":20},"description":"Page size"}],"operationId":"getApiV1Seedance2VideoAllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedance2Video/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/seedance2Video/batchDetail":{"post":{"summary":"Batch get task details","description":"Fetch multiple Seedance 2.0 video task records in a single request (up to 200 ids).\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `ids`.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedance2Video/allRecords` — Get all records.\n- `GET /api/v1/seedance2Video/{_id}` — Get task detail.\n- `PUT /api/v1/seedance2Video/{_id}` — Rename task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 2.x"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Task record ids (max 200)","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}},"example":{"ids":["example"]}}}},"responses":{"200":{"description":"Success. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1Seedance2VideoBatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/seedance2Video/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"example\"\n  ]\n}'"}]}},"/api/v1/seedance2Video/{_id}":{"get":{"summary":"Get task detail","description":"Return the authenticated user's Seedance 2.0 video task identified by `_id`, including its generation settings, current status, and available video output.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/seedance2Video/allRecords` — Get all records.\n- `PUT /api/v1/seedance2Video/{_id}` — Rename task.\n- `DELETE /api/v1/seedance2Video/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 2.x"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskQueued"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task record id"}],"operationId":"getApiV1Seedance2VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/seedance2Video/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"put":{"summary":"Rename task","description":"Rename the authenticated user's Seedance 2.0 video task identified by `_id`; generation settings, processing status, and output media are unchanged.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n- Send an `application/json` body. Required fields: `name`.\n### Behavior\n- Updates the identified resource using the fields accepted by the request schema and the operation's access controls.\n- Fields omitted from the request retain their existing values unless the schema states otherwise.\n- Read the returned record or call the detail operation to confirm the persisted state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/seedance2Video/allRecords` — Get all records.\n- `GET /api/v1/seedance2Video/{_id}` — Get task detail.\n- `DELETE /api/v1/seedance2Video/{_id}` — Delete task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 2.x"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New task name","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}},"example":{"name":"My Task"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task record id"}],"operationId":"putApiV1Seedance2VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https://headswap.app/api/v1/seedance2Video/507f1f77bcf86cd799439011\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"name\": \"My Task\"\n}'"}]},"delete":{"summary":"Delete task","description":"Remove the authenticated user's Seedance 2.0 video task identified by `_id` from normal task history without affecting unrelated tasks.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/seedance2Video/allRecords` — Get all records.\n- `GET /api/v1/seedance2Video/{_id}` — Get task detail.\n- `PUT /api/v1/seedance2Video/{_id}` — Rename task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Seedance 2.x"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"message":"success"},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task record id"}],"operationId":"deleteApiV1Seedance2VideoId","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/seedance2Video/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan30/start":{"post":{"summary":"Start Wan3.0 all-in-one video generation","description":"Generate a video with `wan3.0-video` or `wan3.0-video-prime`.\nBoth models produce identical quality; `wan3.0-video-prime` only trades a higher\nper-second price for much faster inference (about 2 minutes instead of about 14\nminutes for a 720P 15-second clip). The request/response contract is identical —\nswitch by replacing the model name.\nReference mode accepts image, video, audio, file, and public web-page media.\nEach reference video must be 1–15 seconds; all reference videos together must\nnot exceed 15 seconds, and reference-video plus output duration must not exceed 30 seconds.\nStrict first-frame/first-last-frame media cannot be mixed with reference media.\nFile and link inputs are mutually exclusive.\n`prompt_extend` controls upstream prompt rewriting and defaults to false; when it\nstays off, write prompts following the Wan3.0 creator handbook prompt guide.\n`negative_prompt` is not supported.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body. Required fields: `model`, `input`, `parameters`.\n- API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields.\n### Behavior\n- This is an asynchronous operation: a successful submission creates a task and returns before processing finishes.\n- Persist the returned task identifier and use the corresponding detail or list operation to observe progress.\n- Treat the detail endpoint as the source of truth even when webhook delivery is enabled.\n### Response\n- A `200` response confirms task acceptance; it does not by itself mean media generation has completed.\n- Retain the returned identifier and wait for a documented terminal status before using output URLs.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `400` — Invalid mode, media combination, or generation parameter.\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `503` — Provider or Wan3.0 pricing is not configured.\n### Related Operations\n- `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks.\n- `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details.\n- `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan3.0 Video Generation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string","enum":["wan3.0-video","wan3.0-video-prime"],"default":"wan3.0-video"},"mode":{"type":"string","enum":["text-to-video","first-frame","first-last-frames","reference"],"default":"text-to-video"},"minor_suspected_skip":{"type":"boolean","default":false,"description":"Continue after explicitly confirming a suspected-minor warning. Confirmed minor/CSAM content is always blocked."},"input":{"type":"object","properties":{"prompt":{"type":"string","maxLength":5000},"media":{"type":"array","items":{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","enum":["reference_image","reference_video","reference_audio","first_frame","last_frame","file","link"]},"url":{"type":"string"},"duration":{"type":"number","description":"Input media duration in seconds."}}}}}},"parameters":{"type":"object","properties":{"resolution":{"type":"string","enum":["480P","720P","1080P"],"default":"1080P"},"ratio":{"type":"string","enum":["adaptive","16:9","4:3","1:1","3:4","9:16"],"default":"adaptive"},"duration":{"type":"integer","description":"Output duration from 2 to 30 seconds, or -1 for intelligent duration.","default":5},"audio":{"type":"boolean","default":true},"prompt_extend":{"type":"boolean","default":false,"description":"Enable upstream prompt rewriting. Off by default; keep it off and follow the creator handbook prompt guide for stable results."},"seed":{"type":"integer","minimum":0,"maximum":2147483647},"watermark":{"type":"boolean","default":false}}}},"required":["model","input","parameters"]},{"$ref":"#/components/schemas/WebhookInput"}]},"examples":{"reference":{"value":{"model":"wan3.0-video","mode":"reference","input":{"prompt":"Create a cinematic scene using the references.","media":[{"type":"reference_image","url":"https://example.com/reference.png"}]},"parameters":{"resolution":"1080P","ratio":"adaptive","duration":10,"audio":true}}}}}}},"responses":{"200":{"description":"Task created; save data._id for status polling. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"400":{"description":"Invalid mode, media combination, or generation parameter"},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Provider or Wan3.0 pricing is not configured"}},"operationId":"postApiV1UserWan30Start","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan30/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"model\": \"wan3.0-video\",\n  \"mode\": \"reference\",\n  \"input\": {\n    \"prompt\": \"Create a cinematic scene using the references.\",\n    \"media\": [\n      {\n        \"type\": \"reference_image\",\n        \"url\": \"https://example.com/reference.png\"\n      }\n    ]\n  },\n  \"parameters\": {\n    \"resolution\": \"1080P\",\n    \"ratio\": \"adaptive\",\n    \"duration\": 10,\n    \"audio\": true\n  }\n}'"}],"callbacks":{"terminalTask":{"$ref":"#/components/callbacks/A2eTaskTerminal"}}}},"/api/v1/userWan30/allRecords":{"get":{"summary":"List Wan3.0 video tasks","description":"List the authenticated user's Wan3.0 tasks, including status and result_url for completed tasks, with their stored refund status. Missing refund state is unknown.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema.\n### Behavior\n- Returns the collection visible in the current request and authorization context.\n- Apply the documented pagination and filter parameters when present; use response metadata to continue paging.\n- Record fields and status values have the same meaning as in the corresponding detail operation.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details.\n- `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task.\n- `POST /api/v1/userWan30/start` — Start Wan3.0 all-in-one video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan3.0 Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Paginated Wan3.0 task records in data.rows. Each task has optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown).","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object","required":["rows","count"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"count":{"type":"integer","minimum":0}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"rows":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"count":0},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"pageNum","in":"query","required":false,"schema":{"type":"integer","default":1,"example":1},"description":"pageNum parameter"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":20,"example":20},"description":"pageSize parameter"}],"operationId":"getApiV1UserWan30AllRecords","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan30/allRecords\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}},"/api/v1/userWan30/batchDetail":{"post":{"summary":"Batch get Wan3.0 video task details","description":"Query up to 200 task IDs belonging to the authenticated user. The response data is an array of task details with their stored refund status. Missing refund state is unknown.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Send an `application/json` body when using the optional controls documented in the request schema.\n### Behavior\n- Fetches several task records in one request, reducing the number of individual detail calls.\n- Results remain subject to the same authentication and ownership checks as single-record lookups.\n- Match returned records by their identifiers instead of relying on response ordering.\n### Response\n- The `200` response contains the requested collection in the response envelope documented below.\n- An empty collection is a successful result when no matching records are available.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks.\n- `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details.\n- `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan3.0 Video Generation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Task IDs; the server deduplicates and queries at most 200. Missing or empty IDs return an empty array.","example":["example"]}},"required":[],"example":{}},"example":{"ids":["507f1f77bcf86cd799439011"]}}}},"responses":{"200":{"description":"Matching Wan3.0 task details in data. Each task has optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown).","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":[{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5}],"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postApiV1UserWan30BatchDetail","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https://headswap.app/api/v1/userWan30/batchDetail\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n  \"ids\": [\n    \"507f1f77bcf86cd799439011\"\n  ]\n}'"}]}},"/api/v1/userWan30/{_id}":{"get":{"summary":"Get Wan3.0 video task details","description":"Poll this endpoint with data._id from the start response. When data.current_status is completed, read the generated video from data.result_url. The task includes its stored refund status; missing refund state is unknown.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Retrieves the current server-side representation of the requested resource or task.\n- For asynchronous tasks, inspect the documented status and result fields before consuming generated media.\n- Repeat the request only as needed for polling and stop after the task reaches a terminal state.\n### Response\n- On `200`, consume the fields defined by that response schema below.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n- `404` — Task not found for the authenticated user.\n- `429` — Task query budget exceeded; retry after the Retry-After response header.\n- `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.\n### Related Operations\n- `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks.\n- `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task.\n- `POST /api/v1/userWan30/start` — Start Wan3.0 all-in-one video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan3.0 Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Wan3.0 video task status and output. The task has optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown).","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{"_id":"507f1f77bcf86cd799439011","name":"My Task","prompt":"high quality, clear, cinematic","is_downloaded":false,"is_previewed":false,"current_status":"initialized","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","expirationDate":"2026-01-01T00:00:00Z","remainingDays":1,"isExpired":false,"coins":1,"hasRefundCoin":false,"failed_code":"example","failed_message":"example","failed_reason":"example","image_url":"https://example.com/image.jpg","image_urls":["https://example.com/image.jpg"],"result_url":"https://example.com/file","video_url":"https://example.com/video.mp4","result_video_url":"https://example.com/video.mp4","cover_url":"https://example.com/file","result_cover":"example","hd_video_url":"https://example.com/video.mp4","video_time":5,"duration_seconds":5},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found for the authenticated user."},"429":{"description":"Task query budget exceeded; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Task query budget temporarily unavailable; retry after the Retry-After response header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"Task ID returned by POST /api/v1/userWan30/start."}],"operationId":"getApiV1UserWan30Id","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET \"https://headswap.app/api/v1/userWan30/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]},"delete":{"summary":"Delete a Wan3.0 video task","description":"Delete the authenticated user's Wan3.0 task record identified by _id.\n### Request\n- Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context.\n- Supply `_id` in the URL path.\n### Behavior\n- Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules.\n- Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records.\n- Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior.\n### Response\n- A `200` response confirms that the deletion request was applied to the selected record.\n- JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier.\n- Do not infer undocumented fields or statuses; clients should tolerate additional response properties.\n### Errors\n- `401` — Unauthorized - Invalid or missing JWT token.\n### Related Operations\n- `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks.\n- `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details.\n- `POST /api/v1/userWan30/start` — Start Wan3.0 all-in-one video generation.\n\nAuthentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).","tags":["Wan3.0 Video Generation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Wan3.0 task record deleted.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","enum":[0]},"data":{"type":"object"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"example":{"code":0,"data":{},"trace_id":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}}},"401":{"description":"Unauthorized - Invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","example":"507f1f77bcf86cd799439011"},"description":"_id parameter"}],"operationId":"deleteApiV1UserWan30Id","x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE \"https://headswap.app/api/v1/userWan30/507f1f77bcf86cd799439011\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\""}]}}},"components":{"schemas":{"SuccessResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Response code. 0 means success.","example":0},"data":{"description":"Response data"}},"required":["code","data"]},"GenerationTask":{"type":"object","required":["_id","current_status"],"description":"Lifecycle examples: created {\"_id\":\"task-id\",\"current_status\":\"initialized\"}; in progress {\"_id\":\"task-id\",\"current_status\":\"processing\"}; succeeded {\"_id\":\"task-id\",\"current_status\":\"completed\"}; failed {\"_id\":\"task-id\",\"current_status\":\"failed\",\"failed_message\":\"Generation failed\"}. Concrete task family schemas below define all allowed states and terminal values.","properties":{"_id":{"type":"string","description":"Task ID for detail and batch polling."},"name":{"type":"string"},"prompt":{"type":"string"},"is_downloaded":{"type":"boolean"},"is_previewed":{"type":"boolean"},"current_status":{"type":"string","description":"Persisted task state; use the concrete task family schema for its allowed values and terminal states.","example":"processing"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expirationDate":{"type":"string","format":"date-time","nullable":true},"remainingDays":{"type":"number"},"isExpired":{"type":"boolean"},"coins":{"type":"number"},"hasRefundCoin":{"type":"boolean","description":"Whether charged credits were refunded."},"failed_code":{"type":"string"},"failed_message":{"type":"string"},"failed_reason":{"type":"string","description":"Public failure category when available."}}},"GenerationImageTask":{"allOf":[{"$ref":"#/components/schemas/GenerationTask"},{"type":"object","properties":{"creation_mode":{"type":"string"},"image_url":{"type":"string","nullable":true},"image_urls":{"type":"array","items":{"type":"string"}},"result_image_url":{"type":"string","nullable":true},"result_image_urls":{"type":"array","items":{"type":"string"}},"input_images":{"type":"array","items":{"type":"string"}}}}]},"GenerationVideoTask":{"allOf":[{"$ref":"#/components/schemas/GenerationTask"},{"type":"object","properties":{"image_url":{"type":"string","nullable":true},"image_urls":{"type":"array","items":{"type":"string"}},"result_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"result_video_url":{"type":"string","nullable":true},"cover_url":{"type":"string","nullable":true},"result_cover":{"type":"string","nullable":true},"hd_video_url":{"type":"string","nullable":true},"video_time":{"type":"number"},"duration_seconds":{"type":"number"}}}]},"GenerationAudioTask":{"allOf":[{"$ref":"#/components/schemas/GenerationTask"},{"type":"object","properties":{"audio_url":{"type":"string","nullable":true},"result_url":{"type":"string","nullable":true}}}]},"GenerationImageTaskBasic":{"allOf":[{"$ref":"#/components/schemas/GenerationImageTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","processing","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationImageTaskLegacy":{"allOf":[{"$ref":"#/components/schemas/GenerationImageTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationImageTaskGeneral":{"allOf":[{"$ref":"#/components/schemas/GenerationImageTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked","canceled"],"description":"Terminal values for this task family: completed, failed, blocked, canceled. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationImageTaskNano":{"allOf":[{"$ref":"#/components/schemas/GenerationImageTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","processing","seedream_fallback","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskLegacy":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskGeneral":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked","canceled"],"description":"Terminal values for this task family: completed, failed, blocked, canceled. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskQueued":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","queued","processing","completed","failed","blocked"],"description":"Terminal values for this task family: completed, failed, blocked. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskKling":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","queued","processing","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskKlingOmni":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","queued","processing","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskVeo":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","submitted","generating","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskGrok":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked","canceled"],"description":"Terminal values for this task family: completed, failed, blocked, canceled. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskMinimax":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked","canceled"],"description":"Terminal values for this task family: completed, failed, blocked, canceled. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskUpscale":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pending","processing","completed","failed","blocked"],"description":"Terminal values for this task family: completed, failed, blocked. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationVideoTaskDubbing":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","sent","pendding","processing","completed","failed"],"description":"Terminal values for this task family: completed, failed. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationAudioTaskThinkSound":{"allOf":[{"$ref":"#/components/schemas/GenerationAudioTask"},{"type":"object","required":["current_status"],"properties":{"current_status":{"type":"string","enum":["initialized","waiting","sent","pending","processing","completed","failed","canceled"],"description":"Terminal values for this task family: completed, failed, canceled. Stop polling on any terminal value.","example":"initialized"}}}]},"GenerationBackgroundRemovalStartTask":{"allOf":[{"$ref":"#/components/schemas/GenerationImageTaskBasic"},{"type":"object","required":["detail_url"],"properties":{"detail_url":{"type":"string","description":"Relative URL for polling this GPT Image task.","example":"/api/v1/userGptImage/detail/507f1f77bcf86cd799439011"}}}]},"GenerationVirtualTryOnTask":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},{"type":"object","properties":{"image_urls":{"type":"array","items":{"type":"string"}},"task_type":{"type":"string","enum":["image","video"]},"result_image_url":{"type":"string","nullable":true}}}]},"GenerationTalkingVideoTask":{"allOf":[{"$ref":"#/components/schemas/GenerationVideoTaskLegacy"},{"type":"object","properties":{"audio_result_url":{"type":"string","nullable":true}}}]},"GenerationModerationResult":{"type":"object","required":["nsfw_detected"],"properties":{"nsfw_detected":{"type":"boolean","enum":[true]},"message":{"type":"string"}}},"Text2ImageStartResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Response code. 0 means success.","example":0},"data":{"type":"array","description":"Created text-to-image task records.","items":{"type":"object","properties":{"_id":{"type":"string","description":"Task id."},"name":{"type":"string","description":"Task name."},"prompt":{"type":"string","description":"Generation prompt."},"current_status":{"type":"string","description":"Current task status."},"image_urls":{"type":"array","description":"Generated image URLs.","items":{"type":"string"}},"width":{"type":"number","description":"Output image width."},"height":{"type":"number","description":"Output image height."},"coins":{"type":"number","description":"Credits charged for the task."}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}},"required":["code","data"]},"AvatarListResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Response code. 0 means success.","example":0},"data":{"type":"array","description":"Avatars available to the authenticated API user.","items":{"type":"object","description":"Avatar record"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}},"required":["code","data"]},"UserVoice":{"type":"object","properties":{"_id":{"type":"string","description":"Record id (MongoDB ObjectId)","example":"65a3b8c6f0c2d3e4f5a6b7c8"},"name":{"type":"string","description":"Voice model name","example":"My Custom Voice"},"voice_urls":{"type":"array","description":"Audio sample URLs used for training","items":{"type":"string"}},"gender":{"type":"string","description":"Voice gender","enum":["female","male"],"example":"female"},"model":{"type":"string","description":"Voice model provider","enum":["a2e","cartesia","minimax","elevenlabs"],"example":"a2e"},"lang":{"type":"string","description":"Internal language code used by model","example":"en"},"language":{"type":"string","description":"Original language code from client","example":"en-US"},"current_status":{"type":"string","description":"Training status","enum":["sent","pendding","processing","completed","failed"],"example":"processing"},"speaker_id":{"type":"string","description":"Speaker id returned by vendor","example":"a2e-voice-xxxx"},"coins":{"type":"number","description":"Coins cost for this training (if any)","example":0},"denoise":{"type":"boolean","description":"Whether denoising is enabled","example":true},"enhance_voice_similarity":{"type":"boolean","description":"Whether enhance voice similarity is enabled","example":true},"ttsRate":{"type":"number","description":"TTS rate (coins per 10 seconds)","example":1},"hasRefundCoin":{"type":"boolean","description":"Whether coins have been refunded for failed training","example":false},"migration_required":{"type":"boolean","description":"Whether this is a legacy Qwen VC voice that should be re-cloned before the vendor retires it","example":false},"user_id":{"type":"string","description":"Owner user id","example":"65a3b8c6f0c2d3e4f5a6b7c1"},"createdAt":{"type":"string","format":"date-time","description":"Created time","example":"2025-01-14T18:22:13.726Z"},"updatedAt":{"type":"string","format":"date-time","description":"Updated time","example":"2025-01-14T18:22:13.726Z"}}},"UserVoiceTrainingRequest":{"type":"object","required":["name","voice_urls"],"properties":{"name":{"type":"string","description":"Name of the voice model","example":"My Custom Voice"},"voice_urls":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Array of audio file URLs for training","example":["https://example.com/audio1.wav","https://example.com/audio2.wav"]},"gender":{"type":"string","enum":["female","male"],"description":"Voice gender","default":"female","example":"female"},"denoise":{"type":"boolean","description":"Whether to apply denoising","example":true},"enhance_voice_similarity":{"type":"boolean","description":"Whether to enhance voice similarity","example":true},"model":{"type":"string","enum":["a2e","cartesia","minimax","elevenlabs"],"description":"Voice model to use","default":"a2e","example":"a2e"},"language":{"type":"string","description":"Language code from client (e.g. en-US, zh-CN). If omitted, server will infer from request headers.","example":"en-US"}}},"UserVoiceUpdateRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"New name of the voice record","example":"My Renamed Voice"}}},"SuccessUserVoiceResponse":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"$ref":"#/components/schemas/UserVoice"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}},"required":["code","data"]},"SuccessUserVoiceListResponse":{"type":"object","properties":{"code":{"type":"integer","example":0},"data":{"type":"array","items":{"$ref":"#/components/schemas/UserVoice"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}},"required":["code","data"]},"R2UploadPresignedUrlResponse":{"type":"object","properties":{"code":{"type":"integer","example":0,"description":"Response code. 0 means success."},"data":{"type":"object","required":["uploadUrl","cdnUrl","key","bucket","expiresIn"],"properties":{"uploadUrl":{"type":"string","description":"Pre-signed URL. Upload the file with HTTP PUT."},"cdnUrl":{"type":"string","description":"Public CDN URL to use after upload succeeds."},"key":{"type":"string","description":"Final R2 object key."},"bucket":{"type":"string"},"expiresIn":{"type":"integer"}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}},"required":["code","data"]},"ErrorResponse":{"type":"object","properties":{"code":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Business or HTTP error code","example":400},"msg":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Legacy error message"},"success":{"type":"boolean","description":"Legacy success flag","example":false},"data":{"description":"Optional business error details"},"errors":{"type":"array","items":{"type":"object"},"description":"Validation errors when present"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}},"required":["code"],"anyOf":[{"required":["msg"]},{"required":["message"]}]},"SeedAudioTask":{"type":"object","required":["_id","current_status","text_prompt"],"properties":{"_id":{"type":"string"},"current_status":{"type":"string","enum":["initialized","processing","completed","failed"]},"text_prompt":{"type":"string"},"display_text":{"type":"string"},"performance_direction":{"type":"string"},"result_url":{"type":"string","description":"Generated audio URL, empty until the task is completed"},"format":{"type":"string","example":"wav"},"duration":{"type":"number","description":"Output audio duration in seconds"},"original_duration":{"type":"number","description":"Provider-reported duration used for billing"},"billed_duration":{"type":"number"},"billing_unit_price":{"type":"number"},"billing_reservation_coins":{"type":"number"},"expected_coins":{"type":"number"},"coins":{"type":"number","description":"Credits finally charged for this task"},"billing_discount_coins":{"type":"number"},"hasRefundCoin":{"type":"boolean"},"subtitle":{"type":"object","nullable":true},"request_id":{"type":"string"},"provider_log_id":{"type":"string"},"failed_code":{"type":"string"},"failed_message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expiration_days":{"type":"integer","description":"Days the generated audio is retained"},"expiration_time":{"type":"string","format":"date-time","nullable":true}}},"SeedAudioTaskResponse":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/SeedAudioTask"},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"SeedAudioTaskArrayResponse":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SeedAudioTask"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"SeedAudioTaskListResponse":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"message":{"type":"string"},"data":{"type":"object","required":["count","rows"],"properties":{"count":{"type":"integer","description":"Total number of records"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/SeedAudioTask"}}}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"SeedAudioSpeaker":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","description":"Speaker ID, pass it as references[].speaker"},"name":{"type":"string"},"gender":{"type":"string","enum":["male","female","other"]},"age":{"type":"string"},"description":{"type":"string"},"avatar_url":{"type":"string"},"preview_url":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}}}},"SeedAudioSpeakerListResponse":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","example":0},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SeedAudioSpeaker"}},"trace_id":{"type":"string","description":"Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.","example":"3f2c9a1e-8b7d-4c6a-9e15-2d4b7f0a6c81"}}},"KlingOmniTask":{"type":"object","required":["_id","current_status"],"properties":{"_id":{"type":"string","description":"Task ID; use it with the detail, update and delete endpoints"},"name":{"type":"string"},"prompt":{"type":"string"},"image_list":{"type":"array","items":{"type":"string"},"description":"Reference image URLs"},"mode":{"type":"string","enum":["std","pro","4k"]},"duration":{"type":"string","description":"Video duration in seconds"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1"]},"sound":{"type":"boolean"},"multi_shot":{"type":"boolean"},"shot_type":{"type":"string","enum":["intelligence","customize"]},"multi_prompt":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string"},"duration":{"type":"string"}}}},"multi_shot_mode":{"type":"string","enum":["off","auto","manual"]},"current_status":{"type":"string","enum":["initialized","sent","queued","processing","completed","failed"],"description":"completed and failed are terminal states"},"result_url":{"type":"string","description":"Generated video URL, empty until the task is completed"},"cover_url":{"type":"string"},"coins":{"type":"number","description":"Credits charged for this task"},"is_downloaded":{"type":"boolean"},"is_previewed":{"type":"boolean"},"failed_code":{"type":"string"},"failed_message":{"type":"string"},"failed_reason":{"type":"string","description":"Public failure reason, present only when the task failed"},"createdAt":{"type":"string","format":"date-time"},"remainingDays":{"type":"integer","description":"Days left before the result expires"},"expirationDate":{"type":"string","format":"date-time","nullable":true},"isExpired":{"type":"boolean"},"expirationDays":{"type":"integer","description":"Retention period in days"},"shareId":{"type":"string","description":"Share identifier, present only for completed tasks"}}},"VideoTwinRecord":{"type":"object","required":["_id","current_status"],"properties":{"_id":{"type":"string","description":"Video twin ID"},"name":{"type":"string"},"gender":{"type":"string"},"image_url":{"type":"string"},"video_url":{"type":"string"},"current_status":{"type":"string","enum":["initialized","sent","pending","processing","copying","completed","failed"],"description":"completed and failed are terminal states"},"failed_code":{"type":"string"},"failed_message":{"type":"string"},"failed_reason":{"type":"string","description":"Public failure reason, present only when training failed"},"preview_result_url":{"type":"string","description":"Preview video URL; falls back to video_url once completed"},"image_result_url":{"type":"string"},"video_backgroud_image":{"type":"string","description":"Background image URL (field name keeps the historical spelling)"},"video_backgroud_color":{"type":"string","description":"Background color in RGBA format"},"skipPreview":{"type":"boolean"},"isSilent":{"type":"boolean"},"hasVoiceClone":{"type":"boolean"},"hasVideoClone":{"type":"boolean"},"hasEyecontact":{"type":"boolean"},"eyecontact_result_url":{"type":"string"},"custom_anchor_id":{"type":"string","description":"Custom avatar created from this twin"},"anchor_id":{"type":"string"},"user_voice_id":{"type":"string","description":"Cloned voice linked to this twin"},"coins":{"type":"number"},"hasRefundCoin":{"type":"boolean"}}},"WebhookInput":{"type":"object","properties":{"webhook_url":{"type":"string","description":"HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.","example":"https://your-server.example.com/a2e/webhook","maxLength":2048},"webhook_token":{"type":"string","description":"Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.","example":"a-shared-secret","maxLength":256}}},"A2eTaskWebhook":{"type":"object","description":"The formatted task object, without a code/data or event/data envelope. Fields vary by task family.","properties":{"_id":{"type":"string","description":"Task ID for deduplication and detail polling."},"current_status":{"type":"string","description":"Terminal status for most task families: completed, failed, or blocked (delivered as task.failed)."},"status":{"type":"string","description":"Legacy Video status: success or fail. Use X-A2e-Event as the common terminal signal."}},"additionalProperties":true}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use Authorization: Bearer <API_TOKEN>. Generate the token in Account > API Token. Public developer API calls should use API tokens that start with sk_."}},"callbacks":{"A2eTaskTerminal":{"{$request.body#/webhook_url}":{"post":{"summary":"Terminal task callback","description":"Single best-effort POST, no retries. Return any 2xx within 5 seconds; redirects are not followed. Request and response bodies are limited to 64 KiB. See the Webhook receiving protocol in the API introduction.","parameters":[{"name":"X-A2e-Event","in":"header","required":true,"schema":{"type":"string","enum":["task.completed","task.failed"]}},{"name":"X-A2e-Task-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-A2e-Webhook-Token","in":"header","required":false,"description":"Your configured shared token, if supplied. No HMAC signature is sent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/A2eTaskWebhook"},"examples":{"completed":{"summary":"X-A2e-Event: task.completed","value":{"_id":"507f1f77bcf86cd799439011","current_status":"completed"}},"failed":{"summary":"X-A2e-Event: task.failed","value":{"_id":"507f1f77bcf86cd799439012","current_status":"failed"}},"legacyVideo":{"summary":"Legacy Video with X-A2e-Event: task.completed","value":{"_id":"507f1f77bcf86cd799439013","status":"success"}}}}}},"responses":{"2XX":{"description":"Any 2xx acknowledges receipt; failed deliveries are not retried."}}}}}}},"tags":[{"name":"Miscellaneous","description":"Supporting utilities including file upload to cloud storage, pre-signed URL generation, URL saving, and other helper endpoints used across API workflows."},{"name":"Credits"},{"name":"Generate Avatar Videos","description":"Submit a script or audio file to generate an avatar presentation video. The digital avatar lip-syncs to your content and speaks on your behalf."},{"name":"TTS and Voice Clone","description":"Convert text to natural-sounding speech using a library of built-in voices, or clone a custom voice from a short audio sample for consistent narration."},{"name":"Create Avatars","description":"Train and manage custom digital avatars from uploaded video recordings. Trained avatars can then be used in avatar video generation workflows."},{"name":"Background Library","description":"Add, list, and delete images in the custom background library. For image subject cutout, use the separate Image Background Removal API."},{"name":"Video Twin","description":"Build a personalised video twin - a digital double trained on your own footage - that can speak and present content on your behalf with natural motion."},{"name":"Face Swap","description":"Swap faces between a source and a target image or video with identity-preserving blending. Handles diverse lighting, pose, and expression conditions."},{"name":"AI Dubbing","description":"Automatically translate and re-dub a video into a target language using voice cloning and AI-driven lip-sync adjustment."},{"name":"Caption Removal","description":"Detect and cleanly remove embedded captions, subtitles, or text overlays from video frames using AI inpainting."},{"name":"Upscale","description":"Enhance the resolution of images and videos using AI super-resolution. Sharpens fine detail and reduces compression artifacts without visible upscale noise."},{"name":"Text to Image","description":"Generate images from natural language prompts using the platform's diffusion model pipeline. Describe what you want - style, composition, lighting - and receive high-resolution results."},{"name":"Nano Banana","description":"Image generation powered by Google Gemini's image model. Accepts text-only prompts or text combined with up to four reference images for high-fidelity, semantically-aware output."},{"name":"Photobook","description":"Produce a series of stylised portrait photos with consistent subject identity across different poses, outfits, or backgrounds."},{"name":"GPT Image","description":"Image generation and editing via OpenAI GPT-4o image capabilities. Excels at precise instruction-following, photorealistic rendering, and multi-step image editing tasks."},{"name":"Image Background Removal"},{"name":"Wan2.6 Image","description":"Generate images with the Wan 2.6 image model using text prompts and configurable output dimensions."},{"name":"Wan2.7 Image","description":"Generate images with the Wan 2.7 image model using text prompts and configurable output dimensions."},{"name":"Qwen Image","description":"Generate and edit images with Qwen Image models using text prompts and optional reference images."},{"name":"Flux 2","description":"High-quality image generation using the Flux 2 Pro model. Delivers strong results for both creative and photorealistic use cases with fast inference."},{"name":"Kling Image","description":"Generate high-fidelity images with Kling using prompt, aspect ratio, resolution, and optional reference-image controls."},{"name":"Image Edit","description":"Edit product images with the product mode. The clothing mode is deprecated; use Virtual Try-On for garment previews. This endpoint does not provide inpainting or outpainting."},{"name":"Image to Video","description":"Convert a still image into an AI-animated video. Control motion intensity, duration, and aspect ratio to produce smooth, high-quality video clips from a single reference image."},{"name":"Wan Image to Video","description":"Animate a still image into a video using the Wan 2.5 / 2.6 open-source video diffusion model family. Part of the Wan series known for fluid motion and temporal consistency."},{"name":"Wan 2.6 R2V Flash","description":"Generate a video from reference images with the fast Wan 2.6 reference-to-video workflow."},{"name":"HappyHorse Video","description":"Asynchronous video generation powered by HappyHorse models on Alibaba DashScope. Supports HappyHorse 1.0 and 1.1 for text-to-video, image-to-video, and reference-to-video; video-edit remains on HappyHorse 1.0. HappyHorse 1.1 generation supports 480P, 720P, or 1080P; 1.0 and video-edit support 720P or 1080P."},{"name":"Talking Photo","description":"Animate a portrait photo to lip-sync with a given audio track, generating a realistic talking-head video from a single still image."},{"name":"Talking Video","description":"Re-lip-sync an existing video to a new audio source using AI-driven facial animation and motion warping."},{"name":"Virtual Try-On","description":"Generate a realistic preview of a person wearing a specific garment from a product image - no physical samples required."},{"name":"ThinkSound","description":"Generate semantically-aware ambient sound effects and background audio that match the visual content of a video clip."},{"name":"Motion Transfer","description":"Transfer body motion captured in a source video onto a target subject, preserving the target's appearance and background."},{"name":"Actor Swap","description":"Replace an actor in a video segment with a different person, retaining original motion, camera angle, and scene continuity."},{"name":"Product Avatar","description":"Generate a product image using a product photo, a person photo, and product_rect placement coordinates. The completed task returns result_image_url."},{"name":"Head Swap","description":"Replace the head in an image with a target face while keeping the original body, clothing, lighting, and background intact."},{"name":"Veo Video","description":"Text-to-video generation powered by Google DeepMind's Veo model. Produces high-definition, cinematic video clips from a text prompt or a reference image."},{"name":"Kling Video","description":"Text-to-video and image-to-video generation with Kling. Recognized for smooth motion dynamics, scene consistency, and high visual fidelity."},{"name":"Kling Omni","description":"An extended variant of Kling with additional control parameters for output style, generation quality, and advanced scene handling."},{"name":"Kling Assets"},{"name":"Grok Video","description":"Video generation using xAI's Grok model. Suitable for creative and coherent video synthesis from descriptive text prompts."},{"name":"Hailuo Video Generation","description":"Generate videos with Hailuo from text prompts or image references with configurable duration and output settings."},{"name":"MiniMax H3 Video Generation"},{"name":"Seedance 1.5 Pro","description":"Generate cinematic videos with Seedance 1.5 Pro from a text prompt, a first-frame image, or first and last frames. Supports configurable duration, aspect ratio, resolution, camera behavior, and audio generation."},{"name":"Seedance 2.x"},{"name":"Wan3.0 Video Generation","description":"Generate Wan 3.0 videos from text, first-frame images, first and last frames, or image, video, and audio references. Query the returned task ID to read its status and result_url."}],"x-tagGroups":[{"name":"Image & Video Generation","tags":["Image to Video","Text to Image","Nano Banana","GPT Image","Flux 2","Qwen Image","Kling Image","Wan2.6 Image","Wan2.7 Image","Wan Image to Video","Wan 2.6 R2V Flash","Wan3.0 Video Generation","HappyHorse Video","Hailuo Video Generation","MiniMax H3 Video Generation","Seedance 1.5 Pro","Seedance 2.x","Veo Video","Grok Video","Kling Video","Kling Omni","Kling Assets","Image Edit"]},{"name":"Face & Body","tags":["Face Swap","Head Swap","Actor Swap","Talking Photo","Talking Video","Virtual Try-On","Motion Transfer","Product Avatar","Photobook"]},{"name":"Avatar & Video","tags":["Generate Avatar Videos","Create Avatars","Background Library","Video Twin"]},{"name":"Voice & Audio","tags":["TTS and Voice Clone","AI Dubbing","ThinkSound"]},{"name":"Post Processing","tags":["Caption Removal","Upscale","Image Background Removal"]},{"name":"Utilities","tags":["Miscellaneous","Share","Credits"]}],"trace_id":"c401d3ab-da7c-49d6-b541-3d99d3b46fc9"}