Image Studio API

API version: v1.2.4

Public API for product images, model images, history, feedback, and review flows.

Public base URL:

https://phosor.ai

Common contract: common-api.md

Contract Rules

The async identifier is request_id.
Available models are GPT-Image-2 and Phosor Model API.

Endpoint Summary

Public

Method	Path	Purpose
GET	`/api/v1/image-studio/pricing`	Pricing and quota info
GET	`/api/v1/image-studio/jobs/{request_id}`	Poll task status
POST	`/api/v1/image-studio/jobs/{request_id}/cancel`	Cancel a running task
GET	`/api/v1/image-studio/my-works`	List current user works
GET	`/api/v1/image-studio/my-works/{request_id}`	Work detail
GET	`/api/v1/image-studio/my-works/{request_id}/download`	Download generated images
DELETE	`/api/v1/image-studio/my-works/{request_id}`	Soft delete work
POST	`/api/v1/image-studio/tasks/{task_id}/review`	Submit review
GET	`/api/v1/image-studio/tasks/{task_id}/review`	Read review
POST	`/api/v1/image-studio/feedback`	Submit feedback
POST	`/api/v1/image-studio/product/suite`	Product suite generation
POST	`/api/v1/image-studio/product/reference/analyze`	Product reference analyze
POST	`/api/v1/image-studio/product/scene-compose`	Scene compose
POST	`/api/v1/image-studio/product/scene-variation`	Scene variation
POST	`/api/v1/image-studio/product/remove-bg`	Remove background
POST	`/api/v1/image-studio/product/replace`	Replace product
POST	`/api/v1/image-studio/product/inpaint`	Inpaint
POST	`/api/v1/image-studio/product/erase`	Erase
POST	`/api/v1/image-studio/product/handheld`	Handheld product
POST	`/api/v1/image-studio/product/translate`	Translate text in image
POST	`/api/v1/image-studio/product/outpaint`	Outpaint
POST	`/api/v1/image-studio/product/recolor`	Recolor
POST	`/api/v1/image-studio/product/enhance`	Product enhancement
POST	`/api/v1/image-studio/product/upscale`	Upscale
POST	`/api/v1/image-studio/product/analyze`	Product analyze
POST	`/api/v1/image-studio/model/analyze`	Model analyze
POST	`/api/v1/image-studio/model/clothing-suite`	Clothing suite
POST	`/api/v1/image-studio/model/real-model-swap`	Real model swap
POST	`/api/v1/image-studio/model/mannequin-swap`	Mannequin swap
POST	`/api/v1/image-studio/model/model-scene-swap`	Model scene swap
POST	`/api/v1/image-studio/model/ai-outfit`	AI outfit
POST	`/api/v1/image-studio/model/pose-variation`	Pose variation
POST	`/api/v1/image-studio/model/ai-wearable`	AI wearable
POST	`/api/v1/image-studio/agent/analyze`	Workspace analyze

Cancel a Running Task

POST /api/v1/image-studio/jobs/{request_id}/cancel

One endpoint cancels any Image Studio generation — product suite, model images and single-image tools all share it. There is no per-feature cancel path.

Billing

Cancellation is billed by how far each image had already travelled, not by how many images you receive:

Image state when you cancel	Billed?	Why
Still queued	No — refunded	Generation never started, so nothing was consumed
Already generating	Yes — charged in full	Generation has already started and cannot be stopped
Already finished	Yes — charged in full	You receive the image

Cancelling does not stop images that have already started generating — those cannot be interrupted. It stops the task from waiting for them: the response returns immediately and those images are discarded.

Response

JSON

{
  "ok": true,
  "status": "cancelling",
  "charged_running": 2,
  "refunded_queued": 1,
  "already_done": 1
}

Field	Meaning
`charged_running`	Images that had already started generating — charged in full
`refunded_queued`	Images still queued — removed and refunded
`already_done`	Images already generated — billed through the normal success path, never counted twice

