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:

  1. Call a specific processing API to submit a task. It returns taskId and an initial status (queuing).
  2. Poll the generic task-query API GET /v1/tasks/{task_id} (shared by image and video tasks) until the status becomes completed or failed.
  3. On success, get the processed image or video from output.url in 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:

  1. Sign in to the PicMa Studio Developer Platform
  2. Open Algorithm Store and find the algorithm you want to integrate
  3. Open the capability detail page to view the specsCode and sample output images
  4. Choose the effect you want from the samples and use the matching specsCode in your API request
Note: for video enhance APIs, 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

Base path
/v1
Auth
Bearer Token
Request format
application/json
Response format
application/json
Image size limit
≤ 20MB each
Video size limit
≤ 100MB each
Service protection
Rate limit / Circuit breaker / Isolation
Full request URL In production, concatenate the domain and path, for example: 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
Note Max 20MB per image; max 100MB per video for enhance APIs. When rate limiting / circuit breaking / isolation triggers, a degraded response is returned — please retry later.

Common Response

All APIs return a unified ReplyAi structure:

{
  "code": 0,
  "msg": "request success",
  "data": { }
}
FieldTypeDescription
codeintStatus code. 0 means success; others are error codes
msgStringStatus message
dataObjectBusiness payload (task APIs return TaskResultDto)

Error Codes

CodeDescription
0Success
-1Request failed / service degraded (fallback when circuit breaking, rate limiting or isolation triggers)
3Invalid parameter
4Illegal parameter (e.g. expansion coordinates out of bounds)
5Parameter signature validation failed
6Trial quota exhausted
9Permission denied
999Server error, please retry later
1001001Task creation failed
1001002Resource (image/video) URL validation failed
1001003Resource (image/video/audio) size exceeds the limit
1001004Unsupported file type
1001005Unsupported resolution / ratio (illegal resolution or ratio value)
1001006Resource (image/video/audio) count exceeds the limit
1001007Illegal output duration
1001008Resource (video/audio) duration is illegal
1002001Task ID does not exist
1002002Task has been deleted
1003001Interface has been discontinued / taken offline
1003002Failed 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.

FieldTypeRequiredDescription
imageUrlStringYesURL of the image to process
clientTaskIdStringNoClient-defined task ID for idempotency

PhotoPromptReqDto (with prompt)

Extends PhotoRestoreReqDto。Used by: Generative Fill.

FieldTypeRequiredDescription
imageUrlStringYesURL of the composite image (original + mask side-by-side; see Generative Fill input requirements)
clientTaskIdStringNoClient-defined task ID
promptStringYesText prompt describing the desired content for the white mask region

PhotoChangeReqDto (with target image)

Extends PhotoRestoreReqDto。Used by: AI Clothes Changer.

FieldTypeRequiredDescription
imageUrlStringYesOriginal image URL
clientTaskIdStringNoClient-defined task ID
changeImageUrlStringYesTarget image URL (e.g. a clothing image)

PhotoExpansionDto (expansion body)

Extends PhotoRestoreReqDto。Used by: AI Image Expander.

FieldTypeRequiredDescription
imageUrlStringYesURL of the image to process
clientTaskIdStringNoClient-defined task ID
expandImagesJsonDtoExpandImagesJsonDtoYesExpansion parameters, see below

ExpandImagesJsonDto

FieldTypeRequiredDescription
widthIntegerYesCanvas width
heightIntegerYesCanvas height
startXIntegerYesTop-left start X coordinate
startYIntegerYesTop-left start Y coordinate
ValidationstartX 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.

FieldTypeRequiredDescription
imageUrlStringYesURL of the image to process
clientTaskIdStringNoClient-defined task ID
specsCodeStringYesSpecs code (maps to a specific filter / portrait style)
genderIntegerNoGender: 0 = male, 1 = female (optional for multi-person cases)
ratioStringNoOutput 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
resolutionStringNoOutput resolution, default 1K; only 1K / 2K (uppercase)
For style specsCode, see Overview · How to get specsCode. Invalid ratio returns 1001005.

