PicMa Studio API Developer Docs

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.

Copy{
  "imageUrl": "https://example.com/photo.jpg",
  "clientTaskId": "my-task-001"
}

Photo Enhancement

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.

Enhance & Restore 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.

Super Resolution

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.

Motion 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

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.

B&W 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 Repair

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.

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.

Composite sample (bundled with the docs): left = original, right = mask (white = repaint, black = keep)

Copy{
  "imageUrl": "https://example.com/original-with-mask.jpg",
  "prompt": "dress the person in a red dress"
}

Clothes Change

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.

Copy{
  "imageUrl": "https://example.com/person.jpg",
  "changeImageUrl": "https://example.com/clothes.jpg"
}

Image 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.

Copy{
  "imageUrl": "https://example.com/photo.jpg",
  "expandImagesJsonDto": {
    "width": 1024,
    "height": 1024,
    "startX": 200,
    "startY": 200
  }
}

Sky Filter (Offline)

Capability code: photo-sky-filter

Face Dynamization (Offline)

Capability code: photo-face-dynamization

AI Image 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, clientTaskId. Returns 1003002 when style config is missing.

Output notes: Async task; get the result image from output.url when complete.

Copy{
  "imageUrl": "https://example.com/photo.jpg",
  "specsCode": "filter_001",
  "gender": 1
}

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, clientTaskId. Returns 1003002 when style config is missing.

Output notes: Async task; get the result image from output.url when complete.

Copy{
  "imageUrl": "https://example.com/photo.jpg",
  "specsCode": "portrait_001",
  "gender": 1
}

AI Hetu Image 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.

Copy{
  "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.

Copy{
  "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.

Copy{
  "prompt": "a watercolor forest cabin",
  "resolution": "2K",
  "ratio": "4:3"
}

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

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-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.

Copy{
  "prompt": "a corgi wearing sunglasses",
  "resolution": "2K",
  "ratio": "1:1"
}

Gemini 3.1 Flash Image（Nano Banana 2）

Capability code: photo-gemini-3-1-flash-image

Capability: Prompt-based text-to-image / image-to-image generation (Gemini 3.1 Flash / Nano Banana 2).

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（Nano Banana Pro）

Capability code: photo-gemini-3-pro-image

Capability: Prompt-based text-to-image / image-to-image generation (Gemini 3 Pro / Nano Banana Pro).

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.

AI 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 Removal

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.

Copy{
  "imageUrl": "https://example.com/product.jpg",
  "clientTaskId": "rmbg-001"
}

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.

Copy{
  "imageUrl": "https://example.com/street.jpg"
}

Image Watermark Removal

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.

Copy{
  "imageUrl": "https://example.com/photo-with-wm.jpg"
}

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.

Copy{
  "imageUrl": "https://example.com/face.jpg"
}

One-click 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 Target Removal.

Request notes: Body PhotoRestoreReqDto; required imageUrl; optional clientTaskId.

Output notes: Async task; get the result image from output.url when complete.

Copy{
  "imageUrl": "https://example.com/clutter.jpg"
}

ID Photo

Capability code: photo-id-photo

Capability: Converts a portrait to ID-photo style; spec is determined by specsCode.

Use cases: ID photo creation, standard ID background output.

Request notes: Body PhotoFilterReqDto; required imageUrl, specsCode; optional 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.

Copy{
  "imageUrl": "https://example.com/portrait.jpg",
  "specsCode": "id_photo_001"
}

Video Super Resolution

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.

Copy{
  "videoUrl": "https://example.com/input.mp4",
  "specsCode": "1080P",
  "outputFmt": "mp4"
}

Video Face Super Resolution

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 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.

Video Color Enhancement

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 B&W 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.

Video Low-light 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.

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.

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 Removal

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.

Copy{
  "videoUrl": "https://example.com/input.mp4",
  "waterMarkParam": { "X": 100, "Y": 40, "W": 180, "H": 60 },
  "outputFmt": "mp4"
}

Video Background Removal

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.

Output notes: The result is an MOV video with an alpha channel (background removed). Download from output.url when complete.

Copy{
  "videoUrl": "https://example.com/input.mp4"
}

Hetu Style Video

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.

Copy{
  "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.

Copy{
  "imageUrl": "https://example.com/ref.jpg",
  "prompt": "slow push-in, warm sunset atmosphere",
  "outputDuration": 4,
  "outputRes": "720P"
}

Hetu Style Video (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 1001005; 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.

Copy{
  "imageUrls": [
    "https://example.com/frame-start.jpg",
    "https://example.com/frame-end.jpg"
  ],
  "specsCode": "hetu_video_001"
}

Query Task Status (generic polling API)

Capability code: tasks/{task_id}

Example · processing (single image) processing

Copy{
  "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

Copy{
  "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 }
  }
}

Example · processing (text-to-image) processing

Copy{
  "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"
    }
  }
}

Example · completed completed

Copy{
  "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

Copy{
  "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 }
  }
}