The task then reaches status: "cancelled" (not failed) when polled. A cancelled task is never recorded as a failure.

Errors

Status	Meaning
404	Unknown `request_id`, expired, or owned by another account (404 rather than 403 so the endpoint never reveals whether an id exists)
200 with `"ok": false`	The task had already finished; nothing was cancelled

Repeated cancels are idempotent and return the same breakdown.

Common Async Shape

Submit response:

JSON

{ "request_id": "uuid", "status": "pending" }

Typical job detail:

JSON

{
  "request_id": "uuid",
  "status": "done",
  "result": {
    "images": [
      { "url": "https://..." }
    ]
  }
}

Upload First

Most Image Studio flows start by uploading one or more images:

cURL

curl -X POST "https://phosor.ai/api/v1/storage/image/upload" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@input.jpg"

The response returns an s3_url that can be reused in later analyze/generation requests.

Product Suite Flow

Plain text

POST /api/v1/storage/image/upload
  -> {s3_url}
POST /api/v1/image-studio/product/analyze        # optional
  -> {request_id, status:"pending"}
GET  /api/v1/image-studio/jobs/{request_id}
POST /api/v1/image-studio/product/suite
  -> {request_id, status:"pending"}
GET  /api/v1/image-studio/jobs/{request_id}

`POST /product/analyze`

Request body:

Field	Required	Notes
`image_url` / `product_image_url`	yes	Main product image
`image_urls`	no	Multi-view input
`prompt`	no	Extra user instruction
`language`	no	Default `zh`
`product_description`	no	Text description

Product Analyze Sample

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/product/analyze" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/images/product.jpg",
    "image_urls": [
      "https://example.com/images/product-side.jpg"
    ],
    "prompt": "Extract the product facts and important visual cues.",
    "language": "en",
    "product_description": "A foldable electric scooter for urban commuting."
  }'

`POST /product/suite`

Common fields:

product_image_url
image_urls
layout_types
count_per_type
custom_suggestions
layout_template_ids
layout_random_count
same_style_reference
product_info
product_description
brand_config
gen_language
appearance_ratio
style_preset
visual_scheme_id
model
request_id

Product Suite Sample

Upload a product image first:

cURL

curl -X POST "https://phosor.ai/api/v1/storage/image/upload" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@product.jpg"

Then analyze the product:

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/product/analyze" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://example.com/images/product.jpg",
    "image_urls": [
      "https://example.com/images/product-side.jpg"
    ],
    "language": "en",
    "product_description": "A foldable electric scooter for urban commuting."
  }'

Submit the product suite job:

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/product/suite" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://example.com/images/product.jpg",
    "image_urls": [
      "https://example.com/images/product-side.jpg"
    ],
    "layout_types": ["square", "portrait"],
    "count_per_type": 1,
    "custom_suggestions": "Focus on portability, compact fold, and daily commute use.",
    "product_info": "Compact foldable scooter, matte black, city commuting.",
    "gen_language": "en",
    "appearance_ratio": 0.5,
    "model": "openai:gpt-image-2"
  }'

Poll the result:

cURL

curl "https://phosor.ai/api/v1/image-studio/jobs/{request_id}" \
  -H "X-API-Key: your_api_key_here"

Fetch history and download if needed:

cURL

curl "https://phosor.ai/api/v1/image-studio/my-works/{request_id}" \
  -H "X-API-Key: your_api_key_here"

cURL

curl "https://phosor.ai/api/v1/image-studio/my-works/{request_id}/download" \
  -H "X-API-Key: your_api_key_here"

Model Suite Flow

Plain text

POST /api/v1/storage/image/upload
POST /api/v1/image-studio/model/analyze        # optional
POST /api/v1/image-studio/model/clothing-suite
GET  /api/v1/image-studio/jobs/{request_id}

Common fields:

clothing_image_urls
main_image_types
aplus_types
layout_template_ids
layout_random_count
product_info
product_description
brand_config
same_style_reference
model_attrs
appearance_ratio
gen_language
request_id