PhotoFilterReqDto (specs-code filter)

Extends PhotoRestoreReqDto. Used by: HeTu Image Filters.

FieldTypeRequiredDescription
imageUrlStringYesURL of the image to process
clientTaskIdStringNoClient-defined task ID
specsCodeStringYesSpecs code (Hetu filter style; returns 1003002 when invalid)
For style specsCode, see Overview · How to get specsCode.

PhotoIDPhotoReqDto (ID photo)

Extends PhotoRestoreReqDto. Used by: AI ID Photo (Custom Outfit), Standard AI ID Photo.

FieldTypeRequiredDescription
imageUrlStringYesURL of the image to process
clientTaskIdStringNoClient-defined task ID
specsCodeStringYesID photo specs code (returns 1003002 when invalid)
preBeautyIntegerNoBeauty filter: 1 = off, 2 = on; default off when omitted
outputFmtStringNoOutput 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).

FieldTypeRequiredDescription
imageUrlsList<String>NoInput image URLs, max 2; single-person portrait: 1 image; two-person: 1 group photo or 2 individual photos
clientTaskIdStringNoClient-defined task ID
specsCodeStringYesAI Travel Photos style code (returns 1003002 when invalid)
genderIntegerNoGender: 0 = male, 1 = female
ratioStringNoOutput aspect ratio, default 2:3; same allowed values as PhotoSpecsCodeReqDto.ratio
resolutionStringNoOutput resolution, default 1K; only 1K / 2K
beautyIntegerNoBeauty switch: 0 = off, 1 = on
beautyLevelIntegerNoBeauty level 0–10; applies when beauty=1
Validation More than 2 items in 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.

FieldTypeRequiredDescription
promptStringYesText prompt
clientTaskIdStringNoClient-defined task ID
imageUrlsList<String>NoInput image URL list, multiple images supported (omit for pure text-to-image; max count per API listed below)
resolutionStringNoOutput resolution, default 2K; allowed values vary by API (e.g. 1K/2K/4K)
ratioStringNoOutput aspect ratio, allowed values vary by API
Validation Invalid 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.

FieldTypeRequiredDescription
imageUrlStringYesURL of the image to process
clientTaskIdStringNoClient-defined task ID
templateNumberIntegerYesTemplate index

VideoEnhanceReqDto (video enhance)

Used by: Video Enhancement, Face Restoration, Video Denoiser, AI Color Correction, Video Colorizer, Night Enhancement, Detail Enhancement, Scan Line Removal.

FieldTypeRequiredDescription
videoUrlStringYesInput video URL (≤100MB)
clientTaskIdStringNoClient-defined task ID
outputFmtStringNoOutput container: mp4/mov/mkv/ts, default mp4
encodeTypeIntegerNo0=H.264, 1=H.265, default 0
encodeQualityIntegerNo0low / 1medium / 2high, default 1
specsCodeStringNoMust be uppercase: 720P/1080P/4K/8K; omit to match input resolution
Case sensitive Resolution values such as 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.

FieldTypeRequiredDescription
(inherited fields)——Same as VideoEnhanceReqDto
waterMarkParamVideoWaterMarkDtoYesWatermark bounding box (see below)

VideoWaterMarkDto (JSON field names must be uppercase)

Coordinate system Origin is the frame top-left (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).
FieldTypeRequiredDescription
XIntegerYesWatermark top-left X (≥0)
YIntegerYesWatermark top-left Y (≥0)
WIntegerYesWatermark width (≥0)
HIntegerYesWatermark height (≥0)

VideoRmBgReqDto (Video background removal)

Used by: Video Background Remover.

FieldTypeRequiredDescription
videoUrlStringYesInput video URL (≤100MB)
clientTaskIdStringNoClient-defined task ID
Billing Charged as probed duration (seconds) × resolution tier unit price (tier is auto-detected from input resolution).

VideoStyleFilterReqDto (Hetu style video)

Used by: Hetu Style Video - Single Image.

