宠物写真（猫狗换装）API 接入技术教程

1. 技术简介

宠物写真（猫狗换装）是一项基于人工智能图像生成的接口能力。接口接收一张宠物原图，通过视觉特征提取、提示词构建与图生图渲染，输出保留宠物本体特征、并套用指定服饰风格的拟人化高清写真图片。接口采用「创建任务 + 轮询查询」的异步调用模式：先提交生成任务拿到任务标识，再周期性查询任务状态，任务完成后从返回结构中获取写真图片地址。该能力适用于宠物内容创作、社交分享素材生成、宠物周边与 IP 视觉生产等需要批量、可控产出宠物写真的技术场景。

2. 能力概览

3. 适用场景

• 宠物 IP 与周边视觉：为宠物形象统一生成特定风格的视觉素材，用于头像、表情包、周边设计。
• 社交分享素材：将日常宠物照片转为特定主题写真，作为社媒内容素材。
• 内容生产流水线：在需要周期性产出宠物主题图片的业务中，以原图批量提交、轮询回收的方式接入。
• 技术验证与联调：在接入业务系统前，通过在线调试模块验证参数与返回结构。

上述场景仅描述技术用途与数据流向，不涉及业务收益或量化指标。

4. 接入流程

接入分为三步：

1. 准备原图：提供一张清晰、正脸/半身、无遮挡的宠物图片，可为公网可访问的 URL 或 Base64 编码字符串。
2. 创建任务：以 POST 调用创建接口，在请求体中传入风格、宽高比与原图，接口返回任务标识 task_id。
3. 轮询查询：以 GET 调用查询接口并携带 task_id，周期性查询直到任务完成，从返回结构中取回写真图片地址。

创建任务请求参数

查询任务请求参数

5. 调用示例与返回结构

以下示例中的接入地址来自云市场商品页给出的网关地址，鉴权统一使用 APPCODE。

创建任务（POST）

POST /skills_petportrait/create HTTP/1.1
Host: petphoto.market.alicloudapi.com
Authorization: APPCODE <appcode>
Content-Type: application/json

{
  "style_type": "古风汉服",
  "aspect_ratio": "1:1",
  "pet_image": "https://example.com/pet.jpg"
}

查询任务（GET）

GET /skills_petportrait/query?task_id=pp_20260903_a1b2c3d4 HTTP/1.1
Host: petphoto.market.alicloudapi.com
Authorization: APPCODE <appcode>

返回结构示例（JSON）

创建任务返回：

{
   
  "ret_code": 0,
  "task_id": "pp_20260903_a1b2c3d4",
  "msg": "任务创建成功"
}

查询任务返回（任务完成时）：

{
   
  "ret_code": 0,
  "task_status": "done",
  "flow_result": {
   
    "output": {
   
      "image_url": "https://example.com/result/portrait_pp_20260903_a1b2c3d4.png"
    }
  }
}

字段取值以云市场商品页接口文档与控制台实时配置为准；不同资源包下返回字段可能存在差异。

Python 示例

import requests

APPCODE = "<appcode>"
HOST = "https://petphoto.market.alicloudapi.com"

# 1. 创建任务
create = requests.post(
    f"{HOST}/skills_petportrait/create",
    headers={
   "Authorization": f"APPCODE {APPCODE}", "Content-Type": "application/json"},
    json={
   
        "style_type": "古风汉服",
        "aspect_ratio": "1:1",
        "pet_image": "https://example.com/pet.jpg",
    },
    timeout=30,
)
task_id = create.json().get("task_id")

# 2. 轮询查询
import time
for _ in range(30):
    q = requests.get(
        f"{HOST}/skills_petportrait/query",
        headers={
   "Authorization": f"APPCODE {APPCODE}"},
        params={
   "task_id": task_id},
        timeout=30,
    ).json()
    if q.get("task_status") == "done":
        print(q["flow_result"]["output"]["image_url"])
        break
    time.sleep(3)

Java 示例

import java.net.http.*;
import java.net.URI;
import java.time.Duration;

public class PetPortrait {
   
    static final String APPCODE = "<appcode>";
    static final String HOST = "https://petphoto.market.alicloudapi.com";

    public static void main(String[] args) throws Exception {
   
        HttpClient client = HttpClient.newHttpClient();
        // 创建任务
        String body = "{\"style_type\":\"古风汉服\",\"aspect_ratio\":\"1:1\",\"pet_image\":\"https://example.com/pet.jpg\"}";
        HttpRequest create = HttpRequest.newBuilder()
                .uri(URI.create(HOST + "/skills_petportrait/create"))
                .header("Authorization", "APPCODE " + APPCODE)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
        HttpResponse<String> r1 = client.send(create, HttpResponse.BodyHandlers.ofString());
        String taskId = extractTaskId(r1.body());
        // 轮询查询（省略循环细节）
    }

    static String extractTaskId(String json) {
    return ""; }
}

PHP 示例

<?php
$appcode = "<appcode>";
$host = "https://petphoto.market.alicloudapi.com";

// 创建任务
$ch = curl_init("$host/skills_petportrait/create");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: APPCODE $appcode", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "style_type" => "古风汉服",
        "aspect_ratio" => "1:1",
        "pet_image" => "https://example.com/pet.jpg",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$create = json_decode(curl_exec($ch), true);