Model Analyze Sample

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/model/analyze" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/images/shirt-front.jpg",
    "image_urls": [
      "https://example.com/images/shirt-back.jpg"
    ],
    "prompt": "Extract garment structure, fit, and key details.",
    "language": "en",
    "product_description": "Relaxed-fit cotton shirt for daily wear."
  }'

Model Suite Sample

Upload clothing images first:

cURL

curl -X POST "https://phosor.ai/api/v1/storage/image/upload" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@shirt-front.jpg"

cURL

curl -X POST "https://phosor.ai/api/v1/storage/image/upload" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@shirt-back.jpg"

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/model/clothing-suite" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clothing_image_urls": [
      "https://example.com/images/shirt-front.jpg",
      "https://example.com/images/shirt-back.jpg"
    ],
    "main_image_types": {
      "model_shot": 1,
      "selling_point": 1
    },
    "product_info": "Relaxed-fit cotton shirt for daily wear.",
    "model_attrs": {
      "gender": "female",
      "age_group": "young"
    },
    "gen_language": "en",
    "appearance_ratio": 0.7,
    "request_id": "optional-idempotency-key"
  }'

Poll the result:

cURL

curl "https://phosor.ai/api/v1/image-studio/jobs/{request_id}" \
  -H "X-API-Key: your_api_key_here"

One-off Tools

These usually submit directly after upload:

remove-bg
replace
inpaint
erase
handheld
translate
outpaint
recolor
enhance
upscale
scene-compose
scene-variation

Common fields:

image_url / product_image_url / composite_image_url
mask_url
reference_image_url
count
model
request_id

One-off Tool Sample

Upload the input image first:

cURL

curl -X POST "https://phosor.ai/api/v1/storage/image/upload" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@tool-input.jpg"

Example: remove background.

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/product/remove-bg" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/images/product.jpg",
    "count": 1,
    "model": "openai:gpt-image-2"
  }'

Example: product enhancement.

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/product/enhance" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/images/product.jpg",
    "enhance_type": "detail",
    "count": 1
  }'

Poll a one-off job:

cURL

curl "https://phosor.ai/api/v1/image-studio/jobs/{request_id}" \
  -H "X-API-Key: your_api_key_here"

History / Review / Feedback

`GET /my-works`

Current user history list.

`GET /my-works/{request_id}`

Returns:

request_id
task_type
status
error
created_at
finished_at
images
download_urls
input_images
output_labels
reference_images
params
credits_used
review

History Sample

cURL

curl "https://phosor.ai/api/v1/image-studio/my-works?limit=20&offset=0" \
  -H "X-API-Key: your_api_key_here"

cURL

curl "https://phosor.ai/api/v1/image-studio/my-works/{request_id}" \
  -H "X-API-Key: your_api_key_here"

cURL

curl "https://phosor.ai/api/v1/image-studio/my-works/{request_id}/download" \
  -H "X-API-Key: your_api_key_here"

Review Sample

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/tasks/{task_id}/review" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "image_index": 0, "passed": true, "image_type": "a_plus_1", "note": "ok" },
      { "image_index": 1, "passed": false, "image_type": "a_plus_2", "note": "text cut off" }
    ]
  }'

Feedback Sample

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/feedback" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "uuid",
    "message": "The second image looks too dark."
  }'

`POST /tasks/{task_id}/review`

Submits human review items for a task.

`GET /tasks/{task_id}/review`

Reads current review state.

`POST /feedback`

Submits a user feedback item.

Agent Analyze Sample

Upload the workspace image first:

cURL

curl -X POST "https://phosor.ai/api/v1/storage/image/upload" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@workspace.jpg"

cURL

curl -X POST "https://phosor.ai/api/v1/image-studio/agent/analyze" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://example.com/images/product.jpg",
    "gen_language": "en",
    "custom_suggestions": "Make the listing premium and conversion-oriented."
  }'