FieldTypeRequiredDescription
imageUrlStringYesInput image URL (≤20MB)
clientTaskIdStringNoClient-defined task ID
specsCodeStringYesStyle specs code (returns 1003002 if invalid); duration and output specs are determined by the style config
Billing Charged by the style unit price of 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).

FieldTypeRequiredDescription
imageUrlStringYesInput image URL (≤20MB)
clientTaskIdStringNoClient-defined task ID
outputDurationIntegerYesOutput duration (seconds), 2–5
outputResStringYesMust be uppercase: 480P / 720P
promptStringYesCustom prompt
Case sensitiveoutputRes accepts only uppercase 480P and 720P.
Billing Charged as resolution unit price × outputDuration.

VideoStyleFilterFramesReqDto (Hetu style video frames)

Used by: Hetu Style Video - Two Images & First/Last Frames.

FieldTypeRequiredDescription
imageUrlsList<String>NoStart/end frame images, max 2; excess returns 1001006
clientTaskIdStringNoClient-defined task ID
specsCodeStringYesStyle specs code (returns 1003002 if invalid); duration and output specs are determined by the style config
Billing Charged by the style unit price of 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.

FieldTypeRequiredDescription
promptStringYesText prompt
outputResStringYesOutput resolution (must be uppercase); Mini: 480P/720P; 2.0: 480P/720P/1080P/4K
outputDurationIntegerYesOutput duration (seconds), 4–15
imageUrlsList<String>NoReference images, max 9; each ≤20MB; jpeg/png/webp/bmp/tiff/gif/heic
videoUrlsList<String>NoReference videos; combined with audioUrls max 3; total size ≤200MB; total duration 2–15.2s; mp4/mov
audioUrlsList<String>NoReference audio; combined with videoUrls max 3; total size ≤15MB; total duration 2–15.2s; wav/mp3
ratioStringNo1:1 / 4:3 / 3:4 / 16:9 / 9:16
clientTaskIdStringNoClient-defined task ID
Validation Illegal resolution or ratio returns 1001005; too many images or video+audio items returns 1001006; size overflow returns 1001003; illegal total input video/audio duration returns 1001008.
Billing Charged as resolution unit price × 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.

Validation Other rules are the same as 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.

FieldTypeRequiredDescription
promptStringYesText prompt
outputResStringYesOutput resolution (must be uppercase; values per API)
outputDurationIntegerYesOutput duration in seconds (values per API)
imageUrlsList<String>NoReference images (each ≤20MB; max count per API)
ratioStringNoOutput aspect ratio (values per API)
clientTaskIdStringNoClient-defined task ID
Validation Illegal resolution or ratio returns 1001005; too many reference images returns 1001006; illegal duration returns 1001007.
Billing Charged as resolution unit price × outputDuration.

UserPointsDto (User Remaining Points)

Used by: Get Remaining Points (§6.2).

FieldTypeDescription
remainPointsIntegerRemaining 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:

ScenarioReturned fields
Create task (POST)taskId、status、pointsConsumed
Query task (GET /v1/tasks/{task_id})All fields below (conditionally returned by task status)
FieldTypeDescription
taskIdStringTask ID (used for polling)
statusStringqueuing queuing / processing processing / completed completed / failed failed
pointsConsumedIntegerPoints consumed (from points record; may be null)
clientTaskIdStringClient-defined task ID (echoed as-is on query)
reqInfoJsonObjectRequest 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.)
errorMsgStringError message (returned only when status=failed)
errorCodeIntegerError code (returned only when status=failed)
inputMediaInfoInput image info (returned only when the task has an input image URL; may be absent for pure text-to-image tasks)
outputMediaInfoOutput 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:

FieldAssembly rule
reqInfoJsonReturned 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.)
clientTaskIdEchoes the clientTaskId
pointsConsumedRead from points record; null
errorCode / errorMsg仅当 status=failed 时返回
inputReturned only when an input image URL exists, with url、width、height、size
output仅当 status=completed 时返回

MediaInfo

FieldTypeDescription
urlStringResource URL
widthIntegerWidth (px)
heightIntegerHeight (px)
sizeLongFile 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.

