PicMa Studio API Developer Docs
This API set provides async task submission and querying for AI image and video processing — photo restoration, enhancement, filters, text-to-image, video super-resolution, denoising, image-to-video, and more. All tasks are asynchronous: submit a task to obtain a taskId, then poll until it completes.
Overview
This API set provides AI image processing and video processing capabilities. The docs are organized into Image APIs, Video APIs, and Common APIs. All tasks are asynchronous. The standard workflow is:
- Call a specific processing API to submit a task. It returns
taskIdand an initial status (queuing). - Poll the generic task-query API
GET /v1/tasks/{task_id}(shared by image and video tasks) until the status becomes completed or failed. - On success, get the processed image or video from
output.urlin the result.
How to get specsCode
Some APIs (e.g. Image Filters, AI Portrait, HeTu Image Filters, AI ID Photo, Hetu Style Video - Single Image) require a specsCode to select a specific style or capability. Follow these steps:
- Sign in to the PicMa Studio Developer Platform
- Open Algorithm Store and find the algorithm you want to integrate
- Open the capability detail page to view the
specsCodeand sample output images - Choose the effect you want from the samples and use the matching
specsCodein your API request
specsCode means an output resolution tier (e.g. 720P, 1080P) — not an Algorithm Store style code. Invalid or unavailable style codes return 1003002.Base Info & Auth
https://api.developer.magictiger.ai/v1/photo-restore, https://api.developer.magictiger.ai/v1/tasks/{task_id}.Every request must carry the token in the header:
Authorization: Bearer {token}
Content-Type: application/json
Common Response
All APIs return a unified ReplyAi structure:
{
"code": 0,
"msg": "request success",
"data": { }
}
| Field | Type | Description |
|---|---|---|
code | int | Status code. 0 means success; others are error codes |
msg | String | Status message |
data | Object | Business payload (task APIs return TaskResultDto) |
Error Codes
| Code | Description |
|---|---|
0 | Success |
-1 | Request failed / service degraded (fallback when circuit breaking, rate limiting or isolation triggers) |
3 | Invalid parameter |
4 | Illegal parameter (e.g. expansion coordinates out of bounds) |
5 | Parameter signature validation failed |
6 | Trial quota exhausted |
9 | Permission denied |
999 | Server error, please retry later |
1001001 | Task creation failed |
1001002 | Resource (image/video) URL validation failed |
1001003 | Resource (image/video/audio) size exceeds the limit |
1001004 | Unsupported file type |
1001005 | Unsupported resolution / ratio (illegal resolution or ratio value) |
1001006 | Resource (image/video/audio) count exceeds the limit |
1001007 | Illegal output duration |
1001008 | Resource (video/audio) duration is illegal |
1002001 | Task ID does not exist |
1002002 | Task has been deleted |
1003001 | Interface has been discontinued / taken offline |
1003002 | Failed to get configuration, please contact the administrator |
Workflow (Full Example)
Using "Old Photo Restoration" as an example:
Step 1 · Submit a task
curl -X POST 'https://api.developer.magictiger.ai/v1/photo-restore' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-d '{ "imageUrl": "https://example.com/old-photo.jpg" }'
Response:
{
"code": 0,
"msg": "request success",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000-20260717103000",
"status": "queuing",
"pointsConsumed": 10
}
}
Step 2 · Poll task status
curl -X GET 'https://api.developer.magictiger.ai/v1/tasks/550e8400-e29b-41d4-a716-446655440000-20260717103000' \
-H 'Authorization: Bearer {token}'
Repeat until status is completed, then get the result image from data.output.url.
Request Parameters (DTO)
Image API request bodies are mostly based on PhotoRestoreReqDto; video APIs use separate video DTOs (see below).
PhotoRestoreReqDto (base body)
Used directly by: Old Photo Restoration, Photo Enhancer, Old Photo Restoration Pro, Image Upscaler, Photo Unblur, Scratch Removal, Photo Colorizer, Damaged Photo Restoration, Low-Light Enhancement, Background Remover, Object Remover, Image Watermark Remover, Face Cutout, AI Eraser.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the image to process |
clientTaskId | String | No | Client-defined task ID for idempotency |
PhotoPromptReqDto (with prompt)
Extends PhotoRestoreReqDto。Used by: Generative Fill.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the composite image (original + mask side-by-side; see Generative Fill input requirements) |
clientTaskId | String | No | Client-defined task ID |
prompt | String | Yes | Text prompt describing the desired content for the white mask region |
PhotoChangeReqDto (with target image)
Extends PhotoRestoreReqDto。Used by: AI Clothes Changer.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | Original image URL |
clientTaskId | String | No | Client-defined task ID |
changeImageUrl | String | Yes | Target image URL (e.g. a clothing image) |
PhotoExpansionDto (expansion body)
Extends PhotoRestoreReqDto。Used by: AI Image Expander.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the image to process |
clientTaskId | String | No | Client-defined task ID |
expandImagesJsonDto | ExpandImagesJsonDto | Yes | Expansion parameters, see below |
ExpandImagesJsonDto
| Field | Type | Required | Description |
|---|---|---|---|
width | Integer | Yes | Canvas width |
height | Integer | Yes | Canvas height |
startX | Integer | Yes | Top-left start X coordinate |
startY | Integer | Yes | Top-left start Y coordinate |
startX must not exceed width,startY must not exceed height; otherwise error code 4 (illegal parameter) is returned.PhotoSpecsCodeReqDto (specs code)
Extends PhotoRestoreReqDto。Used by: Image Filters, AI Portrait.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the image to process |
clientTaskId | String | No | Client-defined task ID |
specsCode | String | Yes | Specs code (maps to a specific filter / portrait style) |
gender | Integer | No | Gender: 0 = male, 1 = female (optional for multi-person cases) |
ratio | String | No | Output aspect ratio, default 2:3; allowed: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
resolution | String | No | Output resolution, default 1K; only 1K / 2K (uppercase) |
PhotoFilterReqDto (specs-code filter)
Extends PhotoRestoreReqDto. Used by: HeTu Image Filters.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the image to process |
clientTaskId | String | No | Client-defined task ID |
specsCode | String | Yes | Specs code (Hetu filter style; returns 1003002 when invalid) |
specsCode, see Overview · How to get specsCode.PhotoIDPhotoReqDto (ID photo)
Extends PhotoRestoreReqDto. Used by: AI ID Photo (Custom Outfit), Standard AI ID Photo.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the image to process |
clientTaskId | String | No | Client-defined task ID |
specsCode | String | Yes | ID photo specs code (returns 1003002 when invalid) |
preBeauty | Integer | No | Beauty filter: 1 = off, 2 = on; default off when omitted |
outputFmt | String | No | Output format: webp / png / jpg / bmp, default png |
IPhotooSpecsCodeReqDto (AI Travel Photos)
Standalone request body (does not extend PhotoRestoreReqDto). Used by: AI Travel Photos (photo-portrait-iphotoo).
| Field | Type | Required | Description |
|---|---|---|---|
imageUrls | List<String> | No | Input image URLs, max 2; single-person portrait: 1 image; two-person: 1 group photo or 2 individual photos |
clientTaskId | String | No | Client-defined task ID |
specsCode | String | Yes | AI Travel Photos style code (returns 1003002 when invalid) |
gender | Integer | No | Gender: 0 = male, 1 = female |
ratio | String | No | Output aspect ratio, default 2:3; same allowed values as PhotoSpecsCodeReqDto.ratio |
resolution | String | No | Output resolution, default 1K; only 1K / 2K |
beauty | Integer | No | Beauty switch: 0 = off, 1 = on |
beautyLevel | Integer | No | Beauty level 0–10; applies when beauty=1 |
imageUrls returns 1001006; invalid ratio returns 1001005.PhotoGptImagePromptReqDto (text-to-image / image-to-image)
Used by: doubao-seedream-4-0 / doubao-seedream-4-5 / doubao-seedream-5-0 / doubao-seedream-5-0-pro, gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, gemini-3.1-flash-image, gemini-3-pro-image, Hetu Image Large Model.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | String | Yes | Text prompt |
clientTaskId | String | No | Client-defined task ID |
imageUrls | List<String> | No | Input image URL list, multiple images supported (omit for pure text-to-image; max count per API listed below) |
resolution | String | No | Output resolution, default 2K; allowed values vary by API (e.g. 1K/2K/4K) |
ratio | String | No | Output aspect ratio, allowed values vary by API |
resolution or ratio returns 1001005; imageUrls exceeding the API max count returns 1001006.PhotoTemplateNumberReqDto (template index)
Extends PhotoRestoreReqDto。Previously used by Sky Filter and Face Dynamization, which are now offline.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | URL of the image to process |
clientTaskId | String | No | Client-defined task ID |
templateNumber | Integer | Yes | Template index |
VideoEnhanceReqDto (video enhance)
Used by: Video Enhancement, Face Restoration, Video Denoiser, AI Color Correction, Video Colorizer, Night Enhancement, Detail Enhancement, Scan Line Removal.
| Field | Type | Required | Description |
|---|---|---|---|
videoUrl | String | Yes | Input video URL (≤100MB) |
clientTaskId | String | No | Client-defined task ID |
outputFmt | String | No | Output container: mp4/mov/mkv/ts, default mp4 |
encodeType | Integer | No | 0=H.264, 1=H.265, default 0 |
encodeQuality | Integer | No | 0low / 1medium / 2high, default 1 |
specsCode | String | No | Must be uppercase: 720P/1080P/4K/8K; omit to match input resolution |
720P, 1080P, 480P, 4K, and 8K must be uppercase. Lowercase (e.g. 720p) will fail validation. Here specsCode is an output resolution tier, not an Algorithm Store style code.VideoRmWaterMarkReqDto (video watermark removal)
Extends VideoEnhanceReqDto. Used by: Video Watermark Remover.
| Field | Type | Required | Description |
|---|---|---|---|
| (inherited fields) | — | — | Same as VideoEnhanceReqDto |
waterMarkParam | VideoWaterMarkDto | Yes | Watermark bounding box (see below) |
VideoWaterMarkDto (JSON field names must be uppercase)
(0,0); X increases rightward, Y increases downward. X/Y are the watermark top-left corner; W/H are width/height in pixels (all ≥ 0).| Field | Type | Required | Description |
|---|---|---|---|
X | Integer | Yes | Watermark top-left X (≥0) |
Y | Integer | Yes | Watermark top-left Y (≥0) |
W | Integer | Yes | Watermark width (≥0) |
H | Integer | Yes | Watermark height (≥0) |
VideoRmBgReqDto (Video background removal)
Used by: Video Background Remover.
| Field | Type | Required | Description |
|---|---|---|---|
videoUrl | String | Yes | Input video URL (≤100MB) |
clientTaskId | String | No | Client-defined task ID |
VideoStyleFilterReqDto (Hetu style video)
Used by: Hetu Style Video - Single Image.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | Input image URL (≤20MB) |
clientTaskId | String | No | Client-defined task ID |
specsCode | String | Yes | Style specs code (returns 1003002 if invalid); duration and output specs are determined by the style config |
specsCode (fixed tier; not multiplied by duration/resolution). For style specsCode, see Overview · How to get specsCode.VideoStyleFilterCustomReqDto (Hetu style video custom)
Used by: Hetu Style Video - Custom. The underlying generation model was upgraded to v2.0 on 2026-09-15 (API path and request parameters unchanged).
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | String | Yes | Input image URL (≤20MB) |
clientTaskId | String | No | Client-defined task ID |
outputDuration | Integer | Yes | Output duration (seconds), 2–5 |
outputRes | String | Yes | Must be uppercase: 480P / 720P |
prompt | String | Yes | Custom prompt |
outputRes accepts only uppercase 480P and 720P.outputDuration.VideoStyleFilterFramesReqDto (Hetu style video frames)
Used by: Hetu Style Video - Two Images & First/Last Frames.
| Field | Type | Required | Description |
|---|---|---|---|
imageUrls | List<String> | No | Start/end frame images, max 2; excess returns 1001006 |
clientTaskId | String | No | Client-defined task ID |
specsCode | String | Yes | Style specs code (returns 1003002 if invalid); duration and output specs are determined by the style config |
specsCode (fixed tier; not multiplied by duration/resolution). For style specsCode, see Overview · How to get specsCode.VideoSeedanceReqDto (Seedance video generation)
Used by: seedance-2.0-mini, seedance-2.0. Resolution tiers differ by API.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | String | Yes | Text prompt |
outputRes | String | Yes | Output resolution (must be uppercase); Mini: 480P/720P; 2.0: 480P/720P/1080P/4K |
outputDuration | Integer | Yes | Output duration (seconds), 4–15 |
imageUrls | List<String> | No | Reference images, max 9; each ≤20MB; jpeg/png/webp/bmp/tiff/gif/heic |
videoUrls | List<String> | No | Reference videos; combined with audioUrls max 3; total size ≤200MB; total duration 2–15.2s; mp4/mov |
audioUrls | List<String> | No | Reference audio; combined with videoUrls max 3; total size ≤15MB; total duration 2–15.2s; wav/mp3 |
ratio | String | No | 1:1 / 4:3 / 3:4 / 16:9 / 9:16 |
clientTaskId | String | No | Client-defined task ID |
1001005; too many images or video+audio items returns 1001006; size overflow returns 1001003; illegal total input video/audio duration returns 1001008.outputDuration.VideoSeedance25ReqDto (Seedance 2.5 video generation)
Used by: seedance-2.5. Same fields as VideoSeedanceReqDto, but outputRes supports only 480P/720P, and outputDuration is 4–30 seconds.
VideoSeedanceReqDto.VideoPromptReqDto (prompt video generation)
Used by: grok-imagine-video-1.5, Pixverse V6, MiniMax H3. Resolution, ratio, duration, and max reference images vary by API.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | String | Yes | Text prompt |
outputRes | String | Yes | Output resolution (must be uppercase; values per API) |
outputDuration | Integer | Yes | Output duration in seconds (values per API) |
imageUrls | List<String> | No | Reference images (each ≤20MB; max count per API) |
ratio | String | No | Output aspect ratio (values per API) |
clientTaskId | String | No | Client-defined task ID |
1001005; too many reference images returns 1001006; illegal duration returns 1001007.outputDuration.UserPointsDto (User Remaining Points)
Used by: Get Remaining Points (§6.2).
| Field | Type | Description |
|---|---|---|
remainPoints | Integer | Remaining available points (excluding frozen points) |
Task Result Schema (TaskResultDto)
Both a successful task creation (code=0) and the task-query API's data field return TaskResultDto. The field set varies by scenario:
| Scenario | Returned fields |
|---|---|
| Create task (POST) | taskId、status、pointsConsumed |
Query task (GET /v1/tasks/{task_id}) | All fields below (conditionally returned by task status) |
| Field | Type | Description |
|---|---|---|
taskId | String | Task ID (used for polling) |
status | String | queuing queuing / processing processing / completed completed / failed failed |
pointsConsumed | Integer | Points consumed (from points record; may be null) |
clientTaskId | String | Client-defined task ID (echoed as-is on query) |
reqInfoJson | Object | Request info JSON (returned on query only for text-to-image or multi-image-to-image tasks; contains the user's original request parameters such as prompt、imageUrls、resolution、ratio, etc.) |
errorMsg | String | Error message (returned only when status=failed) |
errorCode | Integer | Error code (returned only when status=failed) |
input | MediaInfo | Input image info (returned only when the task has an input image URL; may be absent for pure text-to-image tasks) |
output | MediaInfo | Output image info (returned only when status=completed; relative URLs are auto-completed to full addresses) |
Query task field assembly logic
When querying task status (GET /v1/tasks/{task_id}), the server assembles fields as follows:
| Field | Assembly rule |
|---|---|
reqInfoJson | Returned only for text-to-image or multi-image-to-image tasks; contains the user's original request info (e.g. prompt、imageUrls、resolution、ratio, etc.) |
clientTaskId | Echoes the clientTaskId |
pointsConsumed | Read from points record; null |
errorCode / errorMsg | 仅当 status=failed 时返回 |
input | Returned only when an input image URL exists, with url、width、height、size |
output | 仅当 status=completed 时返回 |
MediaInfo
| Field | Type | Description |
|---|---|---|
url | String | Resource URL |
width | Integer | Width (px) |
height | Integer | Height (px) |
size | Long | File size (bytes) |
Status flow: queuing → processing → completed / failed
Image APIs
The APIs below submit async image processing tasks. Input is typically an image URL (or a text-to-image prompt). Poll the common query API for the result image when complete.
Old Photo Restoration
Capability code: photo-restore
Capability: Intelligently restores old, blurry or low-resolution photos as a whole, improving clarity and overall quality.
Use cases: old photo restoration, low-res portrait/landscape repair, etc.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId. Auth: Bearer Token.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/photo.jpg",
"clientTaskId": "my-task-001"
}
Photo Enhancer
Capability code: photo-enhance
Capability: Enhances details and image quality for a sharper, clearer picture.
Use cases: everyday photo quality boost, detail sharpening.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Old Photo Restoration Pro
Capability code: photo-enhance-restore
Capability: An advanced two-in-one capability combining quality enhancement with detail restoration.
Use cases: photo processing that needs higher-quality restoration and enhancement.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Image Upscaler
Capability code: photo-sr
Capability: Performs general super-resolution upscaling while preserving clarity at larger sizes.
Use cases: upscaling low-resolution images, producing higher-clarity assets.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Photo Unblur
Capability code: photo-deblurring
Capability: Removes blur caused by camera shake or subject motion to recover a clear image.
Use cases: camera-shake blur, motion-trail photo repair.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Scratch Removal
Capability code: photo-scratch-removal
Capability: Intelligently removes scratches, creases and similar defects from old photos.
Use cases: scratch cleanup after digitizing paper old photos.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Photo Colorizer
Capability code: photo-colorization
Capability: Intelligently colorizes black-and-white photos with natural, realistic colors.
Use cases: B&W old photo colorization, historical footage renewal.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Damaged Photo Restoration
Capability code: photo-damaged-restore
Capability: One-click repair for severely damaged old photos with tears, missing areas or stains.
Use cases: repair of torn, stained or heavily damaged photos.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Low-Light Enhancement
Capability code: photo-low-light-enhance
Capability: Boosts brightness and detail for low-light, backlit or underexposed photos.
Use cases: night scenes, indoor low light, underexposed photo brightening.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
Generative Fill
Capability code: photo-partial-repainting
Capability: Intelligently repaints a specified region of the image based on a prompt to replace or adjust content.
Use cases: local scene swap, local content rewrite, inpainting-style edits.
Request notes: Body PhotoPromptReqDto; required imageUrl (must be a preprocessed composite) and prompt; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
imageUrl must be a preprocessed composite: stitch the original image and the edit mask side by side before upload/hosting. Do not send the original alone.
- Left half: original image
- Right half: mask (same size as the original); white = region to repaint, black = keep unchanged
- If the original is
W×H, the composite should be2W×H(equal halves, horizontal stitch)
{
"imageUrl": "https://example.com/original-with-mask.jpg",
"prompt": "dress the person in a red dress"
}
AI Clothes Changer
Capability code: photo-change-clothes
Capability: Intelligently dresses a person in the target outfit for a one-click clothes-change effect.
Use cases: e-commerce try-on, portrait outfit preview.
Request notes: Body PhotoChangeReqDto; required imageUrl, changeImageUrl; optional clientTaskId. The server validates both images separately.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/person.jpg",
"changeImageUrl": "https://example.com/clothes.jpg"
}
AI Image Expander
Capability code: photo-expansion
Capability: Intelligently expands image borders within the specified canvas and auto-fills new content.
Use cases: composition expansion, filling content around the image edges.
Request notes: Body PhotoExpansionDto; required imageUrl, expandImagesJsonDto (width/height/startX/startY). Returns error code 4 when startX > width or startY > height.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/photo.jpg",
"expandImagesJsonDto": {
"width": 1024,
"height": 1024,
"startX": 200,
"startY": 200
}
}
Sky Filter (Offline)
Capability code: photo-sky-filter
1003001 (interface offline).Face Dynamization (Offline)
Capability code: photo-face-dynamization
1003001 (interface offline).Image Filters
Capability code: photo-filter
Capability: Applies an AI filter style to a photo by a specified specs code.
Use cases: stylized filters, batch application of preset filters.
Request notes: Body PhotoSpecsCodeReqDto; required imageUrl, specsCode; optional gender, ratio (default 2:3), resolution (default 1K, supports 1K/2K), clientTaskId. Returns 1003002 when style config is missing.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/photo.jpg",
"specsCode": "filter_001",
"gender": 1,
"ratio": "2:3",
"resolution": "1K"
}
AI Portrait
Capability code: photo-portrait
Capability: Generates an AI portrait-style effect for a photo by a specified specs code (with pre/post-processing).
Use cases: portrait style conversion, template-based portrait generation.
Request notes: Body PhotoSpecsCodeReqDto; required imageUrl, specsCode; optional gender, ratio (default 2:3), resolution (default 1K, supports 1K/2K), clientTaskId. Returns 1003002 when style config is missing.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/photo.jpg",
"specsCode": "portrait_001",
"gender": 1,
"ratio": "2:3",
"resolution": "2K"
}
AI Travel Photos
Capability code: photo-portrait-iphotoo
Capability: Generates travel-photo portrait styles by specs code; supports output ratio/resolution and optional beauty controls.
Use cases: Template-based travel portraits, portrait generation with beauty tuning.
Request notes: Body IPhotooSpecsCodeReqDto; required specsCode; imageUrls max 2 (single person: 1; two people: 1 group photo or 2 individual photos); optional gender, ratio, resolution, beauty, beautyLevel, clientTaskId. Returns 1003002 when style config is missing.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrls": ["https://example.com/photo.jpg"],
"specsCode": "iphotoo_001",
"gender": 0,
"ratio": "3:4",
"resolution": "2K",
"beauty": 1,
"beautyLevel": 6
}
HeTu Image Filters
Capability code: photo-hetu-filter
Capability: Applies a Hetu filter style to a photo by a specified specs code.
Use cases: Hetu style filter application.
Request notes: Body PhotoFilterReqDto; required imageUrl, specsCode; optional clientTaskId. Returns 1003002 when style config is missing.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/photo.jpg",
"specsCode": "hetu_001"
}
doubao-seedream-4-0
Capability code: photo-doubao-seedream-4-0
Capability: Prompt-based text-to-image / image-to-image generation.
Use cases: creative image generation, reference-guided generation.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 10), resolution (1K/2K/4K), ratio (e.g. 1:1, 16:9, 9:16, etc.).
Output notes: Async task; get the result image from output.url when complete.
{
"prompt": "a cyberpunk city at night",
"imageUrls": ["https://example.com/ref.jpg"],
"resolution": "2K",
"ratio": "16:9"
}
doubao-seedream-4-5
Capability code: photo-doubao-seedream-4-5
Capability: Prompt-based text-to-image / image-to-image generation (4.5).
Use cases: creative generation requiring higher quality or newer model capabilities.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 10), resolution (1K/2K/4K), ratio (same as 4.0).
Output notes: Async task; get the result image from output.url when complete.
{
"prompt": "a watercolor forest cabin",
"resolution": "2K",
"ratio": "4:3"
}
doubao-seedream-5-0
Capability code: photo-doubao-seedream-5-0-lite
Capability: Prompt-based text-to-image / image-to-image generation (5.0 Lite).
Use cases: creative generation balancing quality and cost.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 10), resolution (1K/2K/3K), ratio (same as 4.0).
Output notes: Async task; get the result image from output.url when complete.
doubao-seedream-5-0-pro
Capability code: photo-doubao-seedream-5-0-pro
Capability: Prompt-based text-to-image / image-to-image generation (5.0 Pro).
Use cases: creative scenarios requiring higher output quality.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 10), resolution (1K/2K), ratio (same as 4.0).
Output notes: Async task; get the result image from output.url when complete.
gpt-image-2
Capability code: photo-gpt-image-2
Capability: Prompt-based text-to-image / image-to-image generation.
Use cases: general creative generation, multi-image reference generation.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 14), resolution (1K/2K, points vary by resolution), ratio (same as 4.0).
Output notes: Async task; get the result image from output.url when complete.
{
"prompt": "a corgi wearing sunglasses",
"resolution": "2K",
"ratio": "1:1"
}
gpt-image-2.5-flare
Capability code: photo-gpt-image-2-5-flare
Capability: Prompt-based text-to-image / image-to-image generation (GPT Image 2.5 Flare).
Use cases: creative generation with higher resolution tiers, multi-image reference generation.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 14), resolution (1K/2K/4K, points vary by resolution), ratio (same as 4.0).
Output notes: Async task; get the result image from output.url when complete.
gpt-image-2.5-sunburst
Capability code: photo-gpt-image-2-5-sunburst
Capability: Prompt-based text-to-image / image-to-image generation (GPT Image 2.5 Sunburst).
Use cases: creative generation with higher resolution tiers, multi-image reference generation.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 14), resolution (1K/2K/4K, points vary by resolution), ratio (same as 4.0).
Output notes: Async task; get the result image from output.url when complete.
gemini-3.1-flash-image
Capability code: photo-gemini-3-1-flash-image
Capability: Prompt-based text-to-image / image-to-image generation (gemini-3.1-flash-image).
Use cases: multi-aspect creative generation, multi-image reference generation.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 14), resolution (1K/2K/4K, points vary by resolution), ratio (supports 1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1).
Output notes: Async task; get the result image from output.url when complete.
gemini-3-pro-image
Capability code: photo-gemini-3-pro-image
Capability: Prompt-based text-to-image / image-to-image generation (gemini-3-pro-image).
Use cases: creative scenarios requiring higher output quality and stability.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 14), resolution (1K/2K/4K, points vary by resolution), ratio (supports 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9).
Output notes: Async task; get the result image from output.url when complete.
Hetu Image Large Model
Capability code: photo-hetu-image
Capability: Prompt-based Hetu text-to-image / image-to-image generation.
Use cases: creative scenarios requiring Hetu-style image generation.
Request notes: Body PhotoGptImagePromptReqDto; required prompt; optional imageUrls (max 1), resolution (1K/2K), ratio.
Output notes: Async task; get the result image from output.url when complete.
Background Remover
Capability code: photo-remove-bg
Capability: One-click background removal (cutout).
Use cases: product cutout, portrait cutout, transparent-background assets, etc.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId. Use a clear image with a complete subject.
Output notes: Output is typically transparent PNG; download after async polling.
{
"imageUrl": "https://example.com/product.jpg",
"clientTaskId": "rmbg-001"
}
Object Remover
Capability code: photo-target-removal
Capability: Intelligently removes distracting objects from the scene.
Use cases: remove passers-by, clutter, distracting elements, etc.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/street.jpg"
}
Image Watermark Remover
Capability code: photo-remove-watermark
Capability: Removes image watermarks and corner marks.
Use cases: remove watermarks from owned assets (ensure compliant usage).
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Output is typically PNG; download after async polling.
{
"imageUrl": "https://example.com/photo-with-wm.jpg"
}
Face Cutout
Capability code: photo-face-segmentation
Capability: Segments face regions from the image.
Use cases: face-region pipelines, face masks / face cutout workflows.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId. Face should be clearly visible.
Output notes: Output is segmentation-oriented (transparent/PNG); download after async polling.
{
"imageUrl": "https://example.com/face.jpg"
}
AI Eraser
Capability code: photo-inpainting
Capability: One-click removal of unwanted elements with intelligent background fill.
Use cases: remove unwanted objects with auto fill; focuses more on background completion than Object Remover.
Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/clutter.jpg"
}
AI ID Photo (Custom Outfit)
Capability code: photo-id-photo
Capability: ID photo generation with customizable outfits for more accurate garment style and detail; spec is determined by specsCode.
Use cases: ID photos when specific outfit appearance is required.
Request notes: Body PhotoIDPhotoReqDto; required imageUrl, specsCode; optional preBeauty (1 off / 2 on, default off), outputFmt (default png), clientTaskId. Returns 1003002 when spec is missing. Use a clear front-facing single-person portrait.
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/portrait.jpg",
"specsCode": "id_photo_custom_001",
"preBeauty": 2,
"outputFmt": "jpg"
}
Standard AI ID Photo
Capability code: photo-id-photo-standard
Capability: Standardized ID photo styles for common scenarios; spec is determined by specsCode.
Use cases: Conventional ID photos, batch standardized output.
Request notes: Body PhotoIDPhotoReqDto; same fields as AI ID Photo (Custom Outfit).
Output notes: Async task; get the result image from output.url when complete.
{
"imageUrl": "https://example.com/portrait.jpg",
"specsCode": "id_photo_std_001",
"outputFmt": "png"
}
Video APIs
The APIs below submit async video processing tasks or image-to-video tasks. After submission, poll GET /v1/tasks/{task_id} for results.
Video Enhance Rules
Scope: Enhances input video with super-resolution, denoising, colorization, low-light enhancement, deinterlacing, watermark removal, etc.
Input limits: Video URL must be reachable; file ≤ 100MB; common extensions supported (mp4, mov, mkv, webm, avi, ts, etc.).
Resolution limits: Short side ≥ 270, long side ≤ 3840; otherwise returns 1001005.
Output specs: specsCode optional (must be uppercase 720P/1080P/4K/8K); omit to match input resolution and frame rate. Here specsCode is an output resolution tier, not an Algorithm Store style code.
Billing: Points = probed duration (seconds) × tier unit price.
Query: After submission, poll with GET /v1/tasks/{task_id}.
Video Enhancement
Capability code: video-sr
Capability: Improves overall video clarity and perceived resolution.
Use cases: upscaling low-res footage, general quality enhancement.
Request notes: Body VideoEnhanceReqDto; required videoUrl; optional output format/encoding/spec fields.
Output notes: Get the result video from output.url when complete.
{
"videoUrl": "https://example.com/input.mp4",
"specsCode": "1080P",
"outputFmt": "mp4"
}
Face Restoration
Capability code: video-sr-face
Capability: Super-resolution focused on face regions.
Use cases: portrait video, interviews, selfie content clarity boost.
Request notes: Body VideoEnhanceReqDto; fields same as Video Enhance Rules.
Output notes: Get the result video from output.url when complete.
Video Denoiser
Capability code: video-denoising
Capability: Reduces video noise for a cleaner picture.
Use cases: grain noise from high ISO / low-light shooting.
Request notes: Body VideoEnhanceReqDto.
Output notes: Get the result video from output.url when complete.
AI Color Correction
Capability code: video-color-enhance
Capability: Improves color expression and saturation.
Use cases: color enhancement for flat or washed-out footage.
Request notes: Body VideoEnhanceReqDto.
Output notes: Get the result video from output.url when complete.
Video Colorizer
Capability code: video-colorization
Capability: Intelligently colorizes black-and-white or near-monochrome video.
Use cases: old footage restoration, B&W material colorization.
Request notes: Body VideoEnhanceReqDto.
Output notes: Get the result video from output.url when complete.
Night Enhancement
Capability code: video-low-light-enhance
Capability: Improves visible detail in dark / low-light scenes.
Use cases: night scenes, indoor low-light footage brightening.
Request notes: Body VideoEnhanceReqDto.
Output notes: Get the result video from output.url when complete.
Detail Enhancement
Capability code: video-high-texture-sr
Capability: Preserves high-texture detail while upscaling.
Use cases: architecture, nature and other texture-rich content.
Request notes: Body VideoEnhanceReqDto.
Output notes: Get the result video from output.url when complete.
Scan Line Removal
Capability code: video-deinterlace
Capability: Removes combing / interlace artifacts.
Use cases: old TV signals, interlaced-to-progressive conversion.
Request notes: Body VideoEnhanceReqDto.
Output notes: Get the result video from output.url when complete.
Video Watermark Remover
Capability code: video-remove-watermark
Capability: Removes watermark regions in video by bounding box.
Use cases: remove corner marks/watermarks from owned assets (ensure compliant usage).
Request notes: Body VideoRmWaterMarkReqDto; required videoUrl, waterMarkParam. X/Y are the watermark top-left (origin at frame top-left); W/H are width/height in pixels (≥0); JSON field names must be uppercase.
Output notes: Get the result video from output.url when complete.
{
"videoUrl": "https://example.com/input.mp4",
"waterMarkParam": { "X": 100, "Y": 40, "W": 180, "H": 60 },
"outputFmt": "mp4"
}
Video Background Remover
Capability code: video-remove-background
Capability: Segments the subject from the background and outputs a video with a transparent background.
Use cases: portrait/product video matting, transparent dynamic assets.
Request notes: Body VideoRmBgReqDto; required videoUrl; optional clientTaskId. Input video must be reachable and ≤100MB. Returns 1001005 if the resolution cannot be tiered.
Output notes: The result is an MOV video with an alpha channel (background removed). Download from output.url when complete.
{
"videoUrl": "https://example.com/input.mp4"
}
Hetu Style Video - Single Image
Capability code: video-hetu-style
Capability: Generates a short video from an input image by style specs code.
Use cases: turn still images into motion video with preset styles.
Request notes: Body VideoStyleFilterReqDto; required imageUrl, specsCode; optional clientTaskId. Returns 1003002 if the style is invalid. Duration and resolution come from the style config — do not send outputDuration / outputRes.
Output notes: Get result video from output.url; billed by the style unit price of specsCode.
{
"imageUrl": "https://example.com/style-ref.jpg",
"specsCode": "hetu_video_001"
}
Hetu Style Video - Custom
Capability code: video-hetu-style-custom
Capability: Generates a short video from an input image via custom prompt.
Use cases: image-to-video with free-form style/motion description.
Request notes: Body VideoStyleFilterCustomReqDto; required imageUrl, prompt, outputDuration (2–5), outputRes (must be uppercase 480P/720P); optional clientTaskId.
Output notes: Get the result video from output.url; billed as resolution unit price × duration.
{
"imageUrl": "https://example.com/ref.jpg",
"prompt": "slow push-in, warm sunset atmosphere",
"outputDuration": 4,
"outputRes": "720P"
}
Hetu Style Video - Two Images & First/Last Frames
Capability code: video-hetu-style-frames
Capability: Generates a transition short video from start/end frame images.
Use cases: given start/end frames, generate intermediate transition animation.
Request notes: Body VideoStyleFilterFramesReqDto; imageUrls max 2; required specsCode; optional clientTaskId. Excess images return 1001006; invalid style returns 1003002. Duration and resolution come from the style config — do not send outputDuration / outputRes.
Output notes: Get the result video from output.url; billed by the style unit price of specsCode.
{
"imageUrls": [
"https://example.com/frame-start.jpg",
"https://example.com/frame-end.jpg"
],
"specsCode": "hetu_video_001"
}
Video Generation Notes
These APIs generate short videos from a prompt (and optional reference images; Seedance also accepts reference video/audio). They differ from video enhance and Hetu style video.
Resolution values must be uppercase. Billing is resolution unit price × duration. After submission, poll GET /v1/tasks/{task_id}.
seedance-2.0-mini
Capability code: video-seedance-2-0-mini
Capability: Generates a short video from a prompt, optionally with reference images, video, or audio.
Use cases: text-to-video / image-to-video with multimodal references.
Request notes: Body VideoSeedanceReqDto; required prompt, outputRes (must be uppercase 480P/720P), outputDuration (4–15); optional imageUrls (max 9), videoUrls+audioUrls (combined max 3), ratio, clientTaskId. Reference videos: total size ≤200MB, total duration 2–15.2s; reference audio: total size ≤15MB, total duration 2–15.2s. Illegal resolution/ratio returns 1001005; count overflow returns 1001006; size overflow returns 1001003; illegal total input video/audio duration returns 1001008.
Output notes: Get the result video from output.url; billed as resolution unit price × duration.
{
"prompt": "slow push-in, warm sunset atmosphere",
"outputRes": "720P",
"outputDuration": 8,
"ratio": "16:9",
"imageUrls": ["https://example.com/ref.jpg"]
}
seedance-2.0
Capability code: video-seedance-2-0
Capability: seedance-2.0 video generation with higher output resolution tiers.
Use cases: text-to-video / image-to-video that need 1080P / 4K output.
Request notes: Body VideoSeedanceReqDto; fields same as Mini; outputRes must be uppercase 480P/720P/1080P/4K. Reference videos: total size ≤200MB, total duration 2–15.2s; reference audio: total size ≤15MB, total duration 2–15.2s. Illegal resolution/ratio returns 1001005; count overflow returns 1001006; size overflow returns 1001003; illegal total input video/audio duration returns 1001008. Billing matches Mini.
Output notes: Get the result video from output.url.
{
"prompt": "city night timelapse, neon reflections",
"outputRes": "1080P",
"outputDuration": 10,
"ratio": "16:9"
}
seedance-2.5
Capability code: video-seedance-2-5
Capability: seedance-2.5 video generation with longer output duration support.
Use cases: multimodal text-to-video / image-to-video with 480P / 720P output and duration up to 30 seconds.
Request notes: Body VideoSeedance25ReqDto; required prompt, outputRes (uppercase 480P/720P), outputDuration (4–30); optional imageUrls (max 9), videoUrls+audioUrls (combined max 3), ratio, clientTaskId. Reference videos: total size ≤200MB, total duration 2–15.2s; reference audio: total size ≤15MB, total duration 2–15.2s. Illegal resolution/ratio returns 1001005; count overflow returns 1001006; size overflow returns 1001003; illegal total input video/audio duration returns 1001008.
Output notes: Get the result video from output.url; billed as resolution unit price × duration.
{
"prompt": "sunset over the beach, gentle waves",
"outputRes": "720P",
"outputDuration": 20,
"ratio": "16:9",
"imageUrls": ["https://example.com/ref.jpg"]
}
grok-imagine-video-1.5
Capability code: video-grok-imagine-video-1-5
Capability: Generates a short video from a prompt and optional reference image.
Use cases: single-image reference or pure text-to-video.
Request notes: Body VideoPromptReqDto; required prompt, outputRes (uppercase 720P only), outputDuration (4/6/8/10/12/15 only); optional imageUrls (max 1), ratio (1:1/16:9/9:16/4:3/3:4/3:2/2:3), clientTaskId. Illegal resolution/ratio returns 1001005; too many images returns 1001006; illegal duration returns 1001007.
Output notes: Get the result video from output.url; billed as resolution unit price × duration.
{
"prompt": "a person walking slowly along a forest path",
"outputRes": "720P",
"outputDuration": 6,
"ratio": "9:16",
"imageUrls": ["https://example.com/ref.jpg"]
}
Pixverse V6
Capability code: video-pixverse-v6
Capability: Generates a short video from a prompt and optional reference images.
Use cases: text-to-video / image-to-video with multiple resolution and ratio options.
Request notes: Body VideoPromptReqDto; required prompt, outputRes (must be uppercase 360P/540P/720P/1080P), outputDuration (1–15); optional imageUrls (max 3), ratio (auto/16:9/4:3/1:1/3:4/9:16/2:3/3:2/21:9), clientTaskId. Illegal resolution/ratio returns 1001005; too many images returns 1001006; illegal duration returns 1001007.
Output notes: Get the result video from output.url; billed as resolution unit price × duration.
{
"prompt": "camera slowly orbits around the product",
"outputRes": "720P",
"outputDuration": 5,
"ratio": "auto",
"imageUrls": ["https://example.com/product.jpg"]
}
MiniMax H3
Capability code: video-minimax-h3
Capability: Generates a short video from a prompt and optional reference images.
Use cases: longer clips and multi-image references.
Request notes: Body VideoPromptReqDto; required prompt, outputRes (must be uppercase 768P/2K), outputDuration (4–15); optional imageUrls (max 9), ratio (21:9/16:9/4:3/1:1/3:4/9:16), clientTaskId. Illegal resolution/ratio returns 1001005; too many images returns 1001006; illegal duration returns 1001007.
Output notes: Get the result video from output.url; billed as resolution unit price × duration.
{
"prompt": "wide aerial shot of the coastline, sunlight on the sea",
"outputRes": "2K",
"outputDuration": 8,
"ratio": "16:9"
}
Common APIs
Includes task query and user points query.
Query Task Status (generic polling API)
| Param | Type | Required | Description |
|---|---|---|---|
task_id | String | Yes | The taskId returned at task creation (path parameter) |
reqInfoJson is returned only for text-to-image or multi-image-to-image tasks; input is returned only when an input resource URL exists; output is returned only when status=completed.Example · processing (single image) processing
{
"code": 0,
"msg": "request success",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000-20260717103000",
"status": "processing",
"pointsConsumed": 10,
"clientTaskId": "my-task-001",
"input": { "url": "https://example.com/photo.jpg", "width": 800, "height": 600, "size": 123456 }
}
}
Example · processing (multi-image-to-image) processing
{
"code": 0,
"msg": "request success",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000-20260717103000",
"status": "processing",
"pointsConsumed": 10,
"clientTaskId": "my-task-002",
"reqInfoJson": {
"prompt": "a cyberpunk city at night",
"imageUrls": [
"https://example.com/ref1.jpg",
"https://example.com/ref2.jpg"
],
"resolution": "2K",
"ratio": "16:9"
},
"input": { "url": "https://example.com/ref1.jpg", "width": 1024, "height": 768, "size": 234567 }
}
}
reqInfoJson returns the user's original request info (including the imageUrls array); input returns only the primary input image info.Example · processing (text-to-image) processing
{
"code": 0,
"msg": "request success",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000-20260717103000",
"status": "processing",
"pointsConsumed": 10,
"clientTaskId": "my-task-003",
"reqInfoJson": {
"prompt": "a corgi wearing sunglasses",
"resolution": "2K",
"ratio": "1:1"
}
}
}
input field; reqInfoJson returns the user's original request info.Example · completed completed
{
"code": 0,
"msg": "request success",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000-20260717103000",
"status": "completed",
"pointsConsumed": 10,
"clientTaskId": "my-task-001",
"input": { "url": "https://example.com/photo.jpg", "width": 800, "height": 600, "size": 123456 },
"output": { "url": "https://cdn.example.com/output/result.jpg", "width": 1600, "height": 1200, "size": 654321 }
}
}
Example · failed failed
{
"code": 0,
"msg": "request success",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000-20260717103000",
"status": "failed",
"pointsConsumed": 10,
"clientTaskId": "my-task-001",
"errorCode": 999,
"errorMsg": "processing failed",
"input": { "url": "https://example.com/photo.jpg", "width": 800, "height": 600, "size": 123456 }
}
}
1002001 when the task does not exist; 1002002 when the task has been deleted (data is null).Get Remaining Points
Returns the available points balance for the current token (excluding frozen points). This matches the balance check performed before task creation.
Response example
{
"code": 0,
"msg": "request success",
"data": {
"remainPoints": 1000
}
}
Code Examples
Using "Old Photo Restoration" to show the full flow (submit task + poll result). For other APIs, just change the request path and body.
Python
import time
import requests
BASE_URL = "https://api.developer.magictiger.ai"
TOKEN = "YOUR_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
def create_task(path, payload):
resp = requests.post(f"{BASE_URL}/v1/{path}", json=payload, headers=HEADERS, timeout=30)
data = resp.json()
if data["code"] != 0:
raise RuntimeError(f"create task failed: {data['code']} {data['msg']}")
return data["data"]["taskId"]
def wait_result(task_id, interval=3, timeout=300):
deadline = time.time() + timeout
while time.time() < deadline:
data = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
if data["status"] == "completed":
return data
if data["status"] == "failed":
raise RuntimeError(f"task failed: {data.get('errorMsg')}")
time.sleep(interval)
raise TimeoutError("task timeout")
tid = create_task("photo-restore", {"imageUrl": "https://example.com/old-photo.jpg"})
print("output url:", wait_result(tid)["output"]["url"])
Node.js
const BASE_URL = "https://api.developer.magictiger.ai";
const TOKEN = "YOUR_TOKEN";
const headers = { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" };
async function createTask(path, payload) {
const resp = await fetch(`${BASE_URL}/v1/${path}`, { method: "POST", headers, body: JSON.stringify(payload) });
const { code, msg, data } = await resp.json();
if (code !== 0) throw new Error(`create task failed: ${code} ${msg}`);
return data.taskId;
}
async function waitResult(taskId, interval = 3000, timeout = 300000) {
const deadline = Date.now() + timeout;
while (Date.now() < deadline) {
const { data } = await (await fetch(`${BASE_URL}/v1/tasks/${taskId}`, { headers })).json();
if (data.status === "completed") return data;
if (data.status === "failed") throw new Error(`task failed: ${data.errorMsg}`);
await new Promise((r) => setTimeout(r, interval));
}
throw new Error("task timeout");
}
(async () => {
const tid = await createTask("photo-restore", { imageUrl: "https://example.com/old-photo.jpg" });
console.log("output url:", (await waitResult(tid)).output.url);
})();
Java(OkHttp)
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json");
String base = "https://api.developer.magictiger.ai", token = "YOUR_TOKEN";
RequestBody body = RequestBody.create(
"{\"imageUrl\":\"https://example.com/old-photo.jpg\"}", JSON);
Request req = new Request.Builder()
.url(base + "/v1/photo-restore")
.header("Authorization", "Bearer " + token)
.post(body)
.build();
try (Response resp = client.newCall(req).execute()) {
System.out.println(resp.body().string()); // parse data.taskId, then poll GET /v1/tasks/{taskId}
}
Best Practices
- Prepare images: prefer stable, publicly accessible HTTPS direct links; avoid short-lived signed URLs that may expire before the server downloads them (error code
1001002). - Control size: keep each image ≤ 20MB; compress before uploading to speed up downloads and reduce failures.
- Idempotency: generate a unique
clientTaskIdper business request to avoid duplicate tasks and duplicate billing on retries. - Polling backoff: start at ~2s and gradually back off to ~5s to avoid triggering rate limiting.
- Timeout fallback: set an overall max wait (e.g. 5 minutes); on timeout, run your fallback logic and alert.
- Handle degradation: when you receive
code=-1with "Service temporarily unavailable", retry with exponential backoff. - Persist results: download the
output.urlimage promptly and store it in your own storage to avoid loss after the URL expires. - Video watermark coordinates: origin is the frame top-left;
X/Yare the watermark top-left,W/Hare width/height in pixels; JSON field names must be uppercase.
FAQ
Q1: The task stays in queuing / processing — is that normal?
Yes, it means the task is queued or being processed. Keep polling with a backoff strategy; if it takes far longer than expected, contact support with the taskId.
Q2: Why do I get 1001002 resource URL validation failed?
Usually the image URL is unreachable, requires auth, has expired, or is not a direct image link. Make sure the URL can be downloaded anonymously by the server.
Q3: Is clientTaskId required?
No. But a unique value is strongly recommended for idempotency, to avoid duplicate tasks and duplicate billing.
Q4: How do I know how many points each task consumed?
The TaskResultDto.pointsConsumed field returns the points consumed by the task.
Q5: Can the output image URL be used long-term?
Not recommended. The output URL has an expiry; download and store it in your own storage promptly after completion.
Q6: What should I do when I receive "Service temporarily unavailable"?
This is a degraded response (code=-1). Retry later with exponential backoff.
API Cheat Sheet
Browse by category: Image APIs, Video APIs, and Common APIs.
| API | Method | Path | Body |
|---|---|---|---|
| Image APIs | |||
| Old Photo Restoration | POST | /v1/photo-restore | PhotoRestoreReqDto |
| Photo Enhancer | POST | /v1/photo-enhance | PhotoRestoreReqDto |
| Old Photo Restoration Pro | POST | /v1/photo-enhance-restore | PhotoRestoreReqDto |
| Image Upscaler | POST | /v1/photo-sr | PhotoRestoreReqDto |
| Photo Unblur | POST | /v1/photo-deblurring | PhotoRestoreReqDto |
| Scratch Removal | POST | /v1/photo-scratch-removal | PhotoRestoreReqDto |
| Photo Colorizer | POST | /v1/photo-colorization | PhotoRestoreReqDto |
| Damaged Photo Restoration | POST | /v1/photo-damaged-restore | PhotoRestoreReqDto |
| Low-Light Enhancement | POST | /v1/photo-low-light-enhance | PhotoRestoreReqDto |
| Generative Fill | POST | /v1/photo-partial-repainting | PhotoPromptReqDto |
| AI Clothes Changer | POST | /v1/photo-change-clothes | PhotoChangeReqDto |
| AI Image Expander | POST | /v1/photo-expansion | PhotoExpansionDto |
| Sky Filter (Offline) | POST | /v1/photo-sky-filter | - |
| Face Dynamization (Offline) | POST | /v1/photo-face-dynamization | - |
| Image Filters | POST | /v1/photo-filter | PhotoSpecsCodeReqDto |
| AI Portrait | POST | /v1/photo-portrait | PhotoSpecsCodeReqDto |
| AI Travel Photos | POST | /v1/photo-portrait-iphotoo | IPhotooSpecsCodeReqDto |
| HeTu Image Filters | POST | /v1/photo-hetu-filter | PhotoFilterReqDto |
| doubao-seedream-4-0 | POST | /v1/photo-doubao-seedream-4-0 | PhotoGptImagePromptReqDto |
| doubao-seedream-4-5 | POST | /v1/photo-doubao-seedream-4-5 | PhotoGptImagePromptReqDto |
| doubao-seedream-5-0 | POST | /v1/photo-doubao-seedream-5-0-lite | PhotoGptImagePromptReqDto |
| doubao-seedream-5-0-pro | POST | /v1/photo-doubao-seedream-5-0-pro | PhotoGptImagePromptReqDto |
| gpt-image-2 | POST | /v1/photo-gpt-image-2 | PhotoGptImagePromptReqDto |
| gpt-image-2.5-flare | POST | /v1/photo-gpt-image-2-5-flare | PhotoGptImagePromptReqDto |
| gpt-image-2.5-sunburst | POST | /v1/photo-gpt-image-2-5-sunburst | PhotoGptImagePromptReqDto |
| gemini-3.1-flash-image | POST | /v1/photo-gemini-3-1-flash-image | PhotoGptImagePromptReqDto |
| gemini-3-pro-image | POST | /v1/photo-gemini-3-pro-image | PhotoGptImagePromptReqDto |
| Hetu Image Large Model | POST | /v1/photo-hetu-image | PhotoGptImagePromptReqDto |
| Background Remover | POST | /v1/photo-remove-bg | PhotoRestoreReqDto |
| Object Remover | POST | /v1/photo-target-removal | PhotoRestoreReqDto |
| Image Watermark Remover | POST | /v1/photo-remove-watermark | PhotoRestoreReqDto |
| Face Cutout | POST | /v1/photo-face-segmentation | PhotoRestoreReqDto |
| AI Eraser | POST | /v1/photo-inpainting | PhotoRestoreReqDto |
| AI ID Photo (Custom Outfit) | POST | /v1/photo-id-photo | PhotoIDPhotoReqDto |
| Standard AI ID Photo | POST | /v1/photo-id-photo-standard | PhotoIDPhotoReqDto |
| Video APIs | |||
| Video Enhancement | POST | /v1/video-sr | VideoEnhanceReqDto |
| Face Restoration | POST | /v1/video-sr-face | VideoEnhanceReqDto |
| Video Denoiser | POST | /v1/video-denoising | VideoEnhanceReqDto |
| AI Color Correction | POST | /v1/video-color-enhance | VideoEnhanceReqDto |
| Video Colorizer | POST | /v1/video-colorization | VideoEnhanceReqDto |
| Night Enhancement | POST | /v1/video-low-light-enhance | VideoEnhanceReqDto |
| Detail Enhancement | POST | /v1/video-high-texture-sr | VideoEnhanceReqDto |
| Scan Line Removal | POST | /v1/video-deinterlace | VideoEnhanceReqDto |
| Video Watermark Remover | POST | /v1/video-remove-watermark | VideoRmWaterMarkReqDto |
| Video Background Remover | POST | /v1/video-remove-background | VideoRmBgReqDto |
| Hetu Style Video - Single Image | POST | /v1/video-hetu-style | VideoStyleFilterReqDto |
| Hetu Style Video - Custom | POST | /v1/video-hetu-style-custom | VideoStyleFilterCustomReqDto |
| Hetu Style Video - Two Images & First/Last Frames | POST | /v1/video-hetu-style-frames | VideoStyleFilterFramesReqDto |
| seedance-2.0-mini | POST | /v1/video-seedance-2-0-mini | VideoSeedanceReqDto |
| seedance-2.0 | POST | /v1/video-seedance-2-0 | VideoSeedanceReqDto |
| seedance-2.5 | POST | /v1/video-seedance-2-5 | VideoSeedance25ReqDto |
| grok-imagine-video-1.5 | POST | /v1/video-grok-imagine-video-1-5 | VideoPromptReqDto |
| Pixverse V6 | POST | /v1/video-pixverse-v6 | VideoPromptReqDto |
| MiniMax H3 | POST | /v1/video-minimax-h3 | VideoPromptReqDto |
| Common APIs | |||
| Query Task Status | GET | /v1/tasks/{task_id} | None (path param) |
| Get Remaining Points | GET | /v1/user/points | None |
Glossary
| Term | Description |
|---|---|
| Async task | A task mode that returns a taskId immediately and requires polling for the final result |
| taskId | Unique task identifier returned at creation, used for polling |
| clientTaskId | Client-defined task ID for idempotency |
| reqInfoJson | User's original request info returned on query for text-to-image or multi-image-to-image tasks |
| pointsConsumed | Number of points consumed per task |
| remainPoints | Current available points balance (excluding frozen points) |
| Bearer Token | Token auth in the header as Authorization: Bearer {token} |
| Rate limit / Circuit breaker / Isolation | Request-protection mechanisms enabled server-side for stability; return a degraded response when triggered |
Changelog
| Version | Date | Notes |
|---|---|---|
| v1.13 | 2026-10-16 | photo-portrait-iphotoo market display name unified as AI旅拍 / AI Travel Photos (capability code and path unchanged) |
| v1.12 | 2026-10-13 | photo-portrait-iphotoo IPhotooSpecsCodeReqDto now uses imageUrls (max 2) instead of single imageUrl |
| v1.11 | 2026-10-12 | photo-filter and photo-portrait add optional ratio (default 2:3) and resolution (default 1K, supports 1K/2K)Added POST /v1/photo-portrait-iphotoo (IPhotooSpecsCodeReqDto, with beauty parameters)ID photo split into photo-id-photo (custom outfit) and photo-id-photo-standard (standard styles); request body is now PhotoIDPhotoReqDto (preBeauty, outputFmt) |
| v1.10 | 2026-09-18 | photo-gpt-image-2-5-flare and photo-gpt-image-2-5-sunburst resolution supports 1K / 2K / 4K (3K no longer supported) |
| v1.9 | 2026-09-15 | Fixed photo-gpt-image-2 API path (was /v1/photo-photo-gpt-image-2)Added photo-gpt-image-2-5-flare and photo-gpt-image-2-5-sunburst text-to-image / image-to-image APIsAdded video-seedance-2-5 video generation API (outputDuration supports 4–30 seconds)video-hetu-style-custom underlying generation model upgraded to v2.0 (API path and request parameters unchanged)Added GET /v1/user/points to query remaining user points |
| v1.8 | 2026-09-03 | Unified image/video API display names with market-facing Algorithm Store names (capability codes and API paths unchanged) |
| v1.7 | 2026-08-28 | Seedance reference video total size ≤200MB, total duration 2–15s Reference audio total size ≤15MB, total duration 2–15s Added error code 1001008 (illegal input video/audio duration)1001003 message now includes audio |
| v1.6 | 2026-08-24 | Added Seedance 2.0 Mini / Seedance 2.0 / Grok Imagine Video 1.5 / PixVerse V6 / MiniMax H3 Error codes split: 1001005 is resolution/ratio only; added 1001006 (count exceeded) and 1001007 (illegal duration) |
| v1.5 | 2026-08-20 | Added Overview section「How to get specsCode」: obtain style codes and sample images from Algorithm Store detail pages Clarified video enhance resolution specsCode vs Algorithm Store style codes |
| v1.4 | 2026-08-19 | Added Video Background Removal API docs Output is alpha-channel MOV — use an alpha-capable player for preview (mpv recommended) |
| v1.3 | 2026-08-19 | Hetu Style Video / Frames: removed outputDuration and outputRes (determined by style config; billed by style unit price)Custom still requires duration and uppercase resolution, billed as resolution unit price × duration |
| v1.2 | 2026-08-17 | Added background removal, target removal, watermark removal, face segmentation, one-click inpainting, ID photo Added 9 video enhance APIs and 3 Hetu style video APIs Added video DTOs and common validation rules Docs reorganized into Image / Video / Common categories |
| v1.1 | 2026-08-04 | API changes: added AI Image Filter, AI Portrait, AI Hetu Image Filter, Doubao Seedream 4.0/4.5/5.0-lite/5.0-pro, GPT Image 2, Gemini 3.1 Flash Image, Gemini 3 Pro Image, AI Hetu Image photo-filter switched to specs-code mode Sky Filter and Face Dynamization taken offline |
| v1.0 | 2026-07-17 | Initial release covering multiple image-processing APIs and 1 task-query API Added code examples, best practices, FAQ and glossary |