Image utilities, 3D and speech

Submit these media tools as durable workflow steps to POST /v1/creative-agent/workflows, or use them through hosted chat. The synchronous /v1/creative-agent/tools/execute endpoint is reserved for text composition. Original source media can be supplied through the media context and indices, or the named URL fields. Upload indices are negative (-1 is the first); generated-result indices start at zero.

The examples request a quote with confirm_cost: false; the API returns a structured cost response without starting generation. Resubmit with confirm_cost: true after accepting the quote, then read the workflow or subscribe to its event stream for results.

#Remove a background

{
  "input": {
    "steps": [
      {
        "id": "remove_background",
        "toolName": "remove_background",
        "arguments": {
          "source_image_url": "https://your-host.example/original.png",
          "applyMask": true
        }
      }
    ]
  },
  "token_type": "spark",
  "confirm_cost": false
}

BiRefNet preserves the original foreground and returns a transparent PNG. Set applyMask: false to return the alpha mask. No prompt is required. The SDK project equivalent uses modelId: 'birefnet_image_background_removal_fp16', startingImage, and applyMask.

#Reconstruct a textured 3D model

{
  "input": {
    "steps": [
      {
        "id": "image_to_3d",
        "toolName": "image_to_3d",
        "arguments": {
          "source_image_url": "https://your-host.example/front.png",
          "left_view_image_url": "https://your-host.example/left.png",
          "back_view_image_url": "https://your-host.example/back.png",
          "right_view_image_url": "https://your-host.example/right.png",
          "meshTargetFaces": 50000,
          "textureSize": 2048,
          "shapeResolution": 1024
        }
      }
    ]
  },
  "token_type": "spark",
  "confirm_cost": false
}

The front image is required. Any subset of the optional orbit views selects Pixal3D multi-view reconstruction; front-only uses single-view reconstruction. Views describe the subject's own sides: left means its left side faces camera (subject faces screen-left), right means screen-right. Use original stills of the same subject at consistent height and framing. Indexed equivalents are sourceImageIndex, leftViewImageIndex, backViewImageIndex, and rightViewImageIndex.

Control	Allowed values	Default
meshTargetFaces	Integer 5,000–700,000	700,000
textureSize	Integer 1,024–4,096	4,096
normalMapSize	Integer 512–2,048	2,048
ambientOcclusionSize	Integer 256–1,024	1,024
shapeResolution	1,024 or 1,536	1,024

The result is a binary GLB with mediaType: 'model'. Download or display it as a 3D model, rather than passing it to an image tool. The SDK uses pixal3d_int8_i23d or pixal3d_multiview_int8_i23d, startingImage, and named leftViewImage, backViewImage, and rightViewImage binary inputs. Generic contextImages do not identify orbit views.

#Select an object

segment_image accepts sourceImageIndex or source_image_url, plus text, points, or boxes. Point coordinates (x, y) and box coordinates (x0, y0, x1, y1) are normalized to the original image's 0–1 range. Points carry a positive or negative label; boxes default to positive and can carry an exclusion label with a text prompt.

Text can combine with boxes. Points can combine with at most one positive box and cannot combine with text. Use threshold (0–1, default 0.5), multimask (point prompts only), and maxInstances (1–16) to control selection. applyMask: true returns a transparent cutout; the default returns a PNG mask. The SDK equivalent is sam3_image_segment_bf16 with startingImage and sam3Prompt.

#Speech and reference-audio cloning

generate_speech reads prompt as the literal script. Select model: 'voice' for a studio speaker, 'clone' for a supplied recording, or 'design' for a voice described in voiceDescription. Cloning uses voiceSourceIndex (or voice_source_url) and optional voiceTranscript; supply the original recording. It conditions synthesis on that recording and does not create a persistent trained voice model.

Controls include language, voice for studio mode, voiceDescription for studio direction/design, creativity (0.1–2, default 0.9), outputFormat (wav, mp3, flac), seed, and numberOfVariations.

#FastH3 Two-Stage Turbo

Use videoModel: 'minimax-h3-fasth3-t2v-turbo-2stage' with generate_video, or the corresponding i2v/flf2v selector with animate_photo. Set targetResolution to 720, 1080, or 1440 (the 2K class; default). The worker generates the base canvas, then enlarges and refines it; price the selected mode and resolution together.

For uploaded audio, sound_to_video exposes minimax-h3-fasth3-ia2v-turbo-2stage, minimax-h3-fasth3-flfa2v-turbo-2stage, and minimax-h3-fasth3-a2v-turbo-2stage. Supply the audio and the required first/last images. These modes preserve the supplied audio and reject LoRAs. Non-audio H3 modes can use compatible personal LoRAs.