Category note Image APIs cover basic restoration/enhancement, local editing, filters/portraits, text-to-image / image-to-image, segmentation and ID photos. See Video APIs below.

Old Photo Restoration

POST/v1/photo-restore

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

POST/v1/photo-enhance

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

POST/v1/photo-enhance-restore

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

POST/v1/photo-sr

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

POST/v1/photo-deblurring

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

POST/v1/photo-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

POST/v1/photo-colorization

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

POST/v1/photo-damaged-restore

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

POST/v1/photo-low-light-enhance

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

POST/v1/photo-partial-repainting

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.

Input image requirements 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 be 2W×H (equal halves, horizontal stitch)
Partial repainting input sample: left original, right black-and-white mask
Composite sample (bundled with the docs): left = original, right = mask (white = repaint, black = keep)
{
  "imageUrl": "https://example.com/original-with-mask.jpg",
  "prompt": "dress the person in a red dress"
}

AI Clothes Changer

POST/v1/photo-change-clothes

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

POST/v1/photo-expansion

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)

POST/v1/photo-sky-filter

Capability code: photo-sky-filter

Offline This API has been discontinued and returns error code 1003001 (interface offline).

Face Dynamization (Offline)

POST/v1/photo-face-dynamization

Capability code: photo-face-dynamization

Offline This API has been discontinued and returns error code 1003001 (interface offline).

Image Filters

POST/v1/photo-filter

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

POST/v1/photo-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

POST/v1/photo-portrait-iphotoo

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

POST/v1/photo-hetu-filter

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

POST/v1/photo-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

POST/v1/photo-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

POST/v1/photo-doubao-seedream-5-0-lite

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

POST/v1/photo-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

POST/v1/photo-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

POST/v1/photo-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

POST/v1/photo-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

POST/v1/photo-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

POST/v1/photo-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

POST/v1/photo-hetu-image

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

POST/v1/photo-remove-bg

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

POST/v1/photo-target-removal

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

POST/v1/photo-remove-watermark

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

POST/v1/photo-face-segmentation

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

POST/v1/photo-inpainting

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)

POST/v1/photo-id-photo

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

POST/v1/photo-id-photo-standard

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.

Category note Video APIs cover video enhancement (super-resolution, denoising, colorization, watermark removal, etc.), video background removal, Hetu style image-to-video, and Seedance / Grok / PixVerse / MiniMax video generation. See Image APIs above.

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

POST/v1/video-sr

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

POST/v1/video-sr-face

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

POST/v1/video-denoising

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

POST/v1/video-color-enhance

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

POST/v1/video-colorization

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

POST/v1/video-low-light-enhance

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

POST/v1/video-high-texture-sr

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

POST/v1/video-deinterlace

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

POST/v1/video-remove-watermark

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

POST/v1/video-remove-background

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.

Playback compatibility: output includes an alpha channel and requires an alpha-capable player; default system players and many web players may not render transparency correctly — mpv (browser extension or desktop app) is recommended for preview.
{
  "videoUrl": "https://example.com/input.mp4"
}

Hetu Style Video - Single Image

POST/v1/video-hetu-style

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

POST/v1/video-hetu-style-custom

Capability code: video-hetu-style-custom

Model upgrade API path and request parameters are unchanged; the underlying generation model was upgraded to v2.0 on 2026-09-15.

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

POST/v1/video-hetu-style-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

POST/v1/video-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

POST/v1/video-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

POST/v1/video-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

POST/v1/video-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

POST/v1/video-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

POST/v1/video-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)

GET/v1/tasks/{task_id}
ParamTypeRequiredDescription
task_idStringYesThe taskId returned at task creation (path parameter)
Response notes Image and video tasks share this query API. 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 }
  }
}
Note For multi-image-to-image tasks, 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"
    }
  }
}
Note Pure text-to-image tasks have no input image, so 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 }
  }
}
Note Error code 1002001 when the task does not exist; 1002002 when the task has been deleted (data is null).

Get Remaining Points

GET/v1/user/points

