# HeadSwap Public API Reference

Provides guidance on HeadSwap's public REST APIs for third-party developers and AI agents.

## Authentication
Use `Authorization: Bearer <API_TOKEN>` for all requests.
- Base URL: https://headswap.app
- OpenAPI JSON: https://headswap.app/app/dev/openapi-spec
- Full Documentation: https://headswap.app/app/dev

## AI Quickstart
1. Before asking the user to create an API token, first read `${XDG_CONFIG_HOME:-$HOME/.config}/media-generation/credentials.json` on Unix or `%APPDATA%\media-generation\credentials.json` on Windows. Reuse `access_token` only when the file's `base_url` exactly matches `https://headswap.app`. If no matching saved token exists, ask the user to create one in `Account > API Token`; after they provide it, keep it secret and save `{"base_url":"https://headswap.app","access_token":"<API_TOKEN>","token_type":"Bearer"}` to that same file for future requests.
2. Load the machine-readable OpenAPI spec from `https://headswap.app/app/dev/openapi-spec`.
3. Use the endpoint catalog below to choose the correct media workflow.

## Shared schemas
Resolve local $ref values against these definitions.
```json
{"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}}}}
```
## Operation index
- [POST /api/v1/r2/get_upload_presigned_url](https://headswap.app/app/dev#tag/miscellaneous/POST/api/v1/r2/get_upload_presigned_url)
- [GET /api/v1/share/downloadUrl](https://headswap.app/app/dev#tag/miscellaneous/GET/api/v1/share/downloadUrl)
- [POST /api/v1/r2/upload-presigned-url](https://headswap.app/app/dev#tag/miscellaneous/POST/api/v1/r2/upload-presigned-url)
- [POST /api/v1/generation/quote](https://headswap.app/app/dev#tag/credits/POST/api/v1/generation/quote)
- [POST /api/v1/custom_back/allBackground](https://headswap.app/app/dev#tag/credits/POST/api/v1/custom_back/allBackground)
- [POST /api/v1/custom_back/randomBackground](https://headswap.app/app/dev#tag/credits/POST/api/v1/custom_back/randomBackground)
- [GET /api/v1/userVideoTwin/{_id}](https://headswap.app/app/dev#tag/credits/GET/api/v1/userVideoTwin/%7B_id%7D)
- [POST /api/v1/userVideoTwin/retry](https://headswap.app/app/dev#tag/credits/POST/api/v1/userVideoTwin/retry)
- [GET /api/v1/userDubbing/allProcessing](https://headswap.app/app/dev#tag/credits/GET/api/v1/userDubbing/allProcessing)
- [GET /api/v1/userCaptionRemoval/allProcessing](https://headswap.app/app/dev#tag/credits/GET/api/v1/userCaptionRemoval/allProcessing)
- [GET /api/v1/userUpscale/allProcessing](https://headswap.app/app/dev#tag/credits/GET/api/v1/userUpscale/allProcessing)
- [GET /api/v1/userImage2Video/avgProcessingTime](https://headswap.app/app/dev#tag/credits/GET/api/v1/userImage2Video/avgProcessingTime)
- [GET /api/v1/userImage2Video/unlimitedQueueLevel](https://headswap.app/app/dev#tag/credits/GET/api/v1/userImage2Video/unlimitedQueueLevel)
- [POST /api/v1/userImage2Video/{_id}/markShared](https://headswap.app/app/dev#tag/credits/POST/api/v1/userImage2Video/%7B_id%7D/markShared)
- [POST /api/v1/userImage2Video/{_id}/markDownloaded](https://headswap.app/app/dev#tag/credits/POST/api/v1/userImage2Video/%7B_id%7D/markDownloaded)
- [POST /api/v1/userImage2Video/{_id}/markCopied](https://headswap.app/app/dev#tag/credits/POST/api/v1/userImage2Video/%7B_id%7D/markCopied)
- [GET /api/v1/transactionRecord/creditsHistory](https://headswap.app/app/dev#tag/credits/GET/api/v1/transactionRecord/creditsHistory)
- [POST /api/v1/anchor/list](https://headswap.app/app/dev#tag/generate-avatar-videos/POST/api/v1/anchor/list)
- [POST /api/v1/video/generate](https://headswap.app/app/dev#tag/generate-avatar-videos/POST/api/v1/video/generate)
- [GET /api/v1/video/detail](https://headswap.app/app/dev#tag/generate-avatar-videos/GET/api/v1/video/detail)
- [POST /api/v1/anchor/tts_list](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/anchor/tts_list)
- [POST /api/v1/anchor/language_list](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/anchor/language_list)
- [POST /api/v1/anchor/voice_list](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/anchor/voice_list)
- [GET /api/v1/anchor/voice_list](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/anchor/voice_list)
- [POST /api/v1/video/send_tts](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/video/send_tts)
- [GET /api/v1/tts/preview/list](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/tts/preview/list)
- [DELETE /api/v1/tts/preview/{id}](https://headswap.app/app/dev#tag/tts-and-voice-clone/DELETE/api/v1/tts/preview/%7Bid%7D)
- [POST /api/v1/userVoice/training](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/userVoice/training)
- [GET /api/v1/userVoice/trainingRecord](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/userVoice/trainingRecord)
- [GET /api/v1/userVoice/completedRecord](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/userVoice/completedRecord)
- [DELETE /api/v1/userVoice/{_id}](https://headswap.app/app/dev#tag/tts-and-voice-clone/DELETE/api/v1/userVoice/%7B_id%7D)
- [GET /api/v1/userVoice/{_id}](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/userVoice/%7B_id%7D)
- [PUT /api/v1/userVoice/{_id}](https://headswap.app/app/dev#tag/tts-and-voice-clone/PUT/api/v1/userVoice/%7B_id%7D)
- [GET /api/v1/seedAudio/speakers](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/seedAudio/speakers)
- [POST /api/v1/seedAudio/start](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/seedAudio/start)
- [POST /api/v1/seedAudio/generate](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/seedAudio/generate)
- [GET /api/v1/seedAudio/allRecords](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/seedAudio/allRecords)
- [POST /api/v1/seedAudio/batchDetail](https://headswap.app/app/dev#tag/tts-and-voice-clone/POST/api/v1/seedAudio/batchDetail)
- [GET /api/v1/seedAudio/{_id}](https://headswap.app/app/dev#tag/tts-and-voice-clone/GET/api/v1/seedAudio/%7B_id%7D)
- [DELETE /api/v1/seedAudio/{_id}](https://headswap.app/app/dev#tag/tts-and-voice-clone/DELETE/api/v1/seedAudio/%7B_id%7D)
- [POST /api/v1/custom_avatar/add](https://headswap.app/app/dev#tag/create-avatars/POST/api/v1/custom_avatar/add)
- [POST /api/v1/custom_avatar/list](https://headswap.app/app/dev#tag/create-avatars/POST/api/v1/custom_avatar/list)
- [POST /api/v1/custom_avatar/del](https://headswap.app/app/dev#tag/create-avatars/POST/api/v1/custom_avatar/del)
- [GET /api/v1/custom_avatar/all_tags](https://headswap.app/app/dev#tag/create-avatars/GET/api/v1/custom_avatar/all_tags)
- [PUT /api/v1/custom_avatar/{_id}](https://headswap.app/app/dev#tag/create-avatars/PUT/api/v1/custom_avatar/%7B_id%7D)
- [POST /api/v1/custom_back/add](https://headswap.app/app/dev#tag/background-library/POST/api/v1/custom_back/add)
- [POST /api/v1/custom_back/list](https://headswap.app/app/dev#tag/background-library/POST/api/v1/custom_back/list)
- [POST /api/v1/custom_back/del](https://headswap.app/app/dev#tag/background-library/POST/api/v1/custom_back/del)
- [POST /api/v1/userVideoTwin/upload](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/upload)
- [POST /api/v1/userVideoTwin/training](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/training)
- [GET /api/v1/userVideoTwin/uploadStatus](https://headswap.app/app/dev#tag/video-twin/GET/api/v1/userVideoTwin/uploadStatus)
- [GET /api/v1/userVideoTwin/userRecords](https://headswap.app/app/dev#tag/video-twin/GET/api/v1/userVideoTwin/userRecords)
- [POST /api/v1/userVideoTwin/remove](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/remove)
- [GET /api/v1/userVideoTwin/records](https://headswap.app/app/dev#tag/video-twin/GET/api/v1/userVideoTwin/records)
- [POST /api/v1/userVideoTwin/startTraining](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/startTraining)
- [POST /api/v1/userVideoTwin/continueTraining](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/continueTraining)
- [GET /api/v1/userVideoTwin/trainingRecords](https://headswap.app/app/dev#tag/video-twin/GET/api/v1/userVideoTwin/trainingRecords)
- [POST /api/v1/userVideoTwin/batchDetail](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/batchDetail)
- [POST /api/v1/userVideoTwin/eyeContact](https://headswap.app/app/dev#tag/video-twin/POST/api/v1/userVideoTwin/eyeContact)
- [POST /api/v1/userFaceSwapImage/add](https://headswap.app/app/dev#tag/face-swap/POST/api/v1/userFaceSwapImage/add)
- [GET /api/v1/userFaceSwapImage/records](https://headswap.app/app/dev#tag/face-swap/GET/api/v1/userFaceSwapImage/records)
- [DELETE /api/v1/userFaceSwapImage/{_id}](https://headswap.app/app/dev#tag/face-swap/DELETE/api/v1/userFaceSwapImage/%7B_id%7D)
- [POST /api/v1/userFaceSwapPreview/add](https://headswap.app/app/dev#tag/face-swap/POST/api/v1/userFaceSwapPreview/add)
- [GET /api/v1/userFaceSwapPreview/status](https://headswap.app/app/dev#tag/face-swap/GET/api/v1/userFaceSwapPreview/status)
- [POST /api/v1/userFaceSwapTask/add](https://headswap.app/app/dev#tag/face-swap/POST/api/v1/userFaceSwapTask/add)
- [GET /api/v1/userFaceSwapTask/records](https://headswap.app/app/dev#tag/face-swap/GET/api/v1/userFaceSwapTask/records)
- [GET /api/v1/userFaceSwapTask/status](https://headswap.app/app/dev#tag/face-swap/GET/api/v1/userFaceSwapTask/status)
- [POST /api/v1/userFaceSwapTask/batchDetail](https://headswap.app/app/dev#tag/face-swap/POST/api/v1/userFaceSwapTask/batchDetail)
- [GET /api/v1/userFaceSwapTask/{_id}](https://headswap.app/app/dev#tag/face-swap/GET/api/v1/userFaceSwapTask/%7B_id%7D)
- [DELETE /api/v1/userFaceSwapTask/{_id}](https://headswap.app/app/dev#tag/face-swap/DELETE/api/v1/userFaceSwapTask/%7B_id%7D)
- [POST /api/v1/userDubbing/startDubbing](https://headswap.app/app/dev#tag/ai-dubbing/POST/api/v1/userDubbing/startDubbing)
- [GET /api/v1/userDubbing/allRecords](https://headswap.app/app/dev#tag/ai-dubbing/GET/api/v1/userDubbing/allRecords)
- [GET /api/v1/userDubbing/{_id}](https://headswap.app/app/dev#tag/ai-dubbing/GET/api/v1/userDubbing/%7B_id%7D)
- [DELETE /api/v1/userDubbing/{_id}](https://headswap.app/app/dev#tag/ai-dubbing/DELETE/api/v1/userDubbing/%7B_id%7D)
- [POST /api/v1/userCaptionRemoval/start](https://headswap.app/app/dev#tag/caption-removal/POST/api/v1/userCaptionRemoval/start)
- [GET /api/v1/userCaptionRemoval/allRecords](https://headswap.app/app/dev#tag/caption-removal/GET/api/v1/userCaptionRemoval/allRecords)
- [POST /api/v1/userCaptionRemoval/batchDetail](https://headswap.app/app/dev#tag/caption-removal/POST/api/v1/userCaptionRemoval/batchDetail)
- [GET /api/v1/userCaptionRemoval/{_id}](https://headswap.app/app/dev#tag/caption-removal/GET/api/v1/userCaptionRemoval/%7B_id%7D)
- [DELETE /api/v1/userCaptionRemoval/{_id}](https://headswap.app/app/dev#tag/caption-removal/DELETE/api/v1/userCaptionRemoval/%7B_id%7D)
- [POST /api/v1/userCaptionRemoval/retry](https://headswap.app/app/dev#tag/caption-removal/POST/api/v1/userCaptionRemoval/retry)
- [POST /api/v1/userUpscale/start](https://headswap.app/app/dev#tag/upscale/POST/api/v1/userUpscale/start)
- [GET /api/v1/userUpscale/allRecords](https://headswap.app/app/dev#tag/upscale/GET/api/v1/userUpscale/allRecords)
- [POST /api/v1/userUpscale/batchDetail](https://headswap.app/app/dev#tag/upscale/POST/api/v1/userUpscale/batchDetail)
- [GET /api/v1/userUpscale/{_id}](https://headswap.app/app/dev#tag/upscale/GET/api/v1/userUpscale/%7B_id%7D)
- [DELETE /api/v1/userUpscale/{_id}](https://headswap.app/app/dev#tag/upscale/DELETE/api/v1/userUpscale/%7B_id%7D)
- [POST /api/v1/userUpscale/retry](https://headswap.app/app/dev#tag/upscale/POST/api/v1/userUpscale/retry)
- [POST /api/v1/userText2Image/start](https://headswap.app/app/dev#tag/text-to-image/POST/api/v1/userText2Image/start)
- [GET /api/v1/userText2Image/allRecords](https://headswap.app/app/dev#tag/text-to-image/GET/api/v1/userText2Image/allRecords)
- [POST /api/v1/userText2Image/batchDetail](https://headswap.app/app/dev#tag/text-to-image/POST/api/v1/userText2Image/batchDetail)
- [GET /api/v1/userText2Image/{_id}](https://headswap.app/app/dev#tag/text-to-image/GET/api/v1/userText2Image/%7B_id%7D)
- [DELETE /api/v1/userText2Image/{_id}](https://headswap.app/app/dev#tag/text-to-image/DELETE/api/v1/userText2Image/%7B_id%7D)
- [POST /api/v1/userText2Image/quickAddAvatar](https://headswap.app/app/dev#tag/text-to-image/POST/api/v1/userText2Image/quickAddAvatar)
- [POST /api/v1/userNanoBanana/start](https://headswap.app/app/dev#tag/nano-banana/POST/api/v1/userNanoBanana/start)
- [GET /api/v1/userNanoBanana/allRecords](https://headswap.app/app/dev#tag/nano-banana/GET/api/v1/userNanoBanana/allRecords)
- [POST /api/v1/userNanoBanana/batchDetail](https://headswap.app/app/dev#tag/nano-banana/POST/api/v1/userNanoBanana/batchDetail)
- [GET /api/v1/userNanoBanana/detail/{id}](https://headswap.app/app/dev#tag/nano-banana/GET/api/v1/userNanoBanana/detail/%7Bid%7D)
- [DELETE /api/v1/userNanoBanana/delete/{id}](https://headswap.app/app/dev#tag/nano-banana/DELETE/api/v1/userNanoBanana/delete/%7Bid%7D)
- [POST /api/v1/userPhotobook/start](https://headswap.app/app/dev#tag/photobook/POST/api/v1/userPhotobook/start)
- [GET /api/v1/userPhotobook/allRecords](https://headswap.app/app/dev#tag/photobook/GET/api/v1/userPhotobook/allRecords)
- [POST /api/v1/userPhotobook/batchDetail](https://headswap.app/app/dev#tag/photobook/POST/api/v1/userPhotobook/batchDetail)
- [GET /api/v1/userPhotobook/{id}](https://headswap.app/app/dev#tag/photobook/GET/api/v1/userPhotobook/%7Bid%7D)
- [DELETE /api/v1/userPhotobook/{id}](https://headswap.app/app/dev#tag/photobook/DELETE/api/v1/userPhotobook/%7Bid%7D)
- [POST /api/v1/userGptImage/start](https://headswap.app/app/dev#tag/gpt-image/POST/api/v1/userGptImage/start)
- [GET /api/v1/userGptImage/list](https://headswap.app/app/dev#tag/gpt-image/GET/api/v1/userGptImage/list)
- [POST /api/v1/userGptImage/batchDetail](https://headswap.app/app/dev#tag/gpt-image/POST/api/v1/userGptImage/batchDetail)
- [GET /api/v1/userGptImage/detail/{id}](https://headswap.app/app/dev#tag/gpt-image/GET/api/v1/userGptImage/detail/%7Bid%7D)
- [DELETE /api/v1/userGptImage/{id}](https://headswap.app/app/dev#tag/gpt-image/DELETE/api/v1/userGptImage/%7Bid%7D)
- [POST /api/v1/imageBackgroundRemoval/start](https://headswap.app/app/dev#tag/image-background-removal/POST/api/v1/imageBackgroundRemoval/start)
- [POST /api/v1/userWan26Image/start](https://headswap.app/app/dev#tag/wan26-image/POST/api/v1/userWan26Image/start)
- [GET /api/v1/userWan26Image/list](https://headswap.app/app/dev#tag/wan26-image/GET/api/v1/userWan26Image/list)
- [GET /api/v1/userWan26Image/detail/{id}](https://headswap.app/app/dev#tag/wan26-image/GET/api/v1/userWan26Image/detail/%7Bid%7D)
- [POST /api/v1/userWan26Image/batchDetail](https://headswap.app/app/dev#tag/wan26-image/POST/api/v1/userWan26Image/batchDetail)
- [DELETE /api/v1/userWan26Image/{id}](https://headswap.app/app/dev#tag/wan26-image/DELETE/api/v1/userWan26Image/%7Bid%7D)
- [POST /api/v1/userWan27Image/start](https://headswap.app/app/dev#tag/wan27-image/POST/api/v1/userWan27Image/start)
- [GET /api/v1/userWan27Image/list](https://headswap.app/app/dev#tag/wan27-image/GET/api/v1/userWan27Image/list)
- [GET /api/v1/userWan27Image/detail/{id}](https://headswap.app/app/dev#tag/wan27-image/GET/api/v1/userWan27Image/detail/%7Bid%7D)
- [POST /api/v1/userWan27Image/batchDetail](https://headswap.app/app/dev#tag/wan27-image/POST/api/v1/userWan27Image/batchDetail)
- [DELETE /api/v1/userWan27Image/{id}](https://headswap.app/app/dev#tag/wan27-image/DELETE/api/v1/userWan27Image/%7Bid%7D)
- [POST /api/v1/userQwen2Image/start](https://headswap.app/app/dev#tag/qwen-image/POST/api/v1/userQwen2Image/start)
- [GET /api/v1/userQwen2Image/list](https://headswap.app/app/dev#tag/qwen-image/GET/api/v1/userQwen2Image/list)
- [GET /api/v1/userQwen2Image/detail/{id}](https://headswap.app/app/dev#tag/qwen-image/GET/api/v1/userQwen2Image/detail/%7Bid%7D)
- [POST /api/v1/userQwen2Image/batchDetail](https://headswap.app/app/dev#tag/qwen-image/POST/api/v1/userQwen2Image/batchDetail)
- [DELETE /api/v1/userQwen2Image/{id}](https://headswap.app/app/dev#tag/qwen-image/DELETE/api/v1/userQwen2Image/%7Bid%7D)
- [POST /api/v1/userFlux2/start](https://headswap.app/app/dev#tag/flux-2/POST/api/v1/userFlux2/start)
- [GET /api/v1/userFlux2/list](https://headswap.app/app/dev#tag/flux-2/GET/api/v1/userFlux2/list)
- [POST /api/v1/userFlux2/batchDetail](https://headswap.app/app/dev#tag/flux-2/POST/api/v1/userFlux2/batchDetail)
- [GET /api/v1/userFlux2/detail/{id}](https://headswap.app/app/dev#tag/flux-2/GET/api/v1/userFlux2/detail/%7Bid%7D)
- [DELETE /api/v1/userFlux2/{id}](https://headswap.app/app/dev#tag/flux-2/DELETE/api/v1/userFlux2/%7Bid%7D)
- [POST /api/v1/userKlingImage/start](https://headswap.app/app/dev#tag/kling-image/POST/api/v1/userKlingImage/start)
- [GET /api/v1/userKlingImage/list](https://headswap.app/app/dev#tag/kling-image/GET/api/v1/userKlingImage/list)
- [POST /api/v1/userKlingImage/batchDetail](https://headswap.app/app/dev#tag/kling-image/POST/api/v1/userKlingImage/batchDetail)
- [GET /api/v1/userKlingImage/detail/{id}](https://headswap.app/app/dev#tag/kling-image/GET/api/v1/userKlingImage/detail/%7Bid%7D)
- [DELETE /api/v1/userKlingImage/{id}](https://headswap.app/app/dev#tag/kling-image/DELETE/api/v1/userKlingImage/%7Bid%7D)
- [POST /api/v1/userImageEdit/start](https://headswap.app/app/dev#tag/image-edit/POST/api/v1/userImageEdit/start)
- [GET /api/v1/userImageEdit/allRecords](https://headswap.app/app/dev#tag/image-edit/GET/api/v1/userImageEdit/allRecords)
- [POST /api/v1/userImageEdit/batchDetail](https://headswap.app/app/dev#tag/image-edit/POST/api/v1/userImageEdit/batchDetail)
- [GET /api/v1/userImageEdit/{_id}](https://headswap.app/app/dev#tag/image-edit/GET/api/v1/userImageEdit/%7B_id%7D)
- [DELETE /api/v1/userImageEdit/{_id}](https://headswap.app/app/dev#tag/image-edit/DELETE/api/v1/userImageEdit/%7B_id%7D)
- [POST /api/v1/userImage2Video/start](https://headswap.app/app/dev#tag/image-to-video/POST/api/v1/userImage2Video/start)
- [GET /api/v1/userImage2Video/allRecords](https://headswap.app/app/dev#tag/image-to-video/GET/api/v1/userImage2Video/allRecords)
- [POST /api/v1/userImage2Video/batchDetail](https://headswap.app/app/dev#tag/image-to-video/POST/api/v1/userImage2Video/batchDetail)
- [GET /api/v1/userImage2Video/{_id}](https://headswap.app/app/dev#tag/image-to-video/GET/api/v1/userImage2Video/%7B_id%7D)
- [DELETE /api/v1/userImage2Video/{_id}](https://headswap.app/app/dev#tag/image-to-video/DELETE/api/v1/userImage2Video/%7B_id%7D)
- [POST /api/v1/userImage2Video/prompt_extension](https://headswap.app/app/dev#tag/image-to-video/POST/api/v1/userImage2Video/prompt_extension)
- [POST /api/v1/userImage2Video/flf2v_prompt_extension](https://headswap.app/app/dev#tag/image-to-video/POST/api/v1/userImage2Video/flf2v_prompt_extension)
- [POST /api/v1/userWan25/start](https://headswap.app/app/dev#tag/wan-image-to-video/POST/api/v1/userWan25/start)
- [GET /api/v1/userWan25/allRecords](https://headswap.app/app/dev#tag/wan-image-to-video/GET/api/v1/userWan25/allRecords)
- [POST /api/v1/userWan25/batchDetail](https://headswap.app/app/dev#tag/wan-image-to-video/POST/api/v1/userWan25/batchDetail)
- [GET /api/v1/userWan25/{_id}](https://headswap.app/app/dev#tag/wan-image-to-video/GET/api/v1/userWan25/%7B_id%7D)
- [DELETE /api/v1/userWan25/{_id}](https://headswap.app/app/dev#tag/wan-image-to-video/DELETE/api/v1/userWan25/%7B_id%7D)
- [POST /api/v1/userWanSpicy/start](https://headswap.app/app/dev#tag/wan-image-to-video/POST/api/v1/userWanSpicy/start)
- [GET /api/v1/userWanSpicy/allRecords](https://headswap.app/app/dev#tag/wan-image-to-video/GET/api/v1/userWanSpicy/allRecords)
- [POST /api/v1/userWanSpicy/batchDetail](https://headswap.app/app/dev#tag/wan-image-to-video/POST/api/v1/userWanSpicy/batchDetail)
- [GET /api/v1/userWanSpicy/{_id}](https://headswap.app/app/dev#tag/wan-image-to-video/GET/api/v1/userWanSpicy/%7B_id%7D)
- [DELETE /api/v1/userWanSpicy/{_id}](https://headswap.app/app/dev#tag/wan-image-to-video/DELETE/api/v1/userWanSpicy/%7B_id%7D)
- [POST /api/v1/userWan26R2V/start](https://headswap.app/app/dev#tag/wan-26-r2v-flash/POST/api/v1/userWan26R2V/start)
- [GET /api/v1/userWan26R2V/allRecords](https://headswap.app/app/dev#tag/wan-26-r2v-flash/GET/api/v1/userWan26R2V/allRecords)
- [POST /api/v1/userWan26R2V/batchDetail](https://headswap.app/app/dev#tag/wan-26-r2v-flash/POST/api/v1/userWan26R2V/batchDetail)
- [GET /api/v1/userWan26R2V/{_id}](https://headswap.app/app/dev#tag/wan-26-r2v-flash/GET/api/v1/userWan26R2V/%7B_id%7D)
- [DELETE /api/v1/userWan26R2V/{_id}](https://headswap.app/app/dev#tag/wan-26-r2v-flash/DELETE/api/v1/userWan26R2V/%7B_id%7D)
- [POST /api/v1/userHappyhorseVideo/start](https://headswap.app/app/dev#tag/happyhorse-video/POST/api/v1/userHappyhorseVideo/start)
- [GET /api/v1/userHappyhorseVideo/allRecords](https://headswap.app/app/dev#tag/happyhorse-video/GET/api/v1/userHappyhorseVideo/allRecords)
- [POST /api/v1/userHappyhorseVideo/batchDetail](https://headswap.app/app/dev#tag/happyhorse-video/POST/api/v1/userHappyhorseVideo/batchDetail)
- [GET /api/v1/userHappyhorseVideo/{_id}](https://headswap.app/app/dev#tag/happyhorse-video/GET/api/v1/userHappyhorseVideo/%7B_id%7D)
- [DELETE /api/v1/userHappyhorseVideo/{_id}](https://headswap.app/app/dev#tag/happyhorse-video/DELETE/api/v1/userHappyhorseVideo/%7B_id%7D)
- [POST /api/v1/talkingPhoto/start](https://headswap.app/app/dev#tag/talking-photo/POST/api/v1/talkingPhoto/start)
- [GET /api/v1/talkingPhoto/allRecords](https://headswap.app/app/dev#tag/talking-photo/GET/api/v1/talkingPhoto/allRecords)
- [POST /api/v1/talkingPhoto/batchDetail](https://headswap.app/app/dev#tag/talking-photo/POST/api/v1/talkingPhoto/batchDetail)
- [GET /api/v1/talkingPhoto/{_id}](https://headswap.app/app/dev#tag/talking-photo/GET/api/v1/talkingPhoto/%7B_id%7D)
- [DELETE /api/v1/talkingPhoto/{_id}](https://headswap.app/app/dev#tag/talking-photo/DELETE/api/v1/talkingPhoto/%7B_id%7D)
- [POST /api/v1/talkingVideo/start](https://headswap.app/app/dev#tag/talking-video/POST/api/v1/talkingVideo/start)
- [GET /api/v1/talkingVideo/allRecords](https://headswap.app/app/dev#tag/talking-video/GET/api/v1/talkingVideo/allRecords)
- [POST /api/v1/talkingVideo/batchDetail](https://headswap.app/app/dev#tag/talking-video/POST/api/v1/talkingVideo/batchDetail)
- [GET /api/v1/talkingVideo/{_id}](https://headswap.app/app/dev#tag/talking-video/GET/api/v1/talkingVideo/%7B_id%7D)
- [DELETE /api/v1/talkingVideo/{_id}](https://headswap.app/app/dev#tag/talking-video/DELETE/api/v1/talkingVideo/%7B_id%7D)
- [POST /api/v1/virtualTryOn/start](https://headswap.app/app/dev#tag/virtual-try-on/POST/api/v1/virtualTryOn/start)
- [GET /api/v1/virtualTryOn/allRecords](https://headswap.app/app/dev#tag/virtual-try-on/GET/api/v1/virtualTryOn/allRecords)
- [POST /api/v1/virtualTryOn/batchDetail](https://headswap.app/app/dev#tag/virtual-try-on/POST/api/v1/virtualTryOn/batchDetail)
- [GET /api/v1/virtualTryOn/{_id}](https://headswap.app/app/dev#tag/virtual-try-on/GET/api/v1/virtualTryOn/%7B_id%7D)
- [DELETE /api/v1/virtualTryOn/{_id}](https://headswap.app/app/dev#tag/virtual-try-on/DELETE/api/v1/virtualTryOn/%7B_id%7D)
- [POST /api/v1/thinkSound/start](https://headswap.app/app/dev#tag/thinksound/POST/api/v1/thinkSound/start)
- [DELETE /api/v1/thinkSound/{_id}](https://headswap.app/app/dev#tag/thinksound/DELETE/api/v1/thinkSound/%7B_id%7D)
- [GET /api/v1/thinkSound/{_id}](https://headswap.app/app/dev#tag/thinksound/GET/api/v1/thinkSound/%7B_id%7D)
- [GET /api/v1/thinkSound/allRecords](https://headswap.app/app/dev#tag/thinksound/GET/api/v1/thinkSound/allRecords)
- [POST /api/v1/thinkSound/batchDetail](https://headswap.app/app/dev#tag/thinksound/POST/api/v1/thinkSound/batchDetail)
- [POST /api/v1/motionTransfer/start](https://headswap.app/app/dev#tag/motion-transfer/POST/api/v1/motionTransfer/start)
- [GET /api/v1/motionTransfer/allRecords](https://headswap.app/app/dev#tag/motion-transfer/GET/api/v1/motionTransfer/allRecords)
- [POST /api/v1/motionTransfer/batchDetail](https://headswap.app/app/dev#tag/motion-transfer/POST/api/v1/motionTransfer/batchDetail)
- [GET /api/v1/motionTransfer/{_id}](https://headswap.app/app/dev#tag/motion-transfer/GET/api/v1/motionTransfer/%7B_id%7D)
- [DELETE /api/v1/motionTransfer/{_id}](https://headswap.app/app/dev#tag/motion-transfer/DELETE/api/v1/motionTransfer/%7B_id%7D)
- [POST /api/v1/actorSwap/start](https://headswap.app/app/dev#tag/actor-swap/POST/api/v1/actorSwap/start)
- [GET /api/v1/actorSwap/allRecords](https://headswap.app/app/dev#tag/actor-swap/GET/api/v1/actorSwap/allRecords)
- [POST /api/v1/actorSwap/batchDetail](https://headswap.app/app/dev#tag/actor-swap/POST/api/v1/actorSwap/batchDetail)
- [GET /api/v1/actorSwap/{_id}](https://headswap.app/app/dev#tag/actor-swap/GET/api/v1/actorSwap/%7B_id%7D)
- [DELETE /api/v1/actorSwap/{_id}](https://headswap.app/app/dev#tag/actor-swap/DELETE/api/v1/actorSwap/%7B_id%7D)
- [POST /api/v1/productAvatar/start](https://headswap.app/app/dev#tag/product-avatar/POST/api/v1/productAvatar/start)
- [GET /api/v1/productAvatar/allRecords](https://headswap.app/app/dev#tag/product-avatar/GET/api/v1/productAvatar/allRecords)
- [POST /api/v1/productAvatar/batchDetail](https://headswap.app/app/dev#tag/product-avatar/POST/api/v1/productAvatar/batchDetail)
- [GET /api/v1/productAvatar/{_id}](https://headswap.app/app/dev#tag/product-avatar/GET/api/v1/productAvatar/%7B_id%7D)
- [DELETE /api/v1/productAvatar/{_id}](https://headswap.app/app/dev#tag/product-avatar/DELETE/api/v1/productAvatar/%7B_id%7D)
- [POST /api/v1/headSwap/start](https://headswap.app/app/dev#tag/head-swap/POST/api/v1/headSwap/start)
- [GET /api/v1/headSwap/allRecords](https://headswap.app/app/dev#tag/head-swap/GET/api/v1/headSwap/allRecords)
- [POST /api/v1/headSwap/batchDetail](https://headswap.app/app/dev#tag/head-swap/POST/api/v1/headSwap/batchDetail)
- [GET /api/v1/headSwap/{_id}](https://headswap.app/app/dev#tag/head-swap/GET/api/v1/headSwap/%7B_id%7D)
- [DELETE /api/v1/headSwap/{_id}](https://headswap.app/app/dev#tag/head-swap/DELETE/api/v1/headSwap/%7B_id%7D)
- [POST /api/v1/veoVideo/start](https://headswap.app/app/dev#tag/veo-video/POST/api/v1/veoVideo/start)
- [GET /api/v1/veoVideo/allRecords](https://headswap.app/app/dev#tag/veo-video/GET/api/v1/veoVideo/allRecords)
- [POST /api/v1/veoVideo/batchDetail](https://headswap.app/app/dev#tag/veo-video/POST/api/v1/veoVideo/batchDetail)
- [GET /api/v1/veoVideo/{_id}](https://headswap.app/app/dev#tag/veo-video/GET/api/v1/veoVideo/%7B_id%7D)
- [DELETE /api/v1/veoVideo/{_id}](https://headswap.app/app/dev#tag/veo-video/DELETE/api/v1/veoVideo/%7B_id%7D)
- [GET /api/v1/veoVideo/{_id}/1080p](https://headswap.app/app/dev#tag/veo-video/GET/api/v1/veoVideo/%7B_id%7D/1080p)
- [POST /api/v1/klingVideo/start](https://headswap.app/app/dev#tag/kling-video/POST/api/v1/klingVideo/start)
- [GET /api/v1/klingVideo/allRecords](https://headswap.app/app/dev#tag/kling-video/GET/api/v1/klingVideo/allRecords)
- [POST /api/v1/klingVideo/batchDetail](https://headswap.app/app/dev#tag/kling-video/POST/api/v1/klingVideo/batchDetail)
- [GET /api/v1/klingVideo/{_id}](https://headswap.app/app/dev#tag/kling-video/GET/api/v1/klingVideo/%7B_id%7D)
- [PUT /api/v1/klingVideo/{_id}](https://headswap.app/app/dev#tag/kling-video/PUT/api/v1/klingVideo/%7B_id%7D)
- [DELETE /api/v1/klingVideo/{_id}](https://headswap.app/app/dev#tag/kling-video/DELETE/api/v1/klingVideo/%7B_id%7D)
- [POST /api/v1/klingOmni/start](https://headswap.app/app/dev#tag/kling-omni/POST/api/v1/klingOmni/start)
- [GET /api/v1/klingOmni/allRecords](https://headswap.app/app/dev#tag/kling-omni/GET/api/v1/klingOmni/allRecords)
- [POST /api/v1/klingOmni/batchDetail](https://headswap.app/app/dev#tag/kling-omni/POST/api/v1/klingOmni/batchDetail)
- [GET /api/v1/klingOmni/{_id}](https://headswap.app/app/dev#tag/kling-omni/GET/api/v1/klingOmni/%7B_id%7D)
- [PUT /api/v1/klingOmni/{_id}](https://headswap.app/app/dev#tag/kling-omni/PUT/api/v1/klingOmni/%7B_id%7D)
- [DELETE /api/v1/klingOmni/{_id}](https://headswap.app/app/dev#tag/kling-omni/DELETE/api/v1/klingOmni/%7B_id%7D)
- [GET /api/v1/klingAssets](https://headswap.app/app/dev#tag/kling-assets/GET/api/v1/klingAssets)
- [POST /api/v1/klingAssets/voices](https://headswap.app/app/dev#tag/kling-assets/POST/api/v1/klingAssets/voices)
- [POST /api/v1/klingAssets/elements](https://headswap.app/app/dev#tag/kling-assets/POST/api/v1/klingAssets/elements)
- [DELETE /api/v1/klingAssets/{id}](https://headswap.app/app/dev#tag/kling-assets/DELETE/api/v1/klingAssets/%7Bid%7D)
- [POST /api/v1/grokVideo/start](https://headswap.app/app/dev#tag/grok-video/POST/api/v1/grokVideo/start)
- [GET /api/v1/grokVideo/allRecords](https://headswap.app/app/dev#tag/grok-video/GET/api/v1/grokVideo/allRecords)
- [POST /api/v1/grokVideo/batchDetail](https://headswap.app/app/dev#tag/grok-video/POST/api/v1/grokVideo/batchDetail)
- [GET /api/v1/grokVideo/{_id}](https://headswap.app/app/dev#tag/grok-video/GET/api/v1/grokVideo/%7B_id%7D)
- [DELETE /api/v1/grokVideo/{_id}](https://headswap.app/app/dev#tag/grok-video/DELETE/api/v1/grokVideo/%7B_id%7D)
- [POST /api/v1/hailuoVideo/start](https://headswap.app/app/dev#tag/hailuo-video-generation/POST/api/v1/hailuoVideo/start)
- [GET /api/v1/hailuoVideo/allRecords](https://headswap.app/app/dev#tag/hailuo-video-generation/GET/api/v1/hailuoVideo/allRecords)
- [POST /api/v1/hailuoVideo/batchDetail](https://headswap.app/app/dev#tag/hailuo-video-generation/POST/api/v1/hailuoVideo/batchDetail)
- [GET /api/v1/hailuoVideo/{_id}](https://headswap.app/app/dev#tag/hailuo-video-generation/GET/api/v1/hailuoVideo/%7B_id%7D)
- [DELETE /api/v1/hailuoVideo/{_id}](https://headswap.app/app/dev#tag/hailuo-video-generation/DELETE/api/v1/hailuoVideo/%7B_id%7D)
- [POST /api/v1/minimaxH3Video/start](https://headswap.app/app/dev#tag/minimax-h3-video-generation/POST/api/v1/minimaxH3Video/start)
- [GET /api/v1/minimaxH3Video/allRecords](https://headswap.app/app/dev#tag/minimax-h3-video-generation/GET/api/v1/minimaxH3Video/allRecords)
- [POST /api/v1/minimaxH3Video/batchDetail](https://headswap.app/app/dev#tag/minimax-h3-video-generation/POST/api/v1/minimaxH3Video/batchDetail)
- [GET /api/v1/minimaxH3Video/{_id}](https://headswap.app/app/dev#tag/minimax-h3-video-generation/GET/api/v1/minimaxH3Video/%7B_id%7D)
- [DELETE /api/v1/minimaxH3Video/{_id}](https://headswap.app/app/dev#tag/minimax-h3-video-generation/DELETE/api/v1/minimaxH3Video/%7B_id%7D)
- [POST /api/v1/seedanceVideo/start](https://headswap.app/app/dev#tag/seedance-15-pro/POST/api/v1/seedanceVideo/start)
- [GET /api/v1/seedanceVideo/allRecords](https://headswap.app/app/dev#tag/seedance-15-pro/GET/api/v1/seedanceVideo/allRecords)
- [POST /api/v1/seedanceVideo/batchDetail](https://headswap.app/app/dev#tag/seedance-15-pro/POST/api/v1/seedanceVideo/batchDetail)
- [GET /api/v1/seedanceVideo/{_id}](https://headswap.app/app/dev#tag/seedance-15-pro/GET/api/v1/seedanceVideo/%7B_id%7D)
- [PUT /api/v1/seedanceVideo/{_id}](https://headswap.app/app/dev#tag/seedance-15-pro/PUT/api/v1/seedanceVideo/%7B_id%7D)
- [DELETE /api/v1/seedanceVideo/{_id}](https://headswap.app/app/dev#tag/seedance-15-pro/DELETE/api/v1/seedanceVideo/%7B_id%7D)
- [POST /api/v1/seedance2Video/start](https://headswap.app/app/dev#tag/seedance-2x/POST/api/v1/seedance2Video/start)
- [GET /api/v1/seedance2Video/allRecords](https://headswap.app/app/dev#tag/seedance-2x/GET/api/v1/seedance2Video/allRecords)
- [POST /api/v1/seedance2Video/batchDetail](https://headswap.app/app/dev#tag/seedance-2x/POST/api/v1/seedance2Video/batchDetail)
- [GET /api/v1/seedance2Video/{_id}](https://headswap.app/app/dev#tag/seedance-2x/GET/api/v1/seedance2Video/%7B_id%7D)
- [PUT /api/v1/seedance2Video/{_id}](https://headswap.app/app/dev#tag/seedance-2x/PUT/api/v1/seedance2Video/%7B_id%7D)
- [DELETE /api/v1/seedance2Video/{_id}](https://headswap.app/app/dev#tag/seedance-2x/DELETE/api/v1/seedance2Video/%7B_id%7D)
- [POST /api/v1/userWan30/start](https://headswap.app/app/dev#tag/wan30-video-generation/POST/api/v1/userWan30/start)
- [GET /api/v1/userWan30/allRecords](https://headswap.app/app/dev#tag/wan30-video-generation/GET/api/v1/userWan30/allRecords)
- [POST /api/v1/userWan30/batchDetail](https://headswap.app/app/dev#tag/wan30-video-generation/POST/api/v1/userWan30/batchDetail)
- [GET /api/v1/userWan30/{_id}](https://headswap.app/app/dev#tag/wan30-video-generation/GET/api/v1/userWan30/%7B_id%7D)
- [DELETE /api/v1/userWan30/{_id}](https://headswap.app/app/dev#tag/wan30-video-generation/DELETE/api/v1/userWan30/%7B_id%7D)
## Minimal integration workflow
Upload using the published R2 PUT contract, then use the returned cdnUrl as the generation input. Quote the exact generation body; available=false/coins=null is not free. Submit only after checking price and access, retain the model-specific task ID, and poll its documented detail endpoint until completed/failed. Save the documented result URL before expiration. A moderation response may have no task ID; do not poll it. A quote does not reserve credits or prove entitlement.
## API Catalog

### Image & Video Generation
#### Image to Video

##### POST /api/v1/userImage2Video/start — Start image to video conversion
Convert an image to video using AI generation with custom prompts. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userImage2Video/allRecords` — List image to video tasks. - `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail. - `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
}
JSON
```
- Responses:
  - `200` — Image to video task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userImage2Video/allRecords — List image to video tasks
List current user's image to video tasks (only non-expired records will be returned). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail. - `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task. - `POST /api/v1/userImage2Video/start` — Start image to video conversion. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userImage2Video/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImage2Video/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userImage2Video/allRecords` — List image to video tasks. - `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail. - `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userImage2Video/{_id} — Get image to video task detail
Get one image to video task detail by id. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Not Found - Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userImage2Video/allRecords` — List image to video tasks. - `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task. - `POST /api/v1/userImage2Video/start` — Start image to video conversion. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Not Found - Task not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userImage2Video/{_id} — Delete an image to video task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userImage2Video/allRecords` — List image to video tasks. - `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail. - `POST /api/v1/userImage2Video/start` — Start image to video conversion. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserImage2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImage2Video/prompt_extension — Extend prompt for image to video
Extend a prompt for general image-to-video with LLM. Choose JSON (default) or SSE by setting stream: true or Accept: text/event-stream. SSE responses have Content-Type: text/event-stream; charset=utf-8 and HTTP 200. Every frame is data: <JSON> followed by two newlines. There are no SSE event: or id: lines; dispatch on the JSON type field. Zero or more delta events contain text: the entire current visible preview, not a token to append. Replace the preview with each snapshot. Success sends result with data.prompt (English for generation) and data.prompt_localized (lang for display), then done, then closes. Failure 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. Validation/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. Client 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. cURL streaming example (replace token and accessible image URL; FLF2V also requires end_image_url): ```sh curl -N -X POST "https://video.a2e.ai/api/v1/userImage2Video/prompt_extension" \ -H 'Authorization: Bearer YOUR_A2E_API_KEY' \ -H 'Content-Type: application/json' -H 'Accept: text/event-stream' \ --data '{"reference_id": "client-request", "image_url": "https://example.invalid/start.png", "prompt": "A moving camera", "negative_prompt": "", "lang": "en", "stream": true}' ``` Minimal POST response parser (UTF-8 chunks and SSE frame boundaries can split arbitrarily): ```js async function readPromptExtension(response, onPreview = () => {}) { if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); if (!response.headers.get('content-type')?.includes('text/event-stream')) return (await response.json()).data; const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = '', result; try { while (true) { const chunk = await reader.read(); buffer += decoder.decode(chunk.value, { stream: !chunk.done }); let boundary; while ((boundary = /\r?\n\r?\n/.exec(buffer))) { const block = buffer.slice(0, boundary.index); buffer = buffer.slice(boundary.index + boundary[0].length); const data = block.split(/\r?\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n'); if (!data) continue; const event = JSON.parse(data); if (event.type === 'delta') onPreview(event.text); if (event.type === 'result') result = event.data; if (event.type === 'error') throw Object.assign(new Error(event.message), { code: event.code, trace_id: event.trace_id }); if (event.type === 'done') { if (!result) throw new Error('Missing result before done'); return result; } } if (chunk.done) throw new Error('Stream ended before done'); } } finally { await reader.cancel(); } } ``` Call 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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `reference_id`, `image_url`, `prompt`, `negative_prompt`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `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. - `500` — JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200. ### Related Operations - `GET /api/v1/userImage2Video/allRecords` — List image to video tasks. - `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail. - `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.
- Operation ID: `postApiV1UserImage2VideoPromptExtension`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/prompt_extension" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "reference_id": "507f1f77bcf86cd799439011",
  "image_url": "https://example.com/image.jpg",
  "prompt": "high quality, clear, cinematic",
  "negative_prompt": "blurry, low quality, watermark, distorted"
}
JSON
```
- Responses:
  - `200` — JSON prompt result or SSE stream; a stream error can occur after HTTP 200.
```json
{"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."}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `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.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `500` — JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImage2Video/flf2v_prompt_extension — Extend prompt for FLF2V image to video
Extend an FLF2V prompt with LLM; end_image_url is required. Choose JSON (default) or SSE by setting stream: true or Accept: text/event-stream. SSE responses have Content-Type: text/event-stream; charset=utf-8 and HTTP 200. Every frame is data: <JSON> followed by two newlines. There are no SSE event: or id: lines; dispatch on the JSON type field. Zero or more delta events contain text: the entire current visible preview, not a token to append. Replace the preview with each snapshot. Success sends result with data.prompt (English for generation) and data.prompt_localized (lang for display), then done, then closes. Failure 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. Validation/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. Client 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. cURL streaming example (replace token and accessible image URL; FLF2V also requires end_image_url): ```sh curl -N -X POST "https://video.a2e.ai/api/v1/userImage2Video/flf2v_prompt_extension" \ -H 'Authorization: Bearer YOUR_A2E_API_KEY' \ -H 'Content-Type: application/json' -H 'Accept: text/event-stream' \ --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"}' ``` Minimal POST response parser (UTF-8 chunks and SSE frame boundaries can split arbitrarily): ```js async function readPromptExtension(response, onPreview = () => {}) { if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); if (!response.headers.get('content-type')?.includes('text/event-stream')) return (await response.json()).data; const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = '', result; try { while (true) { const chunk = await reader.read(); buffer += decoder.decode(chunk.value, { stream: !chunk.done }); let boundary; while ((boundary = /\r?\n\r?\n/.exec(buffer))) { const block = buffer.slice(0, boundary.index); buffer = buffer.slice(boundary.index + boundary[0].length); const data = block.split(/\r?\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n'); if (!data) continue; const event = JSON.parse(data); if (event.type === 'delta') onPreview(event.text); if (event.type === 'result') result = event.data; if (event.type === 'error') throw Object.assign(new Error(event.message), { code: event.code, trace_id: event.trace_id }); if (event.type === 'done') { if (!result) throw new Error('Missing result before done'); return result; } } if (chunk.done) throw new Error('Stream ended before done'); } } finally { await reader.cancel(); } } ``` Call 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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `reference_id`, `image_url`, `end_image_url`, `prompt`, `negative_prompt`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `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. - `500` — JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200. ### Related Operations - `GET /api/v1/userImage2Video/allRecords` — List image to video tasks. - `GET /api/v1/userImage2Video/{_id}` — Get image to video task detail. - `DELETE /api/v1/userImage2Video/{_id}` — Delete an image to video task.
- Operation ID: `postApiV1UserImage2VideoFlf2vPromptExtension`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/flf2v_prompt_extension" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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"
}
JSON
```
- Responses:
  - `200` — JSON prompt result or SSE stream; a stream error can occur after HTTP 200.
```json
{"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."}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `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.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `500` — JSON mode - Prompt extension infrastructure failure. In SSE mode this is a terminal error data frame under HTTP 200.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Text to Image

##### POST /api/v1/userText2Image/start — Start text to image generation
Create one or more asynchronous text-to-image tasks, then return the records used to monitor generated images. Select the image model with `model_type`: - `a2e`: auto-select the default image model. It supports text-to-image and image editing with up to two reference images. - `zimage`: Z-Image Turbo for text-to-image generation. It does not accept reference images. - `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. API 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`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userText2Image/allRecords` — Get all text to image records. - `GET /api/v1/userText2Image/{_id}` — Get text to image record detail. - `DELETE /api/v1/userText2Image/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserText2ImageStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userText2Image/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "A beautiful sunset over mountains"
}
JSON
```
- Responses:
  - `200` — Text to image task started successfully
```json
{"$ref":"#/components/schemas/Text2ImageStartResponse"}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userText2Image/allRecords — Get all text to image records
Retrieve paginated list of all text to image generation records for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userText2Image/{_id}` — Get text to image record detail. - `DELETE /api/v1/userText2Image/{_id}` — Delete task. - `POST /api/v1/userText2Image/start` — Start text to image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserText2ImageAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userText2Image/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userText2Image/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userText2Image/allRecords` — Get all text to image records. - `GET /api/v1/userText2Image/{_id}` — Get text to image record detail. - `DELETE /api/v1/userText2Image/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserText2ImageBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userText2Image/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userText2Image/{_id} — Get text to image record detail
Retrieve detailed information of a specific text to image generation record. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `404` — Record not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userText2Image/allRecords` — Get all text to image records. - `DELETE /api/v1/userText2Image/{_id}` — Delete task. - `POST /api/v1/userText2Image/start` — Start text to image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserText2ImageId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Record ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userText2Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `404` — Record not found
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userText2Image/{_id} — Delete task
Remove the authenticated user's text-to-image task identified by `_id` from the task history without affecting other generated-image records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userText2Image/allRecords` — Get all text to image records. - `GET /api/v1/userText2Image/{_id}` — Get text to image record detail. - `POST /api/v1/userText2Image/start` — Start text to image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserText2ImageId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userText2Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userText2Image/quickAddAvatar — Quick add avatar from generated image
Create a custom avatar directly from a text to image generation result. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `_id`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad request. - `401` — Unauthorized. ### Related Operations - `GET /api/v1/userText2Image/allRecords` — Get all text to image records. - `GET /api/v1/userText2Image/{_id}` — Get text to image record detail. - `DELETE /api/v1/userText2Image/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserText2ImageQuickAddAvatar`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userText2Image/quickAddAvatar" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Avatar created successfully
```json
{"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"}}}
```
  - `400` — Bad request
  - `401` — Unauthorized
#### Nano Banana

##### POST /api/v1/userNanoBanana/start — Start Nano Banana image generation
Generate images using Nano Banana models with advanced conversational capabilities and NSFW content pre-filtering. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list. - `GET /api/v1/userNanoBanana/detail/{id}` — Get task details. - `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserNanoBananaStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userNanoBanana/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "A serene mountain landscape at sunset with a crystal clear lake"
}
JSON
```
- Responses:
  - `200` — Nano Banana task started successfully or NSFW content detected
```json
{"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"}}}]}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userNanoBanana/allRecords — Get Nano Banana task list
Retrieve paginated list of user's Nano Banana image generation tasks. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`, `status`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userNanoBanana/detail/{id}` — Get task details. - `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task. - `POST /api/v1/userNanoBanana/start` — Start Nano Banana image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserNanoBananaAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; min: 1; max: 100; example: `20`) — Number of items per page
  - `status` (query, optional; string; allowed: `initialized`, `processing`, `completed`, `failed`; example: `initialized`) — Filter by task status
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userNanoBanana/allRecords?pageNum=1&pageSize=20&status=initialized" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userNanoBanana/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list. - `GET /api/v1/userNanoBanana/detail/{id}` — Get task details. - `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserNanoBananaBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userNanoBanana/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userNanoBanana/detail/{id} — Get task details
Retrieve detailed information about a specific Nano Banana task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list. - `DELETE /api/v1/userNanoBanana/delete/{id}` — Delete task. - `POST /api/v1/userNanoBanana/start` — Start Nano Banana image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserNanoBananaDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userNanoBanana/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userNanoBanana/delete/{id} — Delete task
Soft-delete the authenticated user's Nano Banana image task identified by `id`, preserving the stored record while excluding it from normal task lists. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/userNanoBanana/allRecords` — Get Nano Banana task list. - `GET /api/v1/userNanoBanana/detail/{id}` — Get task details. - `POST /api/v1/userNanoBanana/start` — Start Nano Banana image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserNanoBananaDeleteId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userNanoBanana/delete/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
#### GPT Image

##### POST /api/v1/userGptImage/start — Start GPT Image generation or editing
Generate images from text or edit existing images using GPT Image (4o Image) model. **Features:** - Text-to-Image generation - Image-to-Image editing (supports up to 16 reference images) - High-fidelity visuals with accurate text rendering **Output:** - Images are stored in R2 storage and expire after 3 days - 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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userGptImage/list` — Get GPT Image task list. - `GET /api/v1/userGptImage/detail/{id}` — Get task details. - `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserGptImageStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userGptImage/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task",
  "prompt": "high quality, clear, cinematic"
}
JSON
```
- Responses:
  - `200` — Task started successfully or NSFW content detected
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userGptImage/list — Get GPT Image task list
Return the authenticated user's GPT Image generation and editing tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userGptImage/detail/{id}` — Get task details. - `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task. - `POST /api/v1/userGptImage/start` — Start GPT Image generation or editing. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserGptImageList`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; example: `1`) — page parameter
  - `page_size` (query, optional; integer; default: `20`; example: `20`) — page_size parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userGptImage/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userGptImage/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userGptImage/list` — Get GPT Image task list. - `GET /api/v1/userGptImage/detail/{id}` — Get task details. - `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserGptImageBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userGptImage/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userGptImage/detail/{id} — Get task details
Return the authenticated user's GPT Image generation or editing task identified by `id`, including its current status and generated image fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userGptImage/list` — Get GPT Image task list. - `DELETE /api/v1/userGptImage/{id}` — Delete GPT Image task. - `POST /api/v1/userGptImage/start` — Start GPT Image generation or editing. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserGptImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userGptImage/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userGptImage/{id} — Delete GPT Image task
Soft-delete the authenticated user's GPT Image task identified by `id`; the task is excluded from subsequent list results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userGptImage/list` — Get GPT Image task list. - `GET /api/v1/userGptImage/detail/{id}` — Get task details. - `POST /api/v1/userGptImage/start` — Start GPT Image generation or editing. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserGptImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userGptImage/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Flux 2

##### POST /api/v1/userFlux2/start — Start Flux 2 Pro image generation or editing
Generate high-quality images from text or edit existing images using Flux 2 Pro model. **Features:** - Text-to-Image generation with advanced prompt understanding - Image-to-Image editing (supports up to 8 reference images) - Character consistency across multiple images - Text rendering within images - High-quality output with professional-grade results **Processing Time:** - Usually 20-60 seconds **Output:** - Images are stored in R2 storage (3days-apac bucket) and expire 3 days after the task is created (createdAt + 3 days, same as `expirationDate`) - Download and persist the result to your own storage before it expires; `image_url` is a temporary CDN URL, not a permanent asset address - 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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid request parameters. - `401` — Unauthorized - Invalid or missing token. - `402` — Insufficient credits. - `500` — Internal server error. ### Related Operations - `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list. - `GET /api/v1/userFlux2/detail/{id}` — Get task details. - `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFlux2Start`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userFlux2/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Elon Musk and Mark Zuckerberg boxing",
  "prompt": "Elon Musk and Mark Zuckerberg boxing in a professional ring"
}
JSON
```
- Responses:
  - `200` — Flux 2 Pro task started successfully or NSFW content detected
```json
{"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"}}}]}
```
  - `400` — Invalid request parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `402` — Insufficient credits
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `500` — Internal server error
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFlux2/list — Get Flux 2 Pro task list
Retrieve paginated list of user's Flux 2 Pro image generation tasks. Tasks are sorted by creation date (newest first). Only returns tasks that haven't expired (3 days retention, counted from createdAt); expired tasks are omitted rather than flagged. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `page`, `page_size`, `status`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFlux2/detail/{id}` — Get task details. - `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task. - `POST /api/v1/userFlux2/start` — Start Flux 2 Pro image generation or editing. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFlux2List`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starting from 1)
  - `page_size` (query, optional; integer; default: `20`; min: 1; max: 100; example: `20`) — Number of items per page (max 100)
  - `status` (query, optional; string; allowed: `initialized`, `processing`, `completed`, `failed`; example: `initialized`) — Filter by task status
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFlux2/list?page=1&page_size=20&status=initialized" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userFlux2/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list. - `GET /api/v1/userFlux2/detail/{id}` — Get task details. - `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFlux2BatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userFlux2/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFlux2/detail/{id} — Get task details
Retrieve detailed information about a specific Flux 2 Pro task, including generation status, image URL, and processing time. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list. - `DELETE /api/v1/userFlux2/{id}` — Delete Flux 2 Pro task. - `POST /api/v1/userFlux2/start` — Start Flux 2 Pro image generation or editing. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFlux2DetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFlux2/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
```json
{"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` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userFlux2/{id} — Delete Flux 2 Pro task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userFlux2/list` — Get Flux 2 Pro task list. - `GET /api/v1/userFlux2/detail/{id}` — Get task details. - `POST /api/v1/userFlux2/start` — Start Flux 2 Pro image generation or editing. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserFlux2Id`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userFlux2/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Qwen Image

##### POST /api/v1/userQwen2Image/start — Start a new Qwen image generation/edit task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userQwen2Image/list` — List Qwen image tasks. - `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details. - `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserQwen2ImageStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userQwen2Image/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task",
  "prompt": "high quality, clear, cinematic"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userQwen2Image/list — List Qwen image tasks
Return the authenticated user's Qwen image generation and editing tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details. - `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task. - `POST /api/v1/userQwen2Image/start` — Start a new Qwen image generation/edit task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserQwen2ImageList`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; example: `1`) — Page number. Uses page/page_size, not pageNum/pageSize.
  - `page_size` (query, optional; integer; default: `20`; example: `20`) — Rows per page. Backend pagination limits are documented separately when available; do not assume max=100.
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userQwen2Image/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userQwen2Image/detail/{id} — Get Qwen image task details
Return the authenticated user's Qwen image task identified by `id`, including its current status and generated image fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userQwen2Image/list` — List Qwen image tasks. - `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task. - `POST /api/v1/userQwen2Image/start` — Start a new Qwen image generation/edit task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserQwen2ImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userQwen2Image/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userQwen2Image/batchDetail — Batch get Qwen image task details
Return up to 200 authenticated-user Qwen image tasks matching the submitted `ids`; callers should match records by identifier. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userQwen2Image/list` — List Qwen image tasks. - `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details. - `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserQwen2ImageBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userQwen2Image/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userQwen2Image/{id} — Delete a Qwen image task
Soft-delete the authenticated user's Qwen image task identified by `id`; the task is excluded from subsequent list results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userQwen2Image/list` — List Qwen image tasks. - `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details. - `POST /api/v1/userQwen2Image/start` — Start a new Qwen image generation/edit task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserQwen2ImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userQwen2Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Kling Image

##### POST /api/v1/userKlingImage/start — Start Kling 3.0 image generation
Create one or more asynchronous Kling 3.0 image tasks from the prompt and optional reference images, subject to the request's `n` limit. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userKlingImage/list` — List Kling image tasks. - `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details. - `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserKlingImageStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userKlingImage/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task",
  "prompt": "high quality, clear, cinematic"
}
JSON
```
- Responses:
  - `200` — Task created successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userKlingImage/list — List Kling image tasks
Return the authenticated user's Kling image tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details. - `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task. - `POST /api/v1/userKlingImage/start` — Start Kling 3.0 image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserKlingImageList`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; example: `1`) — Page number. Uses page/page_size, not pageNum/pageSize.
  - `page_size` (query, optional; integer; default: `20`; example: `20`) — Rows per page. Backend pagination limits are documented separately when available; do not assume max=100.
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userKlingImage/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userKlingImage/batchDetail — Batch get Kling image task details
Return up to 200 authenticated-user Kling image tasks matching the submitted `ids`; callers should match records by identifier. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userKlingImage/list` — List Kling image tasks. - `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details. - `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserKlingImageBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userKlingImage/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Task details
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userKlingImage/detail/{id} — Get Kling image task details
Return the authenticated user's Kling image task identified by `id`, including its current status and generated image fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userKlingImage/list` — List Kling image tasks. - `DELETE /api/v1/userKlingImage/{id}` — Delete a Kling image task. - `POST /api/v1/userKlingImage/start` — Start Kling 3.0 image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserKlingImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userKlingImage/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userKlingImage/{id} — Delete a Kling image task
Soft-delete the authenticated user's Kling image task identified by `id`; the task is excluded from subsequent list results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userKlingImage/list` — List Kling image tasks. - `GET /api/v1/userKlingImage/detail/{id}` — Get Kling image task details. - `POST /api/v1/userKlingImage/start` — Start Kling 3.0 image generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserKlingImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userKlingImage/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Wan2.6 Image

##### POST /api/v1/userWan26Image/start — Start a new Wan2.6-Image generation task
Create an asynchronous Wan 2.6 image task from a text prompt, with optional input images and generation controls defined by the request schema. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan26Image/list` — Get task list. - `GET /api/v1/userWan26Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan26Image/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan26ImageStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan26Image/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task",
  "prompt": "high quality, clear, cinematic"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan26Image/list — Get task list
Return the authenticated user's Wan 2.6 image tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan26Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan26Image/{id}` — Delete task. - `POST /api/v1/userWan26Image/start` — Start a new Wan2.6-Image generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan26ImageList`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; example: `1`) — page parameter
  - `page_size` (query, optional; integer; default: `20`; example: `20`) — page_size parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan26Image/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan26Image/detail/{id} — Get task details
Return the authenticated user's Wan 2.6 image task identified by `id`, including its current status and generated image fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan26Image/list` — Get task list. - `DELETE /api/v1/userWan26Image/{id}` — Delete task. - `POST /api/v1/userWan26Image/start` — Start a new Wan2.6-Image generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan26ImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan26Image/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWan26Image/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan26Image/list` — Get task list. - `GET /api/v1/userWan26Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan26Image/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan26ImageBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan26Image/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userWan26Image/{id} — Delete task
Soft-delete the authenticated user's Wan 2.6 image task identified by `id`; the task is excluded from subsequent list results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan26Image/list` — Get task list. - `GET /api/v1/userWan26Image/detail/{id}` — Get task details. - `POST /api/v1/userWan26Image/start` — Start a new Wan2.6-Image generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWan26ImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userWan26Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Wan2.7 Image

##### POST /api/v1/userWan27Image/start — Start a new Wan2.7-Image generation task
Create an asynchronous Wan 2.7 image task from a text prompt, with optional input images and generation controls defined by the request schema. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan27Image/list` — Get task list. - `GET /api/v1/userWan27Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan27Image/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan27ImageStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan27Image/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task",
  "prompt": "high quality, clear, cinematic"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan27Image/list — Get task list
Return the authenticated user's Wan 2.7 image tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `page`, `page_size`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan27Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan27Image/{id}` — Delete task. - `POST /api/v1/userWan27Image/start` — Start a new Wan2.7-Image generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan27ImageList`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; example: `1`) — page parameter
  - `page_size` (query, optional; integer; default: `20`; example: `20`) — page_size parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan27Image/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan27Image/detail/{id} — Get task details
Return the authenticated user's Wan 2.7 image task identified by `id`, including its current status and generated image fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan27Image/list` — Get task list. - `DELETE /api/v1/userWan27Image/{id}` — Delete task. - `POST /api/v1/userWan27Image/start` — Start a new Wan2.7-Image generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan27ImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan27Image/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWan27Image/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan27Image/list` — Get task list. - `GET /api/v1/userWan27Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan27Image/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan27ImageBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan27Image/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userWan27Image/{id} — Delete task
Soft-delete the authenticated user's Wan 2.7 image task identified by `id`; the task is excluded from subsequent list results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan27Image/list` — Get task list. - `GET /api/v1/userWan27Image/detail/{id}` — Get task details. - `POST /api/v1/userWan27Image/start` — Start a new Wan2.7-Image generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWan27ImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userWan27Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Wan Image to Video

##### POST /api/v1/userWan25/start — Start Wan video generation
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. For Wan 2.7, set `model` to `wan2.7-i2v` and select the generation mode with `task_type`: - `text_to_video`: text prompt only. Do not provide image/video material. - `first_frame`: image-to-video from one first-frame image. Requires `image_url`. - `first_last_frame`: image-to-video with first and last frame control. Requires `image_url` and `last_frame_url`. - `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`. - `video_extend`: extend an existing video clip. Requires `first_clip_url`; optional `last_frame_url`. - `video_edit`: edit an existing video. Requires `edit_video_url`; optional `reference_image_urls` with up to 3 image URLs. `text_to_video`, `first_last_frame`, `reference_image`, `video_extend` and `video_edit` are only available when `model=wan2.7-i2v`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan25Start`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan25/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
}
JSON
```
- Responses:
  - `200` — Wan video task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan25/allRecords — Get all Wan 2.5 tasks
Return the authenticated user's Wan 2.5 image-to-video tasks using the requested pagination controls, including current status and available output metadata. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan25/{_id}` — Get Wan 2.5 task details. - `DELETE /api/v1/userWan25/{_id}` — Delete a Wan 2.5 task. - `POST /api/v1/userWan25/batchDetail` — Batch query task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan25AllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan25/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWan25/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan25/allRecords` — Get all Wan 2.5 tasks. - `GET /api/v1/userWan25/{_id}` — Get Wan 2.5 task details. - `DELETE /api/v1/userWan25/{_id}` — Delete a Wan 2.5 task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan25BatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan25/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan25/{_id} — Get Wan 2.5 task details
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan25/allRecords` — Get all Wan 2.5 tasks. - `DELETE /api/v1/userWan25/{_id}` — Delete a Wan 2.5 task. - `POST /api/v1/userWan25/batchDetail` — Batch query task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan25Id`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan25/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userWan25/{_id} — Delete a Wan 2.5 task
Remove the authenticated user's Wan 2.5 image-to-video task identified by `_id` from normal task history without affecting unrelated tasks. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan25/allRecords` — Get all Wan 2.5 tasks. - `GET /api/v1/userWan25/{_id}` — Get Wan 2.5 task details. - `POST /api/v1/userWan25/batchDetail` — Batch query task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWan25Id`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userWan25/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWanSpicy/start — Start Wan Spicy image-to-video generation
Start a Wan Spicy image-to-video task via mulerouter.ai/carrothub. - wan2.7-i2v-spicy: with audio support, resolution 720p/1080p, duration 2-15 seconds. - wan2.2-i2v-spicy: no audio, resolution 480p/720p, duration 5 or 8 seconds. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`, `image_url`, `resolution`, `duration`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks. - `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details. - `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWanSpicyStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWanSpicy/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "high quality, clear, cinematic",
  "image_url": "https://example.com/image.jpg",
  "resolution": "480p",
  "duration": 5
}
JSON
```
- Responses:
  - `200` — Task started successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWanSpicy/allRecords — Get all Wan Spicy tasks
Return the authenticated user's Wan Spicy image-to-video tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details. - `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task. - `POST /api/v1/userWanSpicy/start` — Start Wan Spicy image-to-video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWanSpicyAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWanSpicy/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWanSpicy/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks. - `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details. - `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWanSpicyBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWanSpicy/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWanSpicy/{_id} — Get Wan Spicy task details
Return the authenticated user's Wan Spicy image-to-video task identified by `_id`, including its current status and video output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks. - `DELETE /api/v1/userWanSpicy/{_id}` — Delete a Wan Spicy task. - `POST /api/v1/userWanSpicy/start` — Start Wan Spicy image-to-video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWanSpicyId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWanSpicy/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userWanSpicy/{_id} — Delete a Wan Spicy task
Soft-delete the authenticated user's Wan Spicy image-to-video task identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWanSpicy/allRecords` — Get all Wan Spicy tasks. - `GET /api/v1/userWanSpicy/{_id}` — Get Wan Spicy task details. - `POST /api/v1/userWanSpicy/start` — Start Wan Spicy image-to-video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWanSpicyId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userWanSpicy/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Wan 2.6 R2V Flash

##### POST /api/v1/userWan26R2V/start — Start reference-to-video generation
Generate a video from reference images/videos using Wan 2.6 R2V Flash. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`, `reference_urls`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks. - `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details. - `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan26R2VStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan26R2V/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "high quality, clear, cinematic",
  "reference_urls": [
    "https://example.com/file"
  ]
}
JSON
```
- Responses:
  - `200` — Task started successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan26R2V/allRecords — Get all R2V tasks
Return the authenticated user's Wan 2.6 reference-to-video tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details. - `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task. - `POST /api/v1/userWan26R2V/start` — Start reference-to-video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan26R2VAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan26R2V/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWan26R2V/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks. - `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details. - `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan26R2VBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan26R2V/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan26R2V/{_id} — Get R2V task details
Return the authenticated user's Wan 2.6 reference-to-video task identified by `_id`, including its current status and video output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks. - `DELETE /api/v1/userWan26R2V/{_id}` — Delete a R2V task. - `POST /api/v1/userWan26R2V/start` — Start reference-to-video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan26R2VId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan26R2V/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userWan26R2V/{_id} — Delete a R2V task
Soft-delete the authenticated user's Wan 2.6 reference-to-video task identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan26R2V/allRecords` — Get all R2V tasks. - `GET /api/v1/userWan26R2V/{_id}` — Get R2V task details. - `POST /api/v1/userWan26R2V/start` — Start reference-to-video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWan26R2VId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userWan26R2V/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Wan3.0 Video Generation

##### POST /api/v1/userWan30/start — Start Wan3.0 all-in-one video generation
Generate a video with `wan3.0-video` or `wan3.0-video-prime`. Both models produce identical quality; `wan3.0-video-prime` only trades a higher per-second price for much faster inference (about 2 minutes instead of about 14 minutes for a 720P 15-second clip). The request/response contract is identical — switch by replacing the model name. Reference mode accepts image, video, audio, file, and public web-page media. Each reference video must be 1–15 seconds; all reference videos together must not exceed 15 seconds, and reference-video plus output duration must not exceed 30 seconds. Strict first-frame/first-last-frame media cannot be mixed with reference media. File and link inputs are mutually exclusive. `prompt_extend` controls upstream prompt rewriting and defaults to false; when it stays off, write prompts following the Wan3.0 creator handbook prompt guide. `negative_prompt` is not supported. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `model`, `input`, `parameters`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid mode, media combination, or generation parameter. - `401` — Unauthorized - Invalid or missing JWT token. - `503` — Provider or Wan3.0 pricing is not configured. ### Related Operations - `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks. - `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details. - `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan30Start`
- Request schema (nested fields and conditions):
```json
{"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"}]}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan30/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
  }
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Invalid mode, media combination, or generation parameter
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Provider or Wan3.0 pricing is not configured

##### GET /api/v1/userWan30/allRecords — List Wan3.0 video tasks
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details. - `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task. - `POST /api/v1/userWan30/start` — Start Wan3.0 all-in-one video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan30AllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `20`; max: 100; example: `20`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan30/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Paginated Wan3.0 task records in data.rows. Each task has optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown).
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userWan30/batchDetail — Batch get Wan3.0 video task details
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks. - `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details. - `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan30BatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userWan30/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "507f1f77bcf86cd799439011"
  ]
}
JSON
```
- Responses:
  - `200` — Matching Wan3.0 task details in data. Each task has optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown).
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userWan30/{_id} — Get Wan3.0 video task details
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found for the authenticated user. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks. - `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task. - `POST /api/v1/userWan30/start` — Start Wan3.0 all-in-one video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan30Id`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID returned by POST /api/v1/userWan30/start.
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userWan30/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Wan3.0 video task status and output. The task has optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown).
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found for the authenticated user.
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userWan30/{_id} — Delete a Wan3.0 video task
Delete the authenticated user's Wan3.0 task record identified by _id. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks. - `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details. - `POST /api/v1/userWan30/start` — Start Wan3.0 all-in-one video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWan30Id`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userWan30/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Wan3.0 task record deleted.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### HappyHorse Video

##### POST /api/v1/userHappyhorseVideo/start — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)
Generate a video using HappyHorse models on Alibaba DashScope. If model_version is omitted, new tasks keep the legacy 1.0 behavior. Supported modes: - t2v: text → video (happyhorse-1.0-t2v / happyhorse-1.1-t2v) - i2v: image first_frame → video (happyhorse-1.0-i2v / happyhorse-1.1-i2v) - r2v: reference images → video (happyhorse-1.0-r2v / happyhorse-1.1-r2v) - video-edit: video + reference images → edited video (happyhorse-1.0-video-edit) ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `mode`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks. - `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details. - `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserHappyhorseVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userHappyhorseVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "mode": "t2v"
}
JSON
```
- Responses:
  - `200` — Task created successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userHappyhorseVideo/allRecords — List HappyHorse tasks
Return the authenticated user's HappyHorse text-to-video, image-to-video, reference-to-video, and video-edit tasks using pagination. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details. - `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task. - `POST /api/v1/userHappyhorseVideo/start` — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserHappyhorseVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userHappyhorseVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userHappyhorseVideo/batchDetail — Batch query task details
Return up to 200 authenticated-user HappyHorse video tasks matching the submitted `ids`; callers should match records by identifier. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks. - `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details. - `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserHappyhorseVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"example":["example"]}},"required":["ids"],"example":{"ids":["example"]}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userHappyhorseVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userHappyhorseVideo/{_id} — Get HappyHorse task details
Return the authenticated user's HappyHorse video task identified by `_id`, including its mode, current status, and video output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks. - `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task. - `POST /api/v1/userHappyhorseVideo/start` — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserHappyhorseVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userHappyhorseVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userHappyhorseVideo/{_id} — Delete a HappyHorse task
Soft-delete the authenticated user's HappyHorse video task identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userHappyhorseVideo/allRecords` — List HappyHorse tasks. - `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details. - `POST /api/v1/userHappyhorseVideo/start` — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserHappyhorseVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userHappyhorseVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Hailuo Video Generation

##### POST /api/v1/hailuoVideo/start — Start Hailuo video generation
Generate videos using Hailuo. Only supports image-to-video mode. **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. **Duration:** `6` or `10` seconds. **Resolution:** `768P` (default) or `1080P` (not available for 10s). This is an asynchronous API. After calling this endpoint, poll `/api/v1/hailuoVideo/{_id}` to check task status. Model 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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list. - `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail. - `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1HailuoVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/hailuoVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "A cat playing with a ball of yarn",
  "image_url": "https://example.com/image.jpg"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/hailuoVideo/allRecords — Get Hailuo Video task list
Return the authenticated user's Hailuo video-generation tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail. - `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task. - `POST /api/v1/hailuoVideo/start` — Start Hailuo video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1HailuoVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/hailuoVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/hailuoVideo/batchDetail — Batch query Hailuo Video task details
Query details for multiple of the authenticated user's Hailuo video tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list. - `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail. - `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1HailuoVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/hailuoVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/hailuoVideo/{_id} — Get Hailuo Video task detail
Return the authenticated user's Hailuo video task identified by `_id`, including its current status and video output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list. - `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task. - `POST /api/v1/hailuoVideo/start` — Start Hailuo video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1HailuoVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/hailuoVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/hailuoVideo/{_id} — Delete Hailuo Video task
Soft-delete the authenticated user's Hailuo video task identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list. - `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail. - `POST /api/v1/hailuoVideo/start` — Start Hailuo video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1HailuoVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/hailuoVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Deleted
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### MiniMax H3 Video Generation

##### POST /api/v1/minimaxH3Video/start — Start MiniMax H3 video generation
Generate videos using MiniMax H3. Supports three modes via `mode`: `text-to-video`, `image-to-video` (first/last frame) and `reference-to-video` (reference images/videos/audios). **Required:** `prompt`. For `image-to-video`, `first_frame_url` is required. For `reference-to-video`, at least one of `reference_image_urls` / `reference_video_urls` / `reference_audio_urls` is required. **Duration:** integer seconds between `4` and `15`. **Resolution:** `768P` or `2K` (default). **Aspect ratio:** for `text-to-video` one of `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`; `reference-to-video` additionally supports `adaptive` (default). Ignored for `image-to-video`. This is an asynchronous API. After calling this endpoint, poll `/api/v1/minimaxH3Video/{_id}` to check task status. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list. - `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail. - `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1MinimaxH3VideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/minimaxH3Video/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "A cinematic sunrise over snowy mountains"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/minimaxH3Video/allRecords — Get MiniMax H3 Video task list
Return the authenticated user's MiniMax H3 video-generation tasks using the requested pagination controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail. - `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task. - `POST /api/v1/minimaxH3Video/start` — Start MiniMax H3 video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1MinimaxH3VideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/minimaxH3Video/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/minimaxH3Video/batchDetail — Batch query MiniMax H3 Video task details
Return details for several of the authenticated user's MiniMax H3 video tasks in one request. Duplicate ids are removed and at most 200 ids are processed per call. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list. - `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail. - `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1MinimaxH3VideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/minimaxH3Video/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "0123456789abcdef01234567"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/minimaxH3Video/{_id} — Get MiniMax H3 Video task detail
Return the authenticated user's MiniMax H3 video task identified by `_id`, including its current status and video output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list. - `DELETE /api/v1/minimaxH3Video/{_id}` — Delete MiniMax H3 Video task. - `POST /api/v1/minimaxH3Video/start` — Start MiniMax H3 video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1MinimaxH3VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/minimaxH3Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/minimaxH3Video/{_id} — Delete MiniMax H3 Video task
Soft-delete the authenticated user's MiniMax H3 video task identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/minimaxH3Video/allRecords` — Get MiniMax H3 Video task list. - `GET /api/v1/minimaxH3Video/{_id}` — Get MiniMax H3 Video task detail. - `POST /api/v1/minimaxH3Video/start` — Start MiniMax H3 video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1MinimaxH3VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/minimaxH3Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Deleted
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Seedance 1.5 Pro

##### POST /api/v1/seedanceVideo/start — Start Seedance 1.5 Pro video generation
Generate videos using BytePlus ModelArk Seedance 1.5 Pro. Supports 3 modes - text-to-video, image-to-video, first-last-frames. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records. - `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail. - `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SeedanceVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/seedanceVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "A girl holding a fox, the girl opens her eyes..."
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/seedanceVideo/allRecords — Get all Seedance video records
Retrieve all Seedance video generation records for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail. - `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name. - `DELETE /api/v1/seedanceVideo/{_id}` — Delete Seedance video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SeedanceVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedanceVideo/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/seedanceVideo/batchDetail — Batch get Seedance 1.5 task details
Return details for up to 200 distinct task IDs owned by the authenticated user. An empty ids array returns an empty list. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records. - `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail. - `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SeedanceVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"example":["507f1f77bcf86cd799439011"]}},"required":[],"example":{}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/seedanceVideo/batchDetail" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/seedanceVideo/{_id} — Get Seedance video detail
Get detailed information about a specific Seedance video generation task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records. - `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name. - `DELETE /api/v1/seedanceVideo/{_id}` — Delete Seedance video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SeedanceVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedanceVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### PUT /api/v1/seedanceVideo/{_id} — Update Seedance video name
Rename the authenticated user's Seedance video task identified by `_id`; generation settings, processing status, and output media are unchanged. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. - Send an `application/json` body. Required fields: `name`. ### Behavior - Updates the identified resource using the fields accepted by the request schema and the operation's access controls. - Fields omitted from the request retain their existing values unless the schema states otherwise. - Read the returned record or call the detail operation to confirm the persisted state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records. - `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail. - `DELETE /api/v1/seedanceVideo/{_id}` — Delete Seedance video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1SeedanceVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"name":{"type":"string","description":"New name for the task","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}}
```
- Example request:
```bash
curl -X PUT "https://headswap.app/api/v1/seedanceVideo/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Name updated successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found

##### DELETE /api/v1/seedanceVideo/{_id} — Delete Seedance video
Remove the authenticated user's Seedance video task identified by `_id` from normal task history without affecting unrelated tasks. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records. - `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail. - `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1SeedanceVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/seedanceVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
#### Seedance 2.x

##### POST /api/v1/seedance2Video/start — Start Seedance 2.x video generation
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). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/seedance2Video/allRecords` — Get all records. - `GET /api/v1/seedance2Video/{_id}` — Get task detail. - `PUT /api/v1/seedance2Video/{_id}` — Rename task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1Seedance2VideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/seedance2Video/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "prompt": "high quality, clear, cinematic"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/seedance2Video/allRecords — Get all records
List the current user's Seedance 2.0 video tasks with pagination. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedance2Video/{_id}` — Get task detail. - `PUT /api/v1/seedance2Video/{_id}` — Rename task. - `DELETE /api/v1/seedance2Video/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1Seedance2VideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number (1-based)
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedance2Video/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/seedance2Video/batchDetail — Batch get task details
Fetch multiple Seedance 2.0 video task records in a single request (up to 200 ids). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedance2Video/allRecords` — Get all records. - `GET /api/v1/seedance2Video/{_id}` — Get task detail. - `PUT /api/v1/seedance2Video/{_id}` — Rename task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1Seedance2VideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/seedance2Video/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/seedance2Video/{_id} — Get task detail
Return the authenticated user's Seedance 2.0 video task identified by `_id`, including its generation settings, current status, and available video output. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedance2Video/allRecords` — Get all records. - `PUT /api/v1/seedance2Video/{_id}` — Rename task. - `DELETE /api/v1/seedance2Video/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1Seedance2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task record id
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedance2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### PUT /api/v1/seedance2Video/{_id} — Rename task
Rename the authenticated user's Seedance 2.0 video task identified by `_id`; generation settings, processing status, and output media are unchanged. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. - Send an `application/json` body. Required fields: `name`. ### Behavior - Updates the identified resource using the fields accepted by the request schema and the operation's access controls. - Fields omitted from the request retain their existing values unless the schema states otherwise. - Read the returned record or call the detail operation to confirm the persisted state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/seedance2Video/allRecords` — Get all records. - `GET /api/v1/seedance2Video/{_id}` — Get task detail. - `DELETE /api/v1/seedance2Video/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1Seedance2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task record id
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"name":{"type":"string","description":"New task name","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}}
```
- Example request:
```bash
curl -X PUT "https://headswap.app/api/v1/seedance2Video/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Updated
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/seedance2Video/{_id} — Delete task
Remove the authenticated user's Seedance 2.0 video task identified by `_id` from normal task history without affecting unrelated tasks. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/seedance2Video/allRecords` — Get all records. - `GET /api/v1/seedance2Video/{_id}` — Get task detail. - `PUT /api/v1/seedance2Video/{_id}` — Rename task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1Seedance2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task record id
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/seedance2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Deleted
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Veo Video

##### POST /api/v1/veoVideo/start — Start Veo 3.1 video generation
Generate videos using Google DeepMind's Veo 3.1 AI model. Supports text-to-video, image-to-video, and reference-based generation. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/veoVideo/batchDetail` — Batch query task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VeoVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/veoVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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.\""
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/veoVideo/allRecords — Get all Veo video records
Retrieve paginated list of user's Veo video generation records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/veoVideo/{_id}` — Get Veo video detail. - `DELETE /api/v1/veoVideo/{_id}` — Delete Veo video record. - `GET /api/v1/veoVideo/{_id}/1080p` — Get 1080P HD video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VeoVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/veoVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/veoVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `POST /api/v1/veoVideo/start` — Start Veo 3.1 video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VeoVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/veoVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/veoVideo/{_id} — Get Veo video detail
Retrieve detailed information of a specific Veo video generation record. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/veoVideo/allRecords` — Get all Veo video records. - `DELETE /api/v1/veoVideo/{_id}` — Delete Veo video record. - `GET /api/v1/veoVideo/{_id}/1080p` — Get 1080P HD video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VeoVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Video record ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/veoVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/veoVideo/{_id} — Delete Veo video record
Soft-delete the authenticated user's Veo video task identified by `_id`, preserving the stored record while excluding it from normal task lists. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/veoVideo/allRecords` — Get all Veo video records. - `GET /api/v1/veoVideo/{_id}` — Get Veo video detail. - `GET /api/v1/veoVideo/{_id}/1080p` — Get 1080P HD video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1VeoVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Video record ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/veoVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Video record deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/veoVideo/{_id}/1080p — Get 1080P HD video
Retrieve 1080P high-definition version of the video (only available for 16:9 aspect ratio) ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Reads the requested information without creating a generation task. - Use the returned fields as documented; availability may depend on the caller and current resource state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid aspect ratio or missing task ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/veoVideo/allRecords` — Get all Veo video records. - `GET /api/v1/veoVideo/{_id}` — Get Veo video detail. - `DELETE /api/v1/veoVideo/{_id}` — Delete Veo video record. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VeoVideoId1080p`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Video record ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/veoVideo/507f1f77bcf86cd799439011/1080p" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 1080P video retrieved successfully
```json
{"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"}}}
```
  - `202` — 1080P video is being processed, please try again later
  - `400` — Invalid aspect ratio or missing task ID
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Grok Video

##### POST /api/v1/grokVideo/start — Start Grok Imagine video generation
Generate videos using Grok Imagine. Supports both text-to-video and image-to-video modes. **Modes:** - `text-to-video`: Generate video from a text prompt. Requires `prompt`. - `image-to-video`: Generate video from a reference image. Requires at least one image in `image_urls` (or `image_url`). **Duration:** `6`, `10`, or `15` seconds. **Model version:** `legacy` (default) uses the existing Grok Imagine path. `1.5` uses Grok Imagine Video 1.5 and only supports `image-to-video`. **Mode:** `fun`, `normal` (default), or `spicy`. This is an asynchronous API. After calling this endpoint, poll `/api/v1/grokVideo/{_id}` to check task status until `current_status` becomes `completed` or `failed`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list. - `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail. - `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1GrokVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/grokVideo/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/grokVideo/allRecords — Get Grok Video task list
Retrieve paginated list of user's Grok Imagine video generation tasks, ordered by creation time (newest first). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail. - `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task. - `POST /api/v1/grokVideo/start` — Start Grok Imagine video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1GrokVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/grokVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/grokVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list. - `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail. - `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1GrokVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/grokVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/grokVideo/{_id} — Get Grok Video task detail
Retrieve detailed information of a specific Grok Imagine video generation task by ID. Use this endpoint to poll task status after creation. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list. - `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task. - `POST /api/v1/grokVideo/start` — Start Grok Imagine video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1GrokVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/grokVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/grokVideo/{_id} — Delete Grok Video task
Remove the authenticated user's Grok Imagine video task identified by `_id` from normal task history without affecting unrelated tasks. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. ### Related Operations - `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list. - `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail. - `POST /api/v1/grokVideo/start` — Start Grok Imagine video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1GrokVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/grokVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Kling Video

##### POST /api/v1/klingVideo/start — Start Kling video generation
Generate videos using Kling Official API. **Modes:** - `text-to-video` – generate video from text prompt - `image-to-video` – generate video from an image (+ optional end frame in PRO) - `motion-control` – transfer motion from a video onto an image **Versions:** `2.6` (5s/10s) and `3.0` (standard/fast: 3s–15s) **Quality:** `std` (Standard), `pro` (Professional), or `4k` (Kling 3.0 Native 4K for text/image video). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `mode`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/klingVideo/allRecords` — Get all Kling video records. - `GET /api/v1/klingVideo/{_id}` — Get Kling video detail. - `PUT /api/v1/klingVideo/{_id}` — Update Kling video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/klingVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "mode": "image-to-video",
  "prompt": "A beautiful sunset over the ocean"
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/klingVideo/allRecords — Get all Kling video records
Retrieve all Kling video generation records for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/klingVideo/{_id}` — Get Kling video detail. - `PUT /api/v1/klingVideo/{_id}` — Update Kling video name. - `DELETE /api/v1/klingVideo/{_id}` — Delete Kling video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/klingVideo/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/klingVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/klingVideo/allRecords` — Get all Kling video records. - `GET /api/v1/klingVideo/{_id}` — Get Kling video detail. - `PUT /api/v1/klingVideo/{_id}` — Update Kling video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/klingVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/klingVideo/{_id} — Get Kling video detail
Get detailed information about a specific Kling video generation task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/klingVideo/allRecords` — Get all Kling video records. - `PUT /api/v1/klingVideo/{_id}` — Update Kling video name. - `DELETE /api/v1/klingVideo/{_id}` — Delete Kling video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/klingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### PUT /api/v1/klingVideo/{_id} — Update Kling video name
Rename the authenticated user's Kling video task identified by `_id`; generation settings, processing status, and output media are unchanged. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. - Send an `application/json` body. Required fields: `name`. ### Behavior - Updates the identified resource using the fields accepted by the request schema and the operation's access controls. - Fields omitted from the request retain their existing values unless the schema states otherwise. - Read the returned record or call the detail operation to confirm the persisted state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/klingVideo/allRecords` — Get all Kling video records. - `GET /api/v1/klingVideo/{_id}` — Get Kling video detail. - `DELETE /api/v1/klingVideo/{_id}` — Delete Kling video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1KlingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"name":{"type":"string","description":"New name for the task","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}}
```
- Example request:
```bash
curl -X PUT "https://headswap.app/api/v1/klingVideo/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Name updated successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found

##### DELETE /api/v1/klingVideo/{_id} — Delete Kling video
Remove the authenticated user's Kling video task identified by `_id` from normal task history without affecting unrelated tasks. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/klingVideo/allRecords` — Get all Kling video records. - `GET /api/v1/klingVideo/{_id}` — Get Kling video detail. - `PUT /api/v1/klingVideo/{_id}` — Update Kling video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1KlingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/klingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
#### Kling Omni

##### POST /api/v1/klingOmni/start — Start Kling Omni video generation
Generate videos using Kling Omni API (model: kling-v3-omni). This is a simplified wrapper around the official Kling API. **Key Features:** - Multi-reference images: up to 7 images, use `<<<image_N>>>` tags in prompt - Multi-shot editing: AI Director (intelligence) or manual (customize) storyboard - Native sound generation via `sound` parameter - Flexible duration: 3–15 seconds **Simplified vs Official API:** - `image_list`: accepts `string[]` (image URLs); official uses `[{image_url, type?}]`, auto-converted on server - `sound`: accepts `boolean`; official uses `"on"/"off"`, auto-converted on server - `multi_prompt`: items need `prompt` + `duration`; server auto-adds `index` field for official API - `prompt` is required when `multi_shot=false` or `shot_type=intelligence` - `multi_prompt` total duration must equal `duration` when `shot_type=customize` - `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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records. - `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail. - `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingOmniStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/klingOmni/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/klingOmni/allRecords — Get all Kling Omni video records
Retrieve paginated list of Kling Omni video generation tasks for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail. - `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name. - `DELETE /api/v1/klingOmni/{_id}` — Delete Kling Omni video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingOmniAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Number of records per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/klingOmni/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/klingOmni/batchDetail — Batch get Kling Omni video details
Get details of multiple Kling Omni tasks by their IDs (max 200). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records. - `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail. - `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingOmniBatchDetail`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","example":"example"},"description":"Array of task IDs","example":["example"]}},"required":["ids"],"example":{"ids":["example"]}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/klingOmni/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/klingOmni/{_id} — Get Kling Omni video detail
Get detailed information about a specific Kling Omni video generation task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records. - `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name. - `DELETE /api/v1/klingOmni/{_id}` — Delete Kling Omni video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingOmniId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/klingOmni/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `404` — Task not found
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### PUT /api/v1/klingOmni/{_id} — Update Kling Omni video name
Rename the authenticated user's Kling Omni video task identified by `_id`; generation settings, processing status, and output media are unchanged. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. - Send an `application/json` body. Required fields: `name`. ### Behavior - Updates the identified resource using the fields accepted by the request schema and the operation's access controls. - Fields omitted from the request retain their existing values unless the schema states otherwise. - Read the returned record or call the detail operation to confirm the persisted state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `404` — Task not found. ### Related Operations - `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records. - `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail. - `DELETE /api/v1/klingOmni/{_id}` — Delete Kling Omni video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1KlingOmniId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"name":{"type":"string","description":"New name for the task","example":"My Task"}},"required":["name"],"example":{"name":"My Task"}}
```
- Example request:
```bash
curl -X PUT "https://headswap.app/api/v1/klingOmni/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Updated successfully
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `404` — Task not found

##### DELETE /api/v1/klingOmni/{_id} — Delete Kling Omni video
Soft-delete the authenticated user's Kling Omni video task identified by `_id`, preserving the stored record while excluding it from normal task lists. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized. - `404` — Task not found. ### Related Operations - `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records. - `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail. - `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1KlingOmniId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/klingOmni/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized
  - `404` — Task not found
#### Kling Assets

##### GET /api/v1/klingAssets — List the authenticated user's Kling Elements and voices
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`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Reads the requested information without creating a generation task. - Use the returned fields as documented; availability may depend on the caller and current resource state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/klingAssets/{id}` — Remove an owned Kling asset. - `POST /api/v1/klingAssets/voices` — Create a Kling custom voice. - `POST /api/v1/klingAssets/elements` — Create a Kling Element. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingAssets`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/klingAssets" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Asset list returned
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/klingAssets/voices — Create a Kling custom voice
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `voice_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Voice sample audio probe failed; code stays 500 and msg includes the audio source failure reason. No voice task or charge is created. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/klingAssets/{id}` — Remove an owned Kling asset. - `POST /api/v1/klingAssets/elements` — Create a Kling Element. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingAssetsVoices`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/klingAssets/voices" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task",
  "voice_url": "https://example.com/file"
}
JSON
```
- Responses:
  - `200` — Voice creation submitted; `asset_id` is filled in once `status` becomes succeed
```json
{"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"}}}
```
  - `400` — Voice sample audio probe failed; code stays 500 and msg includes the audio source failure reason. No voice task or charge is created.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/klingAssets/elements — Create a Kling Element
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `image_url`, `reference_image_urls`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid input or unavailable voice. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/klingAssets/{id}` — Remove an owned Kling asset. - `POST /api/v1/klingAssets/voices` — Create a Kling custom voice. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingAssetsElements`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/klingAssets/elements" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Lily",
  "image_url": "https://example.com/image.jpg",
  "reference_image_urls": [
    "https://example.com/side.jpg"
  ]
}
JSON
```
- Responses:
  - `200` — Element creation submitted; `asset_id` is filled in once `status` becomes succeed
```json
{"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"}}}
```
  - `400` — Invalid input or unavailable voice
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/klingAssets/{id} — Remove an owned Kling asset
Remove an owned Kling asset. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/klingAssets/voices` — Create a Kling custom voice. - `POST /api/v1/klingAssets/elements` — Create a Kling Element. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1KlingAssetsId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/klingAssets/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Asset removed
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Image Edit

##### POST /api/v1/userImageEdit/start — Start image editing task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `edit_type`, `image_urls`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userImageEdit/allRecords` — Get all task records. - `GET /api/v1/userImageEdit/{_id}` — Get task details. - `DELETE /api/v1/userImageEdit/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImageEditStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userImageEdit/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "edit_type": "product",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userImageEdit/allRecords — Get all task records
Return the authenticated user's image-editing tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userImageEdit/{_id}` — Get task details. - `DELETE /api/v1/userImageEdit/{_id}` — Delete task. - `POST /api/v1/userImageEdit/start` — Start image editing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImageEditAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userImageEdit/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImageEdit/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userImageEdit/allRecords` — Get all task records. - `GET /api/v1/userImageEdit/{_id}` — Get task details. - `DELETE /api/v1/userImageEdit/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImageEditBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userImageEdit/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userImageEdit/{_id} — Get task details
Return the authenticated user's image-editing task identified by `_id`, including its current processing status and generated image fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userImageEdit/allRecords` — Get all task records. - `DELETE /api/v1/userImageEdit/{_id}` — Delete task. - `POST /api/v1/userImageEdit/start` — Start image editing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImageEditId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userImageEdit/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userImageEdit/{_id} — Delete task
Remove the authenticated user's image-editing task identified by `_id` from the task history without affecting other generated-image records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userImageEdit/allRecords` — Get all task records. - `GET /api/v1/userImageEdit/{_id}` — Get task details. - `POST /api/v1/userImageEdit/start` — Start image editing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserImageEditId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userImageEdit/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

### Face & Body
#### Face Swap

##### POST /api/v1/userFaceSwapImage/add — Add a new face image for face swapping
Add a new face image to the user's face swap image collection. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `face_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userFaceSwapImage/records` — Get user's face swap image records. - `DELETE /api/v1/userFaceSwapImage/{_id}` — Remove a face swap image. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapImageAdd`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userFaceSwapImage/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "face_url": "https://example.com/face-image.jpg"
}
JSON
```
- Responses:
  - `200` — Face image added successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFaceSwapImage/records — Get user's face swap image records
Return the authenticated user's saved face-swap source images and their reusable record identifiers. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `DELETE /api/v1/userFaceSwapImage/{_id}` — Remove a face swap image. - `POST /api/v1/userFaceSwapImage/add` — Add a new face image for face swapping. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapImageRecords`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFaceSwapImage/records" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Face swap image records retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userFaceSwapImage/{_id} — Remove a face swap image
Delete a specific face swap image from the user's collection. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid ID format. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userFaceSwapImage/records` — Get user's face swap image records. - `POST /api/v1/userFaceSwapImage/add` — Add a new face image for face swapping. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserFaceSwapImageId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap image to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userFaceSwapImage/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Face swap image deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid ID format
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userFaceSwapPreview/add — Create a new face swap preview task
Create a face swap preview task using video and face image URLs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `video_url`, `face_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userFaceSwapPreview/status` — Get face swap preview status. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapPreviewAdd`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userFaceSwapPreview/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "video_url": "https://example.com/video.mp4",
  "face_url": "https://example.com/face.jpg"
}
JSON
```
- Responses:
  - `200` — Face swap preview task created successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFaceSwapPreview/status — Get face swap preview status
Check the processing status of a specific face swap preview task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `_id`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID format. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `POST /api/v1/userFaceSwapPreview/add` — Create a new face swap preview task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapPreviewStatus`
- Request parameters:
  - `_id` (query, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap preview task
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFaceSwapPreview/status?_id=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Preview status retrieved successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID format
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userFaceSwapTask/add — Create a new face swap task
Create a face swap task with video, face image, and optional cover image. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `video_url`, `face_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records. - `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details. - `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapTaskAdd`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userFaceSwapTask/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Face Swap Video",
  "video_url": "https://example.com/video.mp4",
  "face_url": "https://example.com/face.jpg"
}
JSON
```
- Responses:
  - `200` — Face swap task created successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFaceSwapTask/records — Get user's face swap task records
Retrieve paginated list of face swap tasks for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid pagination parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details. - `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task. - `POST /api/v1/userFaceSwapTask/add` — Create a new face swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapTaskRecords`
- Request parameters:
  - `pageNum` (query, required; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, required; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFaceSwapTask/records?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task records retrieved successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid pagination parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFaceSwapTask/status — Get user's face swap task status
Get overall face swap task status information for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records. - `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details. - `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapTaskStatus`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFaceSwapTask/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task status retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userFaceSwapTask/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records. - `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details. - `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapTaskBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userFaceSwapTask/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userFaceSwapTask/{_id} — Get face swap task details
Retrieve detailed information about a specific face swap task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID format. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records. - `DELETE /api/v1/userFaceSwapTask/{_id}` — Delete face swap task. - `POST /api/v1/userFaceSwapTask/add` — Create a new face swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapTaskId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap task
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userFaceSwapTask/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID format
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userFaceSwapTask/{_id} — Delete face swap task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userFaceSwapTask/records` — Get user's face swap task records. - `GET /api/v1/userFaceSwapTask/{_id}` — Get face swap task details. - `POST /api/v1/userFaceSwapTask/add` — Create a new face swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserFaceSwapTaskId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap task to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userFaceSwapTask/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Head Swap

##### POST /api/v1/headSwap/start — Start head swap generation
Generate a head swap result by replacing the head in a target image/video with a source head. **Supported modes:** - **Image to Image**: Provide an image as `target_image_url` to get a head-swapped image - **Image to Video**: Provide a video as `target_image_url` to get a head-swapped video (max 15 seconds) **Content moderation:** - CSAM detection is performed on input images - If confirmed CSAM intent is detected together with age < 10, the request will be rejected with code 1003 - If suspected CSAM is detected, set `minor_suspected_skip: true` to proceed - Head swap sends no user prompt to the detector, so a low apparent age alone does not trigger 1003 **Async workflow:** 1. Task is created with status `initialized` 2. Task is queued and sent to algorithm service (status: `sent`) 3. Algorithm processes the task (status: `processing`) 4. Result is ready (status: `completed`) or failed (status: `failed`) 5. Use `/api/v1/headSwap/{_id}` to poll for status updates. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `image_url`, `target_image_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid request parameters or insufficient coins. - `401` — Unauthorized - Invalid or missing JWT token. - `403` — Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor) ### Related Operations - `GET /api/v1/headSwap/allRecords` — Get all head swap records. - `GET /api/v1/headSwap/{_id}` — Get head swap task detail. - `DELETE /api/v1/headSwap/{_id}` — Delete head swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1HeadSwapStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/headSwap/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "image_url": "https://example.com/head.jpg",
  "target_image_url": "https://example.com/body.jpg"
}
JSON
```
- Responses:
  - `200` — Head swap task started successfully
```json
{"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"}}}
```
  - `400` — Invalid request parameters or insufficient coins
  - `401` — Unauthorized - Invalid or missing JWT token
  - `403` — Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor)

##### GET /api/v1/headSwap/allRecords — Get all head swap records
Get a paginated list of the current user's head swap tasks. Results are sorted by creation time (newest first) and filtered by expiration. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/headSwap/{_id}` — Get head swap task detail. - `DELETE /api/v1/headSwap/{_id}` — Delete head swap task. - `POST /api/v1/headSwap/start` — Start head swap generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1HeadSwapAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/headSwap/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/headSwap/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/headSwap/allRecords` — Get all head swap records. - `GET /api/v1/headSwap/{_id}` — Get head swap task detail. - `DELETE /api/v1/headSwap/{_id}` — Delete head swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1HeadSwapBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/headSwap/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/headSwap/{_id} — Get head swap task detail
Get detailed information of a specific head swap task by ID. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid task ID format. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/headSwap/allRecords` — Get all head swap records. - `DELETE /api/v1/headSwap/{_id}` — Delete head swap task. - `POST /api/v1/headSwap/start` — Start head swap generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1HeadSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Head swap task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/headSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Invalid task ID format
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/headSwap/{_id} — Delete head swap task
Delete a head swap task by ID. **Status behavior:** - `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 - `sent/pending/processing`: Cannot be deleted, returns 400 error (task is processing) - `completed/failed/blocked` (including legacy `block`): Can be soft-deleted without this refund Deletion marks the task as deleted; it does not guarantee physical media removal. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/headSwap/allRecords` — Get all head swap records. - `GET /api/v1/headSwap/{_id}` — Get head swap task detail. - `POST /api/v1/headSwap/start` — Start head swap generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1HeadSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Head swap task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/headSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task soft-deleted successfully; the response data is an empty object, not a refund receipt
```json
{"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"}}}
```
  - `400` — Invalid task ID returns code 400; a processing task or one queued for less than 60 seconds returns code 30101
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
#### Actor Swap

##### POST /api/v1/actorSwap/start — Start actor swap task
Generate actor swap video by swapping actor from image to video. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `image_url`, `video_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/actorSwap/allRecords` — Get all task records. - `GET /api/v1/actorSwap/{_id}` — Get task details. - `DELETE /api/v1/actorSwap/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ActorSwapStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/actorSwap/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
}
JSON
```
- Responses:
  - `200` — Actor swap task started successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/actorSwap/allRecords — Get all task records
Return the authenticated user's actor-swap tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/actorSwap/{_id}` — Get task details. - `DELETE /api/v1/actorSwap/{_id}` — Delete task. - `POST /api/v1/actorSwap/start` — Start actor swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ActorSwapAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/actorSwap/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/actorSwap/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/actorSwap/allRecords` — Get all task records. - `GET /api/v1/actorSwap/{_id}` — Get task details. - `DELETE /api/v1/actorSwap/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ActorSwapBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/actorSwap/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/actorSwap/{_id} — Get task details
Return the authenticated user's actor-swap task identified by `_id`, including its current processing status and available video output. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/actorSwap/allRecords` — Get all task records. - `DELETE /api/v1/actorSwap/{_id}` — Delete task. - `POST /api/v1/actorSwap/start` — Start actor swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ActorSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/actorSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/actorSwap/{_id} — Delete task
Remove the authenticated user's actor-swap task identified by `_id` from the task history without affecting other generated videos. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/actorSwap/allRecords` — Get all task records. - `GET /api/v1/actorSwap/{_id}` — Get task details. - `POST /api/v1/actorSwap/start` — Start actor swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1ActorSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/actorSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Talking Photo

##### POST /api/v1/talkingPhoto/start — Start talking photo generation
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `image_url`, `prompt`, `negative_prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/talkingPhoto/allRecords` — Get all task records. - `GET /api/v1/talkingPhoto/{_id}` — Get task details. - `DELETE /api/v1/talkingPhoto/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingPhotoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/talkingPhoto/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Talking Photo",
  "image_url": "https://example.com/photo.jpg",
  "prompt": "Make this person smile and speak",
  "negative_prompt": "blurry, distorted"
}
JSON
```
- Responses:
  - `200` — Talking photo task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/talkingPhoto/allRecords — Get all task records
Return the authenticated user's talking-photo tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/talkingPhoto/{_id}` — Get task details. - `DELETE /api/v1/talkingPhoto/{_id}` — Delete task. - `POST /api/v1/talkingPhoto/start` — Start talking photo generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingPhotoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/talkingPhoto/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/talkingPhoto/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/talkingPhoto/allRecords` — Get all task records. - `GET /api/v1/talkingPhoto/{_id}` — Get task details. - `DELETE /api/v1/talkingPhoto/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingPhotoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/talkingPhoto/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/talkingPhoto/{_id} — Get task details
Return the authenticated user's talking-photo task identified by `_id`, including its current processing status and available video output. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/talkingPhoto/allRecords` — Get all task records. - `DELETE /api/v1/talkingPhoto/{_id}` — Delete task. - `POST /api/v1/talkingPhoto/start` — Start talking photo generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingPhotoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/talkingPhoto/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/talkingPhoto/{_id} — Delete task
Remove the authenticated user's talking-photo task identified by `_id` from the task history without affecting other generated videos. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/talkingPhoto/allRecords` — Get all task records. - `GET /api/v1/talkingPhoto/{_id}` — Get task details. - `POST /api/v1/talkingPhoto/start` — Start talking photo generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1TalkingPhotoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/talkingPhoto/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Talking Video

##### POST /api/v1/talkingVideo/start — Start talking video generation
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `video_url`, `audio_url`, `prompt`, `negative_prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/talkingVideo/allRecords` — Get all task records. - `GET /api/v1/talkingVideo/{_id}` — Get task details. - `DELETE /api/v1/talkingVideo/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingVideoStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/talkingVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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"
}
JSON
```
- Responses:
  - `200` — Talking video task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/talkingVideo/allRecords — Get all task records
Return the authenticated user's talking-video tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/talkingVideo/{_id}` — Get task details. - `DELETE /api/v1/talkingVideo/{_id}` — Delete task. - `POST /api/v1/talkingVideo/start` — Start talking video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/talkingVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/talkingVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/talkingVideo/allRecords` — Get all task records. - `GET /api/v1/talkingVideo/{_id}` — Get task details. - `DELETE /api/v1/talkingVideo/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingVideoBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/talkingVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/talkingVideo/{_id} — Get task details
Return the authenticated user's talking-video task identified by `_id`, including its current processing status and available video output. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/talkingVideo/allRecords` — Get all task records. - `DELETE /api/v1/talkingVideo/{_id}` — Delete task. - `POST /api/v1/talkingVideo/start` — Start talking video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/talkingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/talkingVideo/{_id} — Delete task
Remove the authenticated user's talking-video task identified by `_id` from the task history without affecting other generated videos. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/talkingVideo/allRecords` — Get all task records. - `GET /api/v1/talkingVideo/{_id}` — Get task details. - `POST /api/v1/talkingVideo/start` — Start talking video generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1TalkingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/talkingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Virtual Try-On

##### POST /api/v1/virtualTryOn/start — Start virtual try-on task
Start a virtual try-on task with clothing images on person photos. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `image_urls`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records. - `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail. - `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VirtualTryOnStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/virtualTryOn/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Summer Dress Try-On",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/dress.jpg"
  ],
  "timeout": 120
}
JSON
```
- Responses:
  - `200` — Virtual try-on task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/virtualTryOn/allRecords — Get all virtual try-on records
Retrieve paginated list of virtual try-on tasks for the current user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail. - `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task. - `POST /api/v1/virtualTryOn/start` — Start virtual try-on task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VirtualTryOnAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number for pagination
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/virtualTryOn/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/virtualTryOn/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records. - `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail. - `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VirtualTryOnBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/virtualTryOn/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/virtualTryOn/{_id} — Get virtual try-on task detail
Retrieve detailed information of a virtual try-on task by its ID. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records. - `DELETE /api/v1/virtualTryOn/{_id}` — Delete virtual try-on task. - `POST /api/v1/virtualTryOn/start` — Start virtual try-on task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VirtualTryOnId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Virtual try-on task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/virtualTryOn/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/virtualTryOn/{_id} — Delete virtual try-on task
Remove the authenticated user's virtual try-on task identified by `_id` from the task history without affecting other generated try-on results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/virtualTryOn/allRecords` — Get all virtual try-on records. - `GET /api/v1/virtualTryOn/{_id}` — Get virtual try-on task detail. - `POST /api/v1/virtualTryOn/start` — Start virtual try-on task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1VirtualTryOnId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Virtual try-on task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/virtualTryOn/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Virtual try-on task deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Motion Transfer

##### POST /api/v1/motionTransfer/start — Start motion transfer task
Start a motion transfer task to transfer motion from video to image. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `image_url`, `video_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records. - `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail. - `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1MotionTransferStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/motionTransfer/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "image_url": "https://example.com/person.jpg",
  "video_url": "https://example.com/dance.mp4"
}
JSON
```
- Responses:
  - `200` — Motion transfer task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/motionTransfer/allRecords — Get all motion transfer records
Retrieve paginated list of motion transfer tasks for the current user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail. - `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task. - `POST /api/v1/motionTransfer/start` — Start motion transfer task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1MotionTransferAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number for pagination
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/motionTransfer/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/motionTransfer/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records. - `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail. - `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1MotionTransferBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/motionTransfer/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/motionTransfer/{_id} — Get motion transfer task detail
Retrieve detailed information of a motion transfer task by its ID. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records. - `DELETE /api/v1/motionTransfer/{_id}` — Delete motion transfer task. - `POST /api/v1/motionTransfer/start` — Start motion transfer task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1MotionTransferId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Motion transfer task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/motionTransfer/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/motionTransfer/{_id} — Delete motion transfer task
Remove the authenticated user's motion-transfer task identified by `_id` from the task history without affecting other generated videos. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/motionTransfer/allRecords` — Get all motion transfer records. - `GET /api/v1/motionTransfer/{_id}` — Get motion transfer task detail. - `POST /api/v1/motionTransfer/start` — Start motion transfer task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1MotionTransferId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Motion transfer task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/motionTransfer/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Motion transfer task deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Product Avatar

##### POST /api/v1/productAvatar/start — Generate product avatar with AI (Async)
Generate a product image by combining product and person images with customizable positioning and styling. This endpoint returns an image, not a video. **⚠️ IMPORTANT: This is an ASYNCHRONOUS operation** ### Async Workflow 1. **Submit Task** - Call this endpoint to create a new generation task - Returns immediately with task `_id` and status `initialized` - Task is queued for processing 2. **Processing States** - The task goes through these states: - `initialized` → Task created, waiting in queue - `sent` → Task submitted to AI service - `pending` → Task received by AI service - `processing` → AI is generating the image - `completed` → Generation finished successfully - `failed` → Generation failed (check `failed_message`) 3. **Get Results** - Poll for task status and results: - Use `GET /api/v1/productAvatar/{_id}` to check status - Use `GET /api/v1/productAvatar/allRecords` to list all tasks - When `current_status` is `completed`, `result_image_url` contains the generated image 4. **Timeout Handling**: - Tasks timeout after 2 hours and automatically fail - Credits are automatically refunded on timeout or failure ### Best Practices - Poll every 3-5 seconds to check task status - Handle both `completed` and `failed` states - Store the returned `_id` to query results later. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `image_urls`, `product_rect`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters or missing required fields. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks. - `GET /api/v1/productAvatar/{_id}` — Query task status and get result. - `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ProductAvatarStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/productAvatar/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
}
JSON
```
- Responses:
  - `200` — Product avatar generation started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters or missing required fields
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/productAvatar/allRecords — List all product avatar tasks
Retrieve a paginated list of all product avatar generation tasks for the authenticated user. Use this endpoint to monitor task progress and retrieve results. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/productAvatar/{_id}` — Query task status and get result. - `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task. - `POST /api/v1/productAvatar/start` — Generate product avatar with AI (Async) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ProductAvatarAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number (starting from 1)
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/productAvatar/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/productAvatar/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks. - `GET /api/v1/productAvatar/{_id}` — Query task status and get result. - `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ProductAvatarBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/productAvatar/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/productAvatar/{_id} — Query task status and get result
Retrieve detailed information about a specific product avatar generation task. Use this endpoint to poll for task status and get the result when completed. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks. - `DELETE /api/v1/productAvatar/{_id}` — Delete a product avatar task. - `POST /api/v1/productAvatar/start` — Generate product avatar with AI (Async) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ProductAvatarId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID returned from the start endpoint
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/productAvatar/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/productAvatar/{_id} — Delete a product avatar task
Soft delete a product avatar task. The task data will be marked as deleted but not removed from the database. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Task not found. ### Related Operations - `GET /api/v1/productAvatar/allRecords` — List all product avatar tasks. - `GET /api/v1/productAvatar/{_id}` — Query task status and get result. - `POST /api/v1/productAvatar/start` — Generate product avatar with AI (Async) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1ProductAvatarId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/productAvatar/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Task not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Photobook

##### POST /api/v1/userPhotobook/start — Start photobook generation
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `face_image_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userPhotobook/allRecords` — Get photobook records. - `GET /api/v1/userPhotobook/{id}` — Get photobook record detail. - `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserPhotobookStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userPhotobook/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "face_image_url": "https://example.com/face.jpg"
}
JSON
```
- Responses:
  - `200` — Photobook task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userPhotobook/allRecords — Get photobook records
Return the authenticated user's photobook-generation records using `pageNum` and `pageSize`, with newest records presented first. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid pagination parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userPhotobook/{id}` — Get photobook record detail. - `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record. - `POST /api/v1/userPhotobook/start` — Start photobook generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserPhotobookAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userPhotobook/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid pagination parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userPhotobook/batchDetail — Batch query task details
Query details for multiple photobook tasks at once by providing an array of task IDs. Only records owned by the authenticated user are returned. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userPhotobook/allRecords` — Get photobook records. - `GET /api/v1/userPhotobook/{id}` — Get photobook record detail. - `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserPhotobookBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userPhotobook/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userPhotobook/{id} — Get photobook record detail
Get one photobook record by id. The endpoint also syncs the latest pipeline status before returning. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Record not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userPhotobook/allRecords` — Get photobook records. - `DELETE /api/v1/userPhotobook/{id}` — Delete photobook record. - `POST /api/v1/userPhotobook/start` — Start photobook generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserPhotobookId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Photobook record id
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userPhotobook/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Record not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userPhotobook/{id} — Delete photobook record
Remove the photobook record identified by `id` only when it belongs to the authenticated user; unrelated photobook records are unchanged. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Photobook record cannot be deleted in its current status (for example, processing) - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Not Found - Photobook record does not exist or is not accessible by the current user. ### Related Operations - `GET /api/v1/userPhotobook/allRecords` — Get photobook records. - `GET /api/v1/userPhotobook/{id}` — Get photobook record detail. - `POST /api/v1/userPhotobook/start` — Start photobook generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserPhotobookId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Photobook record id
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userPhotobook/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Photobook record deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Photobook record cannot be deleted in its current status (for example, processing)
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Not Found - Photobook record does not exist or is not accessible by the current user
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

### Avatar & Video
#### Generate Avatar Videos

##### POST /api/v1/anchor/list — List available avatars
Returns the system and user-specific avatars available to the authenticated API user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorList`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/anchor/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "web_type": "a2e"
}
JSON
```
- Responses:
  - `200` — Operation completed successfully
```json
{"$ref":"#/components/schemas/AvatarListResponse"}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/video/generate — Generate AI video with avatar
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `anchor_id`, `anchor_type`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters or missing required audio source. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/video/detail` — detail. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VideoGenerate`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/video/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters or missing required audio source
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/video/detail — Get record details
detail. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `video_id`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `POST /api/v1/video/generate` — Generate AI video with avatar. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VideoDetail`
- Request parameters:
  - `video_id` (query, required; string; example: `507f1f77bcf86cd799439011`) — Video task ID returned by the generate endpoint
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/video/detail?video_id=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Operation completed successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Create Avatars

##### POST /api/v1/custom_avatar/add — Create a custom avatar
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `video_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_avatar/list` — List custom avatars. - `PUT /api/v1/custom_avatar/{_id}` — Update item. - `POST /api/v1/custom_avatar/del` — Delete a custom avatar. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomAvatarAdd`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_avatar/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "video_url": "https://example.com/avatar.mp4"
}
JSON
```
- Responses:
  - `200` — Avatar created, or the existing avatar returned for the same video twin
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/custom_avatar/list — List custom avatars
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `PUT /api/v1/custom_avatar/{_id}` — Update item. - `POST /api/v1/custom_avatar/add` — Create a custom avatar. - `POST /api/v1/custom_avatar/del` — Delete a custom avatar. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomAvatarList`
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_avatar/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Custom avatars retrieved successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/custom_avatar/del — Delete a custom avatar
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `_id`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_avatar/list` — List custom avatars. - `PUT /api/v1/custom_avatar/{_id}` — Update item. - `POST /api/v1/custom_avatar/add` — Create a custom avatar. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomAvatarDel`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"_id":{"type":"string","description":"ID of the authenticated user's avatar to delete.","example":"507f1f77bcf86cd799439011"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_avatar/del" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Avatar deleted; `data` is null when no active avatar with this ID belongs to the caller
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/custom_avatar/all_tags — List all tags
Return the distinct tags available for organizing and filtering the authenticated user's custom avatars. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_avatar/list` — List custom avatars. - `PUT /api/v1/custom_avatar/{_id}` — Update item. - `POST /api/v1/custom_avatar/add` — Create a custom avatar. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1CustomAvatarAllTags`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/custom_avatar/all_tags" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Operation completed successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### PUT /api/v1/custom_avatar/{_id} — Update item
Update editable metadata for the authenticated user's custom avatar identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Updates the identified resource using the fields accepted by the request schema and the operation's access controls. - Fields omitted from the request retain their existing values unless the schema states otherwise. - Read the returned record or call the detail operation to confirm the persisted state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_avatar/list` — List custom avatars. - `POST /api/v1/custom_avatar/add` — Create a custom avatar. - `POST /api/v1/custom_avatar/del` — Delete a custom avatar. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1CustomAvatarId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X PUT "https://headswap.app/api/v1/custom_avatar/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item updated successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Background Library

##### POST /api/v1/custom_back/add — Add new custom background
Create a custom background in the authenticated user's library from the submitted background image and metadata. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `img_url`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters or missing img_url. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_back/list` — List items. - `POST /api/v1/custom_back/del` — del. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackAdd`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_back/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "img_url": "https://example.com/background.jpg"
}
JSON
```
- Responses:
  - `200` — Background item created successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters or missing img_url
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/custom_back/list — Create/Run list
Return the authenticated user's custom backgrounds using the submitted pagination and filtering controls. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_back/add` — Add new custom background. - `POST /api/v1/custom_back/del` — del. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackList`
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_back/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item retrieved successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/custom_back/del — Delete record
Remove the authenticated user's custom background identified by the submitted record ID. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `_id`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_back/list` — List items. - `POST /api/v1/custom_back/add` — Add new custom background. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackDel`
- Request schema (nested fields and conditions):
```json
{"allOf":[{"type":"object","required":["_id"],"properties":{"_id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"}}}]}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_back/del" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Operation completed successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Video Twin

##### GET /api/v1/userVideoTwin/uploadStatus — Get video twin upload status
Check the upload status of video twin files for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinUploadStatus`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVideoTwin/uploadStatus" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Upload status retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userVideoTwin/userRecords — Get user video twin records
Return every video-twin record available to the authenticated user, including its current training state and result metadata. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinUserRecords`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVideoTwin/userRecords" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Video twin records retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/remove — Remove video twin
Remove the video twin identified in the request from the authenticated user's collection without affecting unrelated records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `_id`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid video twin ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinRemove`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"_id":{"type":"string","description":"ID of the video twin to remove","example":"507f1f77bcf86cd799439011"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userVideoTwin/remove" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Video twin removed successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid video twin ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userVideoTwin/records — Get video twin records
Retrieve paginated video twin records with optional filters. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`, `status`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. - `GET /api/v1/userVideoTwin/uploadStatus` — Get video twin upload status. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of records per page
  - `status` (query, optional; string; allowed: `pending`, `processing`, `completed`, `failed`; example: `completed`) — Filter by status
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVideoTwin/records?pageNum=1&pageSize=10&status=completed" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Records retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/startTraining — Create an image or video avatar
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinStartTraining`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userVideoTwin/startTraining" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Avatar created; video deep training starts immediately only when skipPreview=true.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/continueTraining — Start video deep training
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `_id`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid video twin ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinContinueTraining`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"_id":{"type":"string","description":"ID of the video twin to continue training","example":"507f1f77bcf86cd799439011"}},"required":["_id"],"example":{"_id":"507f1f77bcf86cd799439011"}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userVideoTwin/continueTraining" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Training continued successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid video twin ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userVideoTwin/trainingRecords — Get training records
Retrieve all video twin training records for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinTrainingRecords`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVideoTwin/trainingRecords" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Training records retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userVideoTwin/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/eyeContact — Start eye contact enhancement
Enhance video twin with improved eye contact using AI processing. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinEyeContact`
- Request schema (nested fields and conditions):
```json
{"type":"object","properties":{"_id":{"type":"string","description":"ID of the video twin to enhance","example":"507f1f77bcf86cd799439011"}},"required":[],"example":{}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userVideoTwin/eyeContact" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Eye contact enhancement started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

### Voice & Audio
#### TTS and Voice Clone

##### POST /api/v1/anchor/tts_list — List system voices (TTS presets)
List available system TTS voices/presets for the current user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/anchor/language_list` — List supported languages/regions for voices. - `POST /api/v1/anchor/voice_list` — List available voices by country/region. - `GET /api/v1/anchor/voice_list` — List available voices (GET) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorTtsList`
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/anchor/tts_list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Voice preset list
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/anchor/language_list — List supported languages/regions for voices
List supported language and region options. Optional `voice_map_type` changes display labels; it does not filter the returned locales. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/anchor/tts_list` — List system voices (TTS presets) - `POST /api/v1/anchor/voice_list` — List available voices by country/region. - `GET /api/v1/anchor/voice_list` — List available voices (GET) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorLanguageList`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/anchor/language_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "voice_map_type": "en-US"
}
JSON
```
- Responses:
  - `200` — Language/region list
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/anchor/voice_list — List available voices by country/region
List available voices filtered by `country`, `region`, and `voice_map_type`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/anchor/tts_list` — List system voices (TTS presets) - `POST /api/v1/anchor/language_list` — List supported languages/regions for voices. - `GET /api/v1/anchor/voice_list` — List available voices (GET) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorVoiceList`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/anchor/voice_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "country": "en",
  "region": "US",
  "voice_map_type": "en-US"
}
JSON
```
- Responses:
  - `200` — Voice list
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/anchor/voice_list — List available voices (GET)
List available voices grouped by gender with the current account's dynamic ttsRate. Defaults: country=en, region=US, voice_map_type=en-US. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `country`, `region`, `voice_map_type`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/anchor/tts_list` — List system voices (TTS presets) - `POST /api/v1/anchor/language_list` — List supported languages/regions for voices. - `POST /api/v1/anchor/voice_list` — List available voices by country/region. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1AnchorVoiceList`
- Request parameters:
  - `country` (query, optional; string; default: `en`; example: `en`) — country parameter
  - `region` (query, optional; string; default: `US`; example: `US`) — region parameter
  - `voice_map_type` (query, optional; string; default: `en-US`; example: `en-US`) — voice_map_type parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/anchor/voice_list?country=en&region=US&voice_map_type=en-US" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/video/send_tts — Generate text-to-speech audio
Convert text to speech using AI voices with customizable parameters. ### Voice Selection Provide exactly one of `tts_id` (system voice) or `user_voice_id` (custom cloned voice). Do not send both: synthesis would use the `tts_id` voice while locale defaults and billing follow `user_voice_id`. - `tts_id`: Use built-in system voice (400+ voices available) - `user_voice_id`: Use your own custom cloned voice; omitted `country` and `region` default to `en-US` ### Billing System voice lists return the current account's `ttsRate` in credits per 10 seconds. Charges are based on the generated audio duration: `ceil(duration / 10) * ttsRate`. A valid zero rate means no credits are charged. Fetch the selected voice's current rate before submitting; generated duration is unknown before synthesis, so this rate is not a total-price quote. ### Text Limitations - **API token users**: No local 3000-unit text limit is applied by this controller - **Web users**: Maximum 3000 weighted units after pause tags are removed - 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 ### Rate Limiting & Captcha For non-API users, captcha verification may be required after frequent usage: - Use `type` parameter to specify captcha type (`turnstile` or `aliyun_captcha`) - Provide corresponding `turnstile_token` or `captchaVerifyParam` when captcha is required - API token users skip captcha verification If generated audio needs a duration probe and that probe fails, msg includes the audio source failure reason. Invalid audio URLs are cached for 180 seconds; cached failures return the same reason without probing again. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `msg`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid request parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `500` — Generated audio duration probe failed; msg includes the audio source failure reason. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VideoSendTts`
- Request schema (nested fields and conditions):
```json
{"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"}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/video/send_tts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "msg": "Welcome. Let's start your AI journey.",
  "tts_id": "66dc3c1b7dc1f1c483cc5ab8",
  "speechRate": 1
}
JSON
```
- Responses:
  - `200` — Text-to-speech generation successful
```json
{"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"}}}
```
  - `400` — Invalid request parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `500` — Generated audio duration probe failed; msg includes the audio source failure reason.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/tts/preview/list — Get TTS preview list
Return the authenticated user's non-deleted TTS preview records created during the last 24 hours, ordered for recent-preview playback. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageSize`, `current`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/tts/preview/{id}` — Delete TTS preview record. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TtsPreviewList`
- Request parameters:
  - `pageSize` (query, optional; integer; default: `20`; min: 1; max: 100; example: `20`) — Number of items per page
  - `current` (query, optional; integer; default: `1`; min: 1; example: `1`) — Current page number
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/tts/preview/list?pageSize=20&current=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — TTS preview list retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/tts/preview/{id} — Delete TTS preview record
Soft-delete the authenticated user's TTS preview record identified by `id`; the underlying audio object is not physically removed by this operation. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Record not found. ### Related Operations - `GET /api/v1/tts/preview/list` — Get TTS preview list. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1TtsPreviewId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — TTS preview record ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/tts/preview/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — TTS preview record deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Record not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVoice/training — Start voice training
Create an asynchronous custom-voice training task from the submitted voice samples. - **Concurrency:** A user may submit only one training request at a time; concurrent submissions are rejected by the service guard. - **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. - **Status:** After creation, poll `GET /api/v1/userVoice/trainingRecord` and inspect `current_status` for progress. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `voice_urls`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid training data. - `401` — Unauthorized - Invalid or missing JWT token. - `403` — Forbidden - Voice clone limit exceeded. ### Related Operations - `DELETE /api/v1/userVoice/{_id}` — Delete voice training record. - `GET /api/v1/userVoice/{_id}` — Get voice training record detail. - `PUT /api/v1/userVoice/{_id}` — Update voice training record name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVoiceTraining`
- Request schema (nested fields and conditions):
```json
{"allOf":[{"$ref":"#/components/schemas/UserVoiceTrainingRequest"},{"$ref":"#/components/schemas/WebhookInput"}]}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userVoice/training" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Custom Voice",
  "voice_urls": [
    "https://example.com/audio1.wav",
    "https://example.com/audio2.wav"
  ]
}
JSON
```
- Responses:
  - `200` — Voice training record created successfully
```json
{"$ref":"#/components/schemas/SuccessUserVoiceResponse"}
```
  - `400` — Bad Request - Invalid training data
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `403` — Forbidden - Voice clone limit exceeded
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userVoice/trainingRecord — Get voice training records
Return the authenticated user's voice-training records across queued, processing, completed, and failed states. - **Ordering:** Records are sorted by `createdAt` in descending order, newest first. - **Status values:** `current_status` may be `sent`, `pendding`, `processing`, `completed`, or `failed`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/userVoice/{_id}` — Delete voice training record. - `GET /api/v1/userVoice/{_id}` — Get voice training record detail. - `PUT /api/v1/userVoice/{_id}` — Update voice training record name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVoiceTrainingRecord`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVoice/trainingRecord" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"$ref":"#/components/schemas/SuccessUserVoiceListResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userVoice/completedRecord — Get completed voice training records
Return only the authenticated user's completed voice-training records (`current_status=completed`). - **Ordering:** Records are sorted by `createdAt` in descending order, newest first. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/userVoice/{_id}` — Delete voice training record. - `GET /api/v1/userVoice/{_id}` — Get voice training record detail. - `PUT /api/v1/userVoice/{_id}` — Update voice training record name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVoiceCompletedRecord`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVoice/completedRecord" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"$ref":"#/components/schemas/SuccessUserVoiceListResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userVoice/{_id} — Delete voice training record
Soft-delete the authenticated user's voice-training record by setting `deleted=true`; the stored record is not physically removed. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid voice training record ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVoice/{_id}` — Get voice training record detail. - `PUT /api/v1/userVoice/{_id}` — Update voice training record name. - `POST /api/v1/userVoice/training` — Start voice training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserVoiceId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — MongoDB ObjectId of the voice training record
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userVoice/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `400` — Invalid voice training record ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userVoice/{_id} — Get voice training record detail
Return one voice-training record owned by the authenticated user, identified by `_id`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid _id. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/userVoice/{_id}` — Delete voice training record. - `PUT /api/v1/userVoice/{_id}` — Update voice training record name. - `POST /api/v1/userVoice/training` — Start voice training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVoiceId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — MongoDB ObjectId of the voice training record
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVoice/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"$ref":"#/components/schemas/SuccessUserVoiceResponse"}
```
  - `400` — Bad Request - Invalid _id
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### PUT /api/v1/userVoice/{_id} — Update voice training record name
Rename the authenticated user's voice-training record identified by `_id`; no training inputs or status fields are changed. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. - Send an `application/json` body. Required fields: `name`. ### Behavior - Updates the identified resource using the fields accepted by the request schema and the operation's access controls. - Fields omitted from the request retain their existing values unless the schema states otherwise. - Read the returned record or call the detail operation to confirm the persisted state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid voice training record ID or request body. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `DELETE /api/v1/userVoice/{_id}` — Delete voice training record. - `GET /api/v1/userVoice/{_id}` — Get voice training record detail. - `POST /api/v1/userVoice/training` — Start voice training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1UserVoiceId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — MongoDB ObjectId of the voice training record
- Request schema (nested fields and conditions):
```json
{"$ref":"#/components/schemas/UserVoiceUpdateRequest"}
```
- Example request:
```bash
curl -X PUT "https://headswap.app/api/v1/userVoice/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Renamed Voice"
}
JSON
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid voice training record ID or request body
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/seedAudio/speakers — List Seed Audio speakers
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Reads the requested information without creating a generation task. - Use the returned fields as documented; availability may depend on the caller and current resource state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - A bearer token was supplied but is invalid, or the Cheap boundary received no token. - `503` — Speaker list credentials are not configured or the provider is temporarily unavailable. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SeedAudioSpeakers`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedAudio/speakers" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Speaker list retrieved successfully
```json
{"$ref":"#/components/schemas/SeedAudioSpeakerListResponse"}
```
  - `401` — Unauthorized - A bearer token was supplied but is invalid, or the Cheap boundary received no token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Speaker list credentials are not configured or the provider is temporarily unavailable
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/seedAudio/start — Start an asynchronous Seed Audio task
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`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `text_prompt`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Too many unfinished Seed Audio tasks for the current user. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SeedAudioStart`
- Request schema (nested fields and conditions):
```json
{"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"}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/seedAudio/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "text_prompt": "Gentle rain in a quiet forest",
  "references": []
}
JSON
```
- Responses:
  - `200` — Task accepted and queued
```json
{"$ref":"#/components/schemas/SeedAudioTaskResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Too many unfinished Seed Audio tasks for the current user
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/seedAudio/generate — Generate custom audio with Seed Audio
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `text_prompt`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Too many unfinished Seed Audio tasks for the current user. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SeedAudioGenerate`
- Request schema (nested fields and conditions):
```json
{"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"}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/seedAudio/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "text_prompt": "Gentle rain in a quiet forest",
  "references": []
}
JSON
```
- Responses:
  - `200` — Task accepted and queued
```json
{"$ref":"#/components/schemas/SeedAudioTaskResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Too many unfinished Seed Audio tasks for the current user
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/seedAudio/allRecords — Get all Seed Audio records
Retrieve the paginated Seed Audio task history of the current user, newest first. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. - `GET /api/v1/seedAudio/speakers` — List Seed Audio speakers. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SeedAudioAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number for pagination
  - `pageSize` (query, optional; integer; default: `20`; min: 1; max: 50; example: `20`) — Number of items per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedAudio/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"$ref":"#/components/schemas/SeedAudioTaskListResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/seedAudio/batchDetail — Batch query Seed Audio task details
Query up to 200 tasks of the current user at once by task ID. Unknown or foreign IDs are silently omitted. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SeedAudioBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/seedAudio/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"$ref":"#/components/schemas/SeedAudioTaskArrayResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/seedAudio/{_id} — Get Seed Audio task detail
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Seed Audio record not found. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `DELETE /api/v1/seedAudio/{_id}` — Delete Seed Audio task. - `GET /api/v1/seedAudio/speakers` — List Seed Audio speakers. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SeedAudioId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Seed Audio task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/seedAudio/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"$ref":"#/components/schemas/SeedAudioTaskResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Seed Audio record not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/seedAudio/{_id} — Delete Seed Audio task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — The task is still processing and cannot be deleted yet. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — Seed Audio record not found. ### Related Operations - `GET /api/v1/seedAudio/allRecords` — Get all Seed Audio records. - `GET /api/v1/seedAudio/{_id}` — Get Seed Audio task detail. - `GET /api/v1/seedAudio/speakers` — List Seed Audio speakers. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1SeedAudioId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Seed Audio task ID
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/seedAudio/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Seed Audio task deleted successfully
```json
{"$ref":"#/components/schemas/SeedAudioTaskResponse"}
```
  - `400` — The task is still processing and cannot be deleted yet
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — Seed Audio record not found
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### AI Dubbing

##### POST /api/v1/userDubbing/startDubbing — Start video dubbing task
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `source_url`, `source_lang`, `target_lang`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userDubbing/allRecords` — Get all task records. - `GET /api/v1/userDubbing/{_id}` — Get task details. - `DELETE /api/v1/userDubbing/{_id}` — Delete dubbing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserDubbingStartDubbing`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userDubbing/startDubbing" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Dubbing video from English to Spanish",
  "source_url": "https://example.com/video.mp4",
  "source_lang": "en",
  "target_lang": "es"
}
JSON
```
- Responses:
  - `200` — Dubbing task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userDubbing/allRecords — Get all task records
Return the authenticated user's dubbing tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userDubbing/{_id}` — Get task details. - `DELETE /api/v1/userDubbing/{_id}` — Delete dubbing task. - `POST /api/v1/userDubbing/startDubbing` — Start video dubbing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserDubbingAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userDubbing/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userDubbing/{_id} — Get task details
Return the authenticated user's dubbing task identified by `_id`, including its current processing status and available output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userDubbing/allRecords` — Get all task records. - `DELETE /api/v1/userDubbing/{_id}` — Delete dubbing task. - `POST /api/v1/userDubbing/startDubbing` — Start video dubbing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserDubbingId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userDubbing/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userDubbing/{_id} — Delete dubbing task
Remove the authenticated user's dubbing task identified by `_id` from the task history without affecting other dubbing records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userDubbing/allRecords` — Get all task records. - `GET /api/v1/userDubbing/{_id}` — Get task details. - `POST /api/v1/userDubbing/startDubbing` — Start video dubbing task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserDubbingId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the dubbing task
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userDubbing/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### ThinkSound

##### POST /api/v1/thinkSound/start — Start ThinkSound generation
Generate audio-visual content from video using AI with customizable parameters. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `video_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters or video format. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records. - `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task. - `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ThinkSoundStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/thinkSound/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "video_url": "https://example.com/video.mp4"
}
JSON
```
- Responses:
  - `200` — ThinkSound generation started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters or video format
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/thinkSound/{_id} — Delete ThinkSound task
Remove the authenticated user's ThinkSound generation task identified by `_id` from the task history without affecting other generated-audio records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records. - `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details. - `POST /api/v1/thinkSound/start` — Start ThinkSound generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1ThinkSoundId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the ThinkSound task to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/thinkSound/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — ThinkSound task deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/thinkSound/{_id} — Get ThinkSound task details
Retrieve detailed information about a specific ThinkSound generation task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID format. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records. - `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task. - `POST /api/v1/thinkSound/start` — Start ThinkSound generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ThinkSoundId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the ThinkSound task
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/thinkSound/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID format
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/thinkSound/allRecords — Get all ThinkSound records
Retrieve paginated list of ThinkSound generation tasks for the authenticated user. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid pagination parameters. - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task. - `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details. - `POST /api/v1/thinkSound/start` — Start ThinkSound generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ThinkSoundAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/thinkSound/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid pagination parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/thinkSound/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/thinkSound/allRecords` — Get all ThinkSound records. - `DELETE /api/v1/thinkSound/{_id}` — Delete ThinkSound task. - `GET /api/v1/thinkSound/{_id}` — Get ThinkSound task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ThinkSoundBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/thinkSound/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

### Post Processing
#### Caption Removal

##### POST /api/v1/userCaptionRemoval/start — Start caption removal task
Create an asynchronous caption-removal task for the submitted source video and return the record used to monitor processing. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `source_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records. - `GET /api/v1/userCaptionRemoval/{_id}` — Get task details. - `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserCaptionRemovalStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userCaptionRemoval/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Remove captions from video",
  "source_url": "https://example.com/video.mp4"
}
JSON
```
- Responses:
  - `200` — Caption removal task started successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userCaptionRemoval/allRecords — Get all task records
Return the authenticated user's caption-removal tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userCaptionRemoval/{_id}` — Get task details. - `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task. - `POST /api/v1/userCaptionRemoval/start` — Start caption removal task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserCaptionRemovalAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userCaptionRemoval/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userCaptionRemoval/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records. - `GET /api/v1/userCaptionRemoval/{_id}` — Get task details. - `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserCaptionRemovalBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userCaptionRemoval/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userCaptionRemoval/{_id} — Get task details
Return the authenticated user's caption-removal task identified by `_id`, including its current processing status and available output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records. - `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task. - `POST /api/v1/userCaptionRemoval/start` — Start caption removal task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserCaptionRemovalId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userCaptionRemoval/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userCaptionRemoval/{_id} — Delete caption removal task
Remove the authenticated user's caption-removal task identified by `_id` from the task history without affecting other records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid task ID. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records. - `GET /api/v1/userCaptionRemoval/{_id}` — Get task details. - `POST /api/v1/userCaptionRemoval/start` — Start caption removal task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserCaptionRemovalId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the caption removal task
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userCaptionRemoval/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid task ID
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userCaptionRemoval/retry — Retry existing media tasks
Retry an owned, non-deleted task with _id, or a batch with _ids. When both are supplied, _ids takes precedence. Batch IDs are deduplicated case-insensitively and results retain their first-occurrence order. Records are queried in chunks of 50 and submissions run with at most four concurrent tasks per request. There is no new request-size limit; an empty batch succeeds without submitting work. All batch items are awaited, even after failures. Any failure preserves the top-level error code and HTTP status of the first failed item in input order; data.results also includes successful items so clients can avoid resubmitting them. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Requests another processing attempt for an eligible failed task. - Eligibility, charging, and state transitions follow the task-specific rules exposed by the response. - Continue monitoring the same or returned task identifier after the retry is accepted. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid request; no tasks submitted. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — A task is absent, deleted, or not owned; batch data.results reports every attempted item. - `500` — Existing upstream or database error response, with data.results for batch requests. ### Related Operations - `GET /api/v1/userCaptionRemoval/allRecords` — Get all task records. - `GET /api/v1/userCaptionRemoval/{_id}` — Get task details. - `DELETE /api/v1/userCaptionRemoval/{_id}` — Delete caption removal task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserCaptionRemovalRetry`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userCaptionRemoval/retry" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Tasks submitted successfully (code 0).
```json
{"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"}}}
```
  - `400` — Invalid request; no tasks submitted.
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — A task is absent, deleted, or not owned; batch data.results reports every attempted item.
```json
{"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` — Existing upstream or database error response, with data.results for batch requests.
```json
{"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"}}}
```
#### Upscale

##### POST /api/v1/userUpscale/start — Start upscale task
Create an asynchronous media-upscaling task for the submitted image or video source and return the record used to monitor processing. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `source_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - Non-success responses use the published error envelope; surface the returned message and code to diagnostics. ### Related Operations - `GET /api/v1/userUpscale/allRecords` — Get all task records. - `GET /api/v1/userUpscale/{_id}` — Get task details. - `DELETE /api/v1/userUpscale/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserUpscaleStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userUpscale/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "source_url": "https://example.com/video.mp4"
}
JSON
```
- Responses:
  - `200` — Upscale task created
```json
{"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"}}}
```

##### GET /api/v1/userUpscale/allRecords — Get all task records
Return the authenticated user's media-upscaling tasks, newest first, using the requested page number and page size. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userUpscale/{_id}` — Get task details. - `DELETE /api/v1/userUpscale/{_id}` — Delete task. - `POST /api/v1/userUpscale/start` — Start upscale task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserUpscaleAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userUpscale/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userUpscale/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `ids`. ### Behavior - Fetches several task records in one request, reducing the number of individual detail calls. - Results remain subject to the same authentication and ownership checks as single-record lookups. - Match returned records by their identifiers instead of relying on response ordering. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userUpscale/allRecords` — Get all task records. - `GET /api/v1/userUpscale/{_id}` — Get task details. - `DELETE /api/v1/userUpscale/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserUpscaleBatchDetail`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userUpscale/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userUpscale/{_id} — Get task details
Return the authenticated user's media-upscaling task identified by `_id`, including its current processing status and available output fields. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `GET /api/v1/userUpscale/allRecords` — Get all task records. - `DELETE /api/v1/userUpscale/{_id}` — Delete task. - `POST /api/v1/userUpscale/start` — Start upscale task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserUpscaleId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userUpscale/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 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.
```json
{"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"}}}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### DELETE /api/v1/userUpscale/{_id} — Delete task
Remove the authenticated user's media-upscaling task identified by `_id` from the task history without affecting other records. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Deletes or marks the selected resource as deleted according to the endpoint's documented lifecycle rules. - Use the resource identifier from a list, creation, or detail response; deleting one resource does not affect unrelated records. - Do not assume an in-progress task can be cancelled unless the endpoint explicitly documents that behavior. ### Response - A `200` response confirms that the deletion request was applied to the selected record. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userUpscale/allRecords` — Get all task records. - `GET /api/v1/userUpscale/{_id}` — Get task details. - `POST /api/v1/userUpscale/start` — Start upscale task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserUpscaleId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://headswap.app/api/v1/userUpscale/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userUpscale/retry — Retry existing media tasks
Retry an owned, non-deleted task with _id, or a batch with _ids. When both are supplied, _ids takes precedence. Batch IDs are deduplicated case-insensitively and results retain their first-occurrence order. Records are queried in chunks of 50 and submissions run with at most four concurrent tasks per request. There is no new request-size limit; an empty batch succeeds without submitting work. All batch items are awaited, even after failures. Any failure preserves the top-level error code and HTTP status of the first failed item in input order; data.results also includes successful items so clients can avoid resubmitting them. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Requests another processing attempt for an eligible failed task. - Eligibility, charging, and state transitions follow the task-specific rules exposed by the response. - Continue monitoring the same or returned task identifier after the retry is accepted. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid request; no tasks submitted. - `401` — Unauthorized - Invalid or missing JWT token. - `404` — A task is absent, deleted, or not owned; batch data.results reports every attempted item. - `500` — Existing upstream or database error response, with data.results for batch requests. ### Related Operations - `GET /api/v1/userUpscale/allRecords` — Get all task records. - `GET /api/v1/userUpscale/{_id}` — Get task details. - `DELETE /api/v1/userUpscale/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserUpscaleRetry`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/userUpscale/retry" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Success, or an existing business rejection (nonzero code); V2 upscale retries still require creating a new task.
```json
{"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"}}}
```
  - `400` — Invalid request; no tasks submitted.
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `404` — A task is absent, deleted, or not owned; batch data.results reports every attempted item.
```json
{"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` — Existing upstream or database error response, with data.results for batch requests.
```json
{"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"}}}
```
#### Image Background Removal

##### POST /api/v1/imageBackgroundRemoval/start — Start background removal for any image subject
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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `image_url`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Invalid source image or resolution. - `401` — Unauthorized - Invalid or missing JWT token. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ImageBackgroundRemovalStart`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/imageBackgroundRemoval/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "image_url": "https://example.com/image.jpg"
}
JSON
```
- Responses:
  - `200` — Task accepted; data includes _id, current_status, coins, and detail_url.
```json
{"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"}}}
```
  - `400` — Invalid source image or resolution.
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

### Utilities
#### Miscellaneous

##### POST /api/v1/r2/get_upload_presigned_url — Get pre-signed upload URL
Legacy endpoint for generating a pre-signed R2 PUT URL. Prefer /api/v1/r2/upload-presigned-url for new integrations. If bucket is omitted, files are uploaded to 3days-apac by default. urlPrefix changes the leading object-key path and defaults to adam2eve. cdnDomain changes the CDN domain suffix and defaults to the existing makefun.ai behavior. The returned key is scoped to {urlPrefix}/{env}/user/{user_id}/. PUT upload contract (also applies to the legacy alias): - 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. - The uploadUrl query already authenticates the PUT. Use a separate unauthenticated HTTP client: do not forward Authorization or manually add x-amz-* headers. - 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. - fileSize and contentLength are optional outside site runtimes. Omit them for a minimal upload; never copy a placeholder byte count. - 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. - Site runtimes can require fileSize; use the actual byte count there. expiresIn is URL validity, not object retention. Use cdnUrl only after PUT succeeds. Two-step cURL example (requires curl and jq): ```sh curl -X POST "https://video.a2e.ai/api/v1/r2/get_upload_presigned_url" \ -H 'Authorization: Bearer YOUR_A2E_API_KEY' \ -H 'Content-Type: application/json' \ --data '{"key":"upload.png","purpose":"STAGING","contentType":"image/png","expiresIn":300}' \ --fail-with-body --output /tmp/a2e-upload-response.json upload_url=$(jq -er '.data.uploadUrl' /tmp/a2e-upload-response.json) curl -X PUT "$upload_url" -H 'Content-Type: image/png' \ --data-binary @upload.png --fail-with-body ``` Replace YOUR_A2E_API_KEY and upload.png with your own API key and file. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `key`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/r2/upload-presigned-url` — Get pre-signed upload URL.
- Operation ID: `postApiV1R2GetUploadPresignedUrl`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/r2/get_upload_presigned_url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "key": "upload.png",
  "purpose": "STAGING",
  "expiresIn": 60,
  "contentType": "image/png"
}
JSON
```
- Responses:
  - `200` — Item retrieved successfully
```json
{"$ref":"#/components/schemas/R2UploadPresignedUrlResponse"}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/share/downloadUrl — Get a downloadable video URL from a share link
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. ### Request - This operation does not declare bearer authentication in the published specification. - Supported query parameters: `share_url`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Reads the requested information without creating a generation task. - Use the returned fields as documented; availability may depend on the caller and current resource state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Malformed or unsupported share link. - `404` — Shared video is missing, unavailable, or expired.
- Operation ID: `getApiV1ShareDownloadUrl`
- Request parameters:
  - `share_url` (query, required; string; example: `https://example.com/file`) — Complete share-result link issued by this service.
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/share/downloadUrl?share_url=https%3A%2F%2Fexample.com%2Ffile" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Download URL returned.
```json
{"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"}}}
```
  - `400` — Malformed or unsupported share link.
  - `404` — Shared video is missing, unavailable, or expired.

##### POST /api/v1/r2/upload-presigned-url — Get pre-signed upload URL
Generate a pre-signed R2 PUT URL for direct browser/client upload. If bucket is omitted, files are uploaded to 3days-apac by default. urlPrefix changes the leading object-key path and defaults to adam2eve outside site runtimes. cdnDomain changes the CDN domain suffix and defaults to the existing makefun.ai behavior outside site runtimes. Site runtimes reject urlPrefix and cdnDomain overrides to preserve isolated storage routing. The returned key is scoped to {urlPrefix}/{env}/user/{user_id}/. Use cdnUrl as the public file URL after the PUT upload succeeds. API-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. The 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. PUT upload contract (also applies to the legacy alias): - 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. - The uploadUrl query already authenticates the PUT. Use a separate unauthenticated HTTP client: do not forward Authorization or manually add x-amz-* headers. - 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. - fileSize and contentLength are optional outside site runtimes. Omit them for a minimal upload; never copy a placeholder byte count. - 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. - Site runtimes can require fileSize; use the actual byte count there. expiresIn is URL validity, not object retention. Use cdnUrl only after PUT succeeds. Two-step cURL example (requires curl and jq): ```sh curl -X POST "https://video.a2e.ai/api/v1/r2/upload-presigned-url" \ -H 'Authorization: Bearer YOUR_A2E_API_KEY' \ -H 'Content-Type: application/json' \ --data '{"key":"upload.png","purpose":"STAGING","contentType":"image/png","expiresIn":300}' \ --fail-with-body --output /tmp/a2e-upload-response.json upload_url=$(jq -er '.data.uploadUrl' /tmp/a2e-upload-response.json) curl -X PUT "$upload_url" -H 'Content-Type: image/png' \ --data-binary @upload.png --fail-with-body ``` Replace YOUR_A2E_API_KEY and upload.png with your own API key and file. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `key`. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/r2/get_upload_presigned_url` — Get pre-signed upload URL.
- Operation ID: `postApiV1R2UploadPresignedUrl`
- Request schema (nested fields and conditions):
```json
{"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 request:
```bash
curl -X POST "https://headswap.app/api/v1/r2/upload-presigned-url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "key": "upload.png",
  "purpose": "STAGING",
  "expiresIn": 60,
  "contentType": "image/png"
}
JSON
```
- Responses:
  - `200` — Operation completed successfully
```json
{"$ref":"#/components/schemas/R2UploadPresignedUrlResponse"}
```
  - `400` — Bad Request - Invalid parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
#### Credits

##### POST /api/v1/generation/quote — Estimate generation credit consumption
Returns a credit estimate without creating a task, calling a generation provider, or charging credits. For agent use, send `endpoint` plus the exact `requestBody` intended for that generation endpoint. Only pricing-related fields are interpreted; a successful quote does not validate the complete generation request. The legacy normalized quote body remains supported for backward compatibility. Core 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. Unlimited 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. Only 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. Seed 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. HTTP 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. For A2E/Qwen image generation, include the output `width` and `height` as well as `resolution`. For `/api/v1/talkingVideo/start`, include `input_audio_duration` in `requestBody` to quote the source audio length; `input_video_duration` does not price this operation. In 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. `/api/v1/imageBackgroundRemoval/start` uses GPT Image 2.5 Flare pricing at the requested `resolution` (default `1K`). Quotes use the same dimension-based resolution promotion as task creation; supported A2E tiers are `1K`, `1080P`, and `2K`. A 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. For 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. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Unsupported endpoint or invalid pricing combinations. Missing duration may instead return HTTP 200 with available=false; inspect data.available. - `401` — Missing or invalid bearer token. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1GenerationQuote`
- Request schema (nested fields and conditions):
```json
{"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":{}}}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/generation/quote" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "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
  }
}
JSON
```
- Responses:
  - `200` — Estimate result. HTTP 200 with available=false and coins=null means no usable estimate, never a free generation.
```json
{"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"}}}
```
  - `400` — Unsupported endpoint or invalid pricing combinations. Missing duration may instead return HTTP 200 with available=false; inspect data.available.
  - `401` — Missing or invalid bearer token

##### POST /api/v1/custom_back/allBackground — List available backgrounds
List available backgrounds. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/custom_back/randomBackground` — Get a random default background. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackAllBackground`
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_back/allBackground" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/custom_back/randomBackground — Get a random default background
Get a random default background. ### Request - This operation does not declare bearer authentication in the published specification. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - Non-success responses use the published error envelope; surface the returned message and code to diagnostics. ### Related Operations - `POST /api/v1/custom_back/allBackground` — List available backgrounds.
- Operation ID: `postApiV1CustomBackRandomBackground`
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/custom_back/randomBackground" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```

##### GET /api/v1/userVideoTwin/{_id} — Get a video twin record
Get a video twin record. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. ### Related Operations - `POST /api/v1/userVideoTwin/retry` — Retry a video twin task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userVideoTwin/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/retry — Retry a video twin task
Retry a video twin task. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `_id`. ### Behavior - Requests another processing attempt for an eligible failed task. - Eligibility, charging, and state transitions follow the task-specific rules exposed by the response. - Continue monitoring the same or returned task identifier after the retry is accepted. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/{_id}` — Get a video twin record. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinRetry`
- Request schema (nested fields and conditions):
```json
{"allOf":[{"type":"object","required":["_id"],"properties":{"_id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","example":"507f1f77bcf86cd799439011"}}}]}
```
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userVideoTwin/retry" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userDubbing/allProcessing — List processing task identifiers and statuses
List processing task identifiers and statuses. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserDubbingAllProcessing`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userDubbing/allProcessing" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userCaptionRemoval/allProcessing — List processing task identifiers and statuses
List processing task identifiers and statuses. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserCaptionRemovalAllProcessing`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userCaptionRemoval/allProcessing" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userUpscale/allProcessing — List processing task identifiers and statuses
List processing task identifiers and statuses. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. - `429` — Task query budget exceeded; retry after the Retry-After response header. - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserUpscaleAllProcessing`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userUpscale/allProcessing" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `429` — Task query budget exceeded; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `503` — Task query budget temporarily unavailable; retry after the Retry-After response header.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userImage2Video/avgProcessingTime — Get image-to-video processing estimates
Get image-to-video processing estimates. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared. - `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded. - `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoAvgProcessingTime`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userImage2Video/avgProcessingTime" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/userImage2Video/unlimitedQueueLevel — Get image-to-video unlimited queue level
Get image-to-video unlimited queue level. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Retrieves the current server-side representation of the requested resource or task. - For asynchronous tasks, inspect the documented status and result fields before consuming generated media. - Repeat the request only as needed for polling and stop after the task reaches a terminal state. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared. - `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded. - `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoUnlimitedQueueLevel`
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/userImage2Video/unlimitedQueueLevel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImage2Video/{_id}/markShared — Mark an image-to-video task as shared
Mark an image-to-video task as shared. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Records the named client interaction for the identified task. - The operation does not regenerate or otherwise modify the task's media output. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded. - `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied. - `GET /api/v1/userImage2Video/avgProcessingTime` — Get image-to-video processing estimates. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoIdMarkShared`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011/markShared" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImage2Video/{_id}/markDownloaded — Mark an image-to-video task as downloaded
Mark an image-to-video task as downloaded. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Records the named client interaction for the identified task. - The operation does not regenerate or otherwise modify the task's media output. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared. - `POST /api/v1/userImage2Video/{_id}/markCopied` — Mark an image-to-video task as copied. - `GET /api/v1/userImage2Video/avgProcessingTime` — Get image-to-video processing estimates. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoIdMarkDownloaded`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011/markDownloaded" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userImage2Video/{_id}/markCopied — Mark an image-to-video task as copied
Mark an image-to-video task as copied. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supply `_id` in the URL path. ### Behavior - Records the named client interaction for the identified task. - The operation does not regenerate or otherwise modify the task's media output. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/userImage2Video/{_id}/markShared` — Mark an image-to-video task as shared. - `POST /api/v1/userImage2Video/{_id}/markDownloaded` — Mark an image-to-video task as downloaded. - `GET /api/v1/userImage2Video/avgProcessingTime` — Get image-to-video processing estimates. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoIdMarkCopied`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X POST "https://headswap.app/api/v1/userImage2Video/507f1f77bcf86cd799439011/markCopied" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
```json
{"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"}}}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### GET /api/v1/transactionRecord/creditsHistory — Get credits history
Retrieve paginated credits transaction history for the authenticated user. Positive amounts are credit grants or purchases; negative amounts are credit consumption. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Supported query parameters: `pageNum`, `pageSize`, `is_consumption`, `startDate`, `endDate`. Omitted values use the defaults shown in the parameter schema. ### Behavior - Returns the collection visible in the current request and authorization context. - Apply the documented pagination and filter parameters when present; use response metadata to continue paging. - Record fields and status values have the same meaning as in the corresponding detail operation. ### Response - The `200` response contains the requested collection in the response envelope documented below. - An empty collection is a successful result when no matching records are available. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid query parameters. - `401` — Unauthorized - Invalid or missing token. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TransactionRecordCreditsHistory`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number, starting from 1.
  - `pageSize` (query, optional; integer; default: `10`; min: 1; example: `10`) — Number of records per page.
  - `is_consumption` (query, optional; boolean; example: `false`) — When true, only returns consumption records; when false, only returns credit income records.
  - `startDate` (query, optional; string; example: `2026-01-01T00:00:00Z`) — Inclusive ISO date-time lower bound for createdAt.
  - `endDate` (query, optional; string; example: `2026-01-01T00:00:00Z`) — Inclusive ISO date-time upper bound for createdAt.
- Example request:
```bash
curl -X GET "https://headswap.app/api/v1/transactionRecord/creditsHistory?pageNum=1&pageSize=10&is_consumption=false&startDate=2026-01-01T00%3A00%3A00Z&endDate=2026-01-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Credits history retrieved successfully
```json
{"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"}}}
```
  - `400` — Bad Request - Invalid query parameters
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

## Deprecated operations
These paths remain listed for compatibility. Use the replacement APIs described below.

### Avatar & Video
#### Video Twin

##### POST /api/v1/userVideoTwin/upload — Deprecated video twin upload
- Deprecated: use the replacement in the description below.
This route always returns ENDPOINT_DEPRECATED. Create an avatar with POST /api/v1/userVideoTwin/startTraining instead. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Reads the requested information without creating a generation task. - Use the returned fields as documented; availability may depend on the caller and current resource state. ### Response - This operation does not declare a `2xx` response; consult the documented response statuses below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/startTraining. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. - `GET /api/v1/userVideoTwin/uploadStatus` — Get video twin upload status. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinUpload`
- Responses:
  - `400` — ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/startTraining.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```

##### POST /api/v1/userVideoTwin/training — Deprecated video twin training
- Deprecated: use the replacement in the description below.
This route always returns ENDPOINT_DEPRECATED. Start deep training with POST /api/v1/userVideoTwin/continueTraining instead. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - No request body or operation-specific parameters are required. ### Behavior - Reads the requested information without creating a generation task. - Use the returned fields as documented; availability may depend on the caller and current resource state. ### Response - This operation does not declare a `2xx` response; consult the documented response statuses below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/continueTraining. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `GET /api/v1/userVideoTwin/uploadStatus` — Get video twin upload status. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinTraining`
- Responses:
  - `400` — ENDPOINT_DEPRECATED; use POST /api/v1/userVideoTwin/continueTraining.
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```
  - `401` — Unauthorized - Invalid or missing JWT token
```json
{"$ref":"#/components/schemas/ErrorResponse"}
```