Skip to content

Photo Pose ​

Upload a face photo and match it with a pose (official template, your custom pose, or write prompt words directly) to generate a pose photo of the character. The task is executed asynchronously and usually takes 15 to 60 seconds to complete.

Create task ​

http
POST /v1/images/pose
ParametersTypeRequiredDescription
template_idstringChoose one of twoTemplate ID (see "Template List" below), or your own custom posture ID (starting with upose_, see "Custom Posture")
promptstringChoose one of twoDirectly specify the gesture prompt word (one-time, not saved). Choose one from template_id; for metropolitan transmission, template_id shall prevail
work_typeintNoImage engine, only effective when using prompt (when using template_id, the engine is determined by the template): 2=Qwen (default), 3=Flux, 4=Krea
imagestringYesFace photo: image URL, or base64 (can be prefixed with data:image/jpeg;base64,). Max 10MB
max_sideintNoKeep the proportion of the original image and specify the pixels of the longest side. Range 512–2048, if exceeded, it will be clamped to the range
widthintNoCustom output width, needs to be transmitted at the same time as height. Range 512–2048
heightintNoCustom output height, needs to be transmitted at the same time as width. Range 512–2048
webhook_urlstringNoPush address after the task ends

Request header Idempotency-Key (optional): Your business ID, which is not repeated within the same function, will be returned unchanged in the result.

Posture source ​

template_id and prompt Choose one (for metropolitan transmission, template_id shall prevail):

  • Use template/custom pose: Pass template_id. It can be an official template ID, or a custom pose ID you saved (starting with upose_, see "Custom poses"). The engine is determined by this template, work_type is ignored.
  • Write the prompt directly: Pass prompt, one-time use, do not save. Use work_type to select the engine (2=Qwen default, 3=Flux, 4=Krea). If you want to use the same prompt repeatedly, save it as a custom pose.
jsonc
// Use an official template
{ "template_id": "pose_office", "image": "https://example.com/face.jpg" }

// Use your custom pose
{ "template_id": "upose_xxx", "image": "https://example.com/face.jpg" }

// Write a prompt directly and select the Flux engine
{ "prompt": "Standing on a city rooftop in a trench coat, looking back with a smile, full body, sunset lighting, photorealistic", "work_type": 3, "image": "https://example.com/face.jpg" }

Resolution ​

When no resolution parameter is passed, the default resolution of the template workflow is used. To specify the output size, choose one of two options:

  • Keep Proportion: Only pass max_side, scale it according to the original image aspect ratio, so that the longest side is equal to this value.
  • Custom size: Transmit width and height at the same time, and the output is fixed to the width and height.

Constraints: 512–2048 on each side, automatically rounded down to a multiple of 8; the total pixel limit is approximately 3.1MP (approximately 1536×2048), and oversized values are scaled down. Resolution parameters apply to Qwen, Flux, and Krea templates (SD templates ignore them). Qwen prioritizes max_side when both modes are supplied; Flux and Krea prioritize width/height.

jsonc
// Preserve aspect ratio, longest side 1280
{ "template_id": "pose_office", "image": "https://example.com/face.jpg", "max_side": 1280 }

// Custom size 832×1216 (portrait)
{ "template_id": "pose_office", "image": "https://example.com/face.jpg", "width": 832, "height": 1216 }

Photo requirements:

  • Frontal face with clear facial features. It is best to have only one person in the picture.
  • If no clear face is detected, or a minor is suspected, 422 input_rejected will be returned.

Example ​

bash
curl -X POST https://api.modelgo.moneygo.ai/v1/images/pose \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_10086" \
  -d '{
    "template_id": "pose_office",
    "image": "https://example.com/face.jpg"
  }'
python
import base64
import requests

with open("face.jpg", "rb") as f:
    image = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

res = requests.post(
    "https://api.modelgo.moneygo.ai/v1/images/pose",
    headers={"Authorization": "Bearer sk-your-key", "Idempotency-Key": "order_10086"},
    json={"template_id": "pose_office", "image": image},
    timeout=60,
)
print(res.json())
js
import { readFile } from 'node:fs/promises'

const image = 'data:image/jpeg;base64,' + (await readFile('face.jpg')).toString('base64')
const res = await fetch('https://api.modelgo.moneygo.ai/v1/images/pose', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk-your-key', 'Content-Type': 'application/json', 'Idempotency-Key': 'order_10086' },
  body: JSON.stringify({ template_id: 'pose_office', image }),
})
console.log(await res.json())

Return ​

json
{
  "id": "task_3kP9xQ2mZ7aB1cD4eF6gH8jK",
  "object": "task",
  "capability": "image.pose",
  "status": "queued",
  "template_id": "pose_office",
  "cost": 30,
  "output": null,
  "error": null,
  "created_at": "2026-09-17T08:00:00.000Z",
  "started_at": null,
  "finished_at": null
}

Then get the results via a webhook callback or task query. When successful, output.images is the result image address.

Template list ​

http
GET /v1/templates?capability=image.pose&page=1&page_size=20

Pass page or page_size to paginate. See Template pagination for parameters and response fields.

json
{
  "data": [
    {
      "id": "pose_office",
      "capability": "image.pose",
      "name": "Office",
      "description": "Professional attire in an office setting",
      "price": 30,
      "cover_url": "https://cdn.example.com/covers/office.jpg"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

Templates will increase or decrease from time to time. It is recommended to synchronize regularly and do not hard-code the template ID.

Custom pose ​

In addition to the official templates, you can generate poses with your own prompt words, two ways:

  • One-time: Pass prompt directly (without saving) when creating a task, see the parameter table above.
  • Save for reuse: Save the prompt word as a private gesture, get the ID starting with upose_, and then use it as template_id.

Custom poses are private and can only be seen and used by you. The billing is consistent with the official template (deducted according to the engine's default price).

MethodDescription
POST /v1/posesCreated. Body: { name, prompt, work_type? } (work_type 2=Qwen default, 3=Flux, 4=Krea). Return containing id (upose_...)
GET /v1/posesMy custom pose list · Template pagination
PATCH /v1/poses/{id}Modify name / prompt
DELETE /v1/poses/{id}Delete
bash
# 1. Save a pose
curl -X POST https://api.modelgo.moneygo.ai/v1/poses \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{ "name": "City rooftop portrait", "prompt": "Standing on a city rooftop in a trench coat, looking back with a smile, full body, sunset lighting, photorealistic" }'
# → { "id": "upose_xxx", ... }

# 2. Generate with it (same as an official template)
curl -X POST https://api.modelgo.moneygo.ai/v1/images/pose \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{ "template_id": "upose_xxx", "image": "https://example.com/face.jpg" }'
Copyright © 2026 ModelGo all rights reserved | Technology powered by MoneyGo.ai