Returns the available points balance for the current token (excluding frozen points). This matches the balance check performed before task creation.

Request parameters None.

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

  1. 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).
  2. Control size: keep each image ≤ 20MB; compress before uploading to speed up downloads and reduce failures.
  3. Idempotency: generate a unique clientTaskId per business request to avoid duplicate tasks and duplicate billing on retries.
  4. Polling backoff: start at ~2s and gradually back off to ~5s to avoid triggering rate limiting.
  5. Timeout fallback: set an overall max wait (e.g. 5 minutes); on timeout, run your fallback logic and alert.
  6. Handle degradation: when you receive code=-1 with "Service temporarily unavailable", retry with exponential backoff.
  7. Persist results: download the output.url image promptly and store it in your own storage to avoid loss after the URL expires.
  8. Video watermark coordinates: origin is the frame top-left; X/Y are the watermark top-left, W/H are 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.

APIMethodPathBody
Image APIs
Old Photo RestorationPOST/v1/photo-restorePhotoRestoreReqDto
Photo EnhancerPOST/v1/photo-enhancePhotoRestoreReqDto
Old Photo Restoration ProPOST/v1/photo-enhance-restorePhotoRestoreReqDto
Image UpscalerPOST/v1/photo-srPhotoRestoreReqDto
Photo UnblurPOST/v1/photo-deblurringPhotoRestoreReqDto
Scratch RemovalPOST/v1/photo-scratch-removalPhotoRestoreReqDto
Photo ColorizerPOST/v1/photo-colorizationPhotoRestoreReqDto
Damaged Photo RestorationPOST/v1/photo-damaged-restorePhotoRestoreReqDto
Low-Light EnhancementPOST/v1/photo-low-light-enhancePhotoRestoreReqDto
Generative FillPOST/v1/photo-partial-repaintingPhotoPromptReqDto
AI Clothes ChangerPOST/v1/photo-change-clothesPhotoChangeReqDto
AI Image ExpanderPOST/v1/photo-expansionPhotoExpansionDto
Sky Filter (Offline)POST/v1/photo-sky-filter-
Face Dynamization (Offline)POST/v1/photo-face-dynamization-
Image FiltersPOST/v1/photo-filterPhotoSpecsCodeReqDto
AI PortraitPOST/v1/photo-portraitPhotoSpecsCodeReqDto
AI Travel PhotosPOST/v1/photo-portrait-iphotooIPhotooSpecsCodeReqDto
HeTu Image FiltersPOST/v1/photo-hetu-filterPhotoFilterReqDto
doubao-seedream-4-0POST/v1/photo-doubao-seedream-4-0PhotoGptImagePromptReqDto
doubao-seedream-4-5POST/v1/photo-doubao-seedream-4-5PhotoGptImagePromptReqDto
doubao-seedream-5-0POST/v1/photo-doubao-seedream-5-0-litePhotoGptImagePromptReqDto
doubao-seedream-5-0-proPOST/v1/photo-doubao-seedream-5-0-proPhotoGptImagePromptReqDto
gpt-image-2POST/v1/photo-gpt-image-2PhotoGptImagePromptReqDto
gpt-image-2.5-flarePOST/v1/photo-gpt-image-2-5-flarePhotoGptImagePromptReqDto
gpt-image-2.5-sunburstPOST/v1/photo-gpt-image-2-5-sunburstPhotoGptImagePromptReqDto
gemini-3.1-flash-imagePOST/v1/photo-gemini-3-1-flash-imagePhotoGptImagePromptReqDto
gemini-3-pro-imagePOST/v1/photo-gemini-3-pro-imagePhotoGptImagePromptReqDto
Hetu Image Large ModelPOST/v1/photo-hetu-imagePhotoGptImagePromptReqDto
Background RemoverPOST/v1/photo-remove-bgPhotoRestoreReqDto
Object RemoverPOST/v1/photo-target-removalPhotoRestoreReqDto
Image Watermark RemoverPOST/v1/photo-remove-watermarkPhotoRestoreReqDto
Face CutoutPOST/v1/photo-face-segmentationPhotoRestoreReqDto
AI EraserPOST/v1/photo-inpaintingPhotoRestoreReqDto
AI ID Photo (Custom Outfit)POST/v1/photo-id-photoPhotoIDPhotoReqDto
Standard AI ID PhotoPOST/v1/photo-id-photo-standardPhotoIDPhotoReqDto
Video APIs
Video EnhancementPOST/v1/video-srVideoEnhanceReqDto
Face RestorationPOST/v1/video-sr-faceVideoEnhanceReqDto
Video DenoiserPOST/v1/video-denoisingVideoEnhanceReqDto
AI Color CorrectionPOST/v1/video-color-enhanceVideoEnhanceReqDto
Video ColorizerPOST/v1/video-colorizationVideoEnhanceReqDto
Night EnhancementPOST/v1/video-low-light-enhanceVideoEnhanceReqDto
Detail EnhancementPOST/v1/video-high-texture-srVideoEnhanceReqDto
Scan Line RemovalPOST/v1/video-deinterlaceVideoEnhanceReqDto
Video Watermark RemoverPOST/v1/video-remove-watermarkVideoRmWaterMarkReqDto
Video Background RemoverPOST/v1/video-remove-backgroundVideoRmBgReqDto
Hetu Style Video - Single ImagePOST/v1/video-hetu-styleVideoStyleFilterReqDto
Hetu Style Video - CustomPOST/v1/video-hetu-style-customVideoStyleFilterCustomReqDto
Hetu Style Video - Two Images & First/Last FramesPOST/v1/video-hetu-style-framesVideoStyleFilterFramesReqDto
seedance-2.0-miniPOST/v1/video-seedance-2-0-miniVideoSeedanceReqDto
seedance-2.0POST/v1/video-seedance-2-0VideoSeedanceReqDto
seedance-2.5POST/v1/video-seedance-2-5VideoSeedance25ReqDto
grok-imagine-video-1.5POST/v1/video-grok-imagine-video-1-5VideoPromptReqDto
Pixverse V6POST/v1/video-pixverse-v6VideoPromptReqDto
MiniMax H3POST/v1/video-minimax-h3VideoPromptReqDto
Common APIs
Query Task StatusGET/v1/tasks/{task_id}None (path param)
Get Remaining PointsGET/v1/user/pointsNone

