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
POST /v1/images/pose| Parameters | Type | Required | Description |
|---|---|---|---|
template_id | string | Choose one of two | Template ID (see "Template List" below), or your own custom posture ID (starting with upose_, see "Custom Posture") |
prompt | string | Choose one of two | Directly specify the gesture prompt word (one-time, not saved). Choose one from template_id; for metropolitan transmission, template_id shall prevail |
work_type | int | No | Image engine, only effective when using prompt (when using template_id, the engine is determined by the template): 2=Qwen (default), 3=Flux, 4=Krea |
image | string | Yes | Face photo: image URL, or base64 (can be prefixed with data:image/jpeg;base64,). Max 10MB |
max_side | int | No | Keep 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 |
width | int | No | Custom output width, needs to be transmitted at the same time as height. Range 512–2048 |
height | int | No | Custom output height, needs to be transmitted at the same time as width. Range 512–2048 |
webhook_url | string | No | Push 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 withupose_, see "Custom poses"). The engine is determined by this template,work_typeis ignored. - Write the prompt directly: Pass
prompt, one-time use, do not save. Usework_typeto 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.
// 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
widthandheightat 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.
// 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_rejectedwill be returned.
Example
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"
}'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())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
{
"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
GET /v1/templates?capability=image.pose&page=1&page_size=20Pass page or page_size to paginate. See Template pagination for parameters and response fields.
{
"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
promptdirectly (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 astemplate_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).
| Method | Description |
|---|---|
POST /v1/poses | Created. Body: { name, prompt, work_type? } (work_type 2=Qwen default, 3=Flux, 4=Krea). Return containing id (upose_...) |
GET /v1/poses | My custom pose list · Template pagination |
PATCH /v1/poses/{id} | Modify name / prompt |
DELETE /v1/poses/{id} | Delete |
# 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" }'