$taskId = $create["task_id"];

// 轮询查询
do {
   
    sleep(3);
    $q = curl_init("$host/skills_petportrait/query?task_id=" . urlencode($taskId));
    curl_setopt_array($q, [CURLOPT_HTTPHEADER => ["Authorization: APPCODE $appcode"], CURLOPT_RETURNTRANSFER => true]);
    $resp = json_decode(curl_exec($q), true);
} while (($resp["task_status"] ?? "") !== "done");
echo $resp["flow_result"]["output"]["image_url"];

Node.js 示例

const APPCODE = "<appcode>";
const HOST = "https://petphoto.market.alicloudapi.com";

// 创建任务
const createRes = await fetch(`${
     HOST}/skills_petportrait/create`, {
   
  method: "POST",
  headers: {
    Authorization: `APPCODE ${
     APPCODE}`, "Content-Type": "application/json" },
  body: JSON.stringify({
   
    style_type: "古风汉服",
    aspect_ratio: "1:1",
    pet_image: "https://example.com/pet.jpg",
  }),
});
const {
    task_id } = await createRes.json();

// 轮询查询
let url;
for (let i = 0; i < 30; i++) {
   
  const q = await fetch(`${
     HOST}/skills_petportrait/query?task_id=${
     task_id}`, {
   
    headers: {
    Authorization: `APPCODE ${
     APPCODE}` },
  }).then((r) => r.json());
  if (q.task_status === "done") {
    url = q.flow_result.output.image_url; break; }
  await new Promise((r) => setTimeout(r, 3000));
}
console.log(url);

6. 在线调试实录

在云市场商品页的 API 调试模块中，可按以下步骤完成一次联调：

1. 选择操作「创建任务」，请求方式显示为 POST，调用地址为 /skills_petportrait/create。
2. 在请求体（Body）中填写 style_type、aspect_ratio 与 pet_image 三个字段，其中 pet_image 填入一张公网可访问的宠物图片地址。
3. 发起请求，接口返回 task_id。
4. 切换操作「查询结果」，请求方式显示为 GET，在查询参数中填入上一步的 task_id。
5. 发起查询，待 task_status 变为 done 后，从 flow_result.output.image_url 取回写真图片地址。

该走查用于确认参数格式与返回结构，与业务系统接入逻辑一致。调试中建议使用清晰、正脸、无遮挡的原图，以减少因原图不可解析导致的失败。

7. 接口调用限制与规范

• 请求频率：建议单账户请求频率参考控制台实时配置；高频提交可能触发限流，返回 403。
• 配额：每日可调用次数随账户资源包而定，以控制台实时配置为准；配额用尽后调用会被拒绝。
• 批量规则：单次请求生成一张写真。需要批量产出时，建议串行或受限并发提交，并在每次创建后等待轮询完成，避免短时间内大量并发导致限流。
• 原图要求：清晰、正脸/半身、无遮挡；支持 URL 与 Base64 两种传入方式。
• 合规要求：传入的宠物图像须用于已获授权的用途，不得处理未授权的人像或隐私内容；上传图像按服务商声明处理，不应依赖其长期留存。

上述频率与配额为参考性描述，精确数值以控制台实时配置为准。

8. 能力边界与免责声明

支持

• 面向猫狗宠物的原图换装写真生成。
• 十余种内置风格的套用与多宽高比输出。
• 异步任务模式，便于批量与流水线接入。

不支持

• 直接以人像或非猫狗宠物作为换装主体。
• 保证生成结果与某张指定参考图在构图、姿态上完全一致。
• 实时流式返回；本接口采用异步轮询，需等待任务完成。

免责声明
生成结果由算法产出，仅供参考，不对生成内容的版权归属、与本体相似度及任何业务决策承担责任。接入方应确保传入图像与生成用途符合相关规范。

9. 错误码与排查指南

10. 常见问题 FAQ

Q1：接口支持哪些宠物？
当前面向猫狗宠物。其他物种的换装效果不在支持范围内。

Q2：原图有什么要求？
建议提供清晰、正脸或半身、无遮挡的照片，支持公网 URL 与 Base64 编码两种传入方式。

Q3：怎么拿到生成的写真？
先调用创建接口拿到 task_id，再调用查询接口轮询，待 task_status 为 done 时从 flow_result.output.image_url 取回图片地址。

Q4：宽高比怎么选？
按使用版式选择：头像用 1:1，朋友圈用 3:4，海报用 16:9，横版内容用 4:3 或 9:16。

Q5：一次能出几张？
单次请求生成一张写真。批量场景请循环提交并控制频率，避免限流。

Q6：返回的图片地址有效期？
以返回 URL 的有效期为准，建议及时下载保存到自有存储。

11. 内容小结

宠物写真（猫狗换装）接口以「创建任务 + 轮询查询」的异步模式工作：创建接口提交风格、宽高比与原图并返回 task_id，查询接口携带 task_id 轮询至完成并取回写真图片地址。接入时注意原图质量、请求频率与配额，并以控制台实时配置核对频率、配额与返回字段。生成结果由算法产出，仅供参考，接入方应自行确保图像授权与用途合规。