Glossary

TermDescription
Async taskA task mode that returns a taskId immediately and requires polling for the final result
taskIdUnique task identifier returned at creation, used for polling
clientTaskIdClient-defined task ID for idempotency
reqInfoJsonUser's original request info returned on query for text-to-image or multi-image-to-image tasks
pointsConsumedNumber of points consumed per task
remainPointsCurrent available points balance (excluding frozen points)
Bearer TokenToken auth in the header as Authorization: Bearer {token}
Rate limit / Circuit breaker / IsolationRequest-protection mechanisms enabled server-side for stability; return a degraded response when triggered

Changelog

VersionDateNotes
v1.132026-10-16photo-portrait-iphotoo market display name unified as AI旅拍 / AI Travel Photos (capability code and path unchanged)
v1.122026-10-13photo-portrait-iphotoo IPhotooSpecsCodeReqDto now uses imageUrls (max 2) instead of single imageUrl
v1.112026-10-12photo-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.102026-09-18photo-gpt-image-2-5-flare and photo-gpt-image-2-5-sunburst resolution supports 1K / 2K / 4K (3K no longer supported)
v1.92026-09-15Fixed 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 APIs
Added 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.82026-09-03Unified image/video API display names with market-facing Algorithm Store names (capability codes and API paths unchanged)
v1.72026-08-28Seedance 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.62026-08-24Added 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.52026-08-20Added 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.42026-08-19Added Video Background Removal API docs
Output is alpha-channel MOV — use an alpha-capable player for preview (mpv recommended)
v1.32026-08-19Hetu 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.22026-08-17Added 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.12026-08-04API 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.02026-07-17Initial release covering multiple image-processing APIs and 1 task-query API
Added code examples, best practices, FAQ and glossary