AI 助理
备案控制台
文档
输入文档关键字查找
首页 大模型服务平台百炼 开发参考 模型调用 图像生成-更多 图配文API参考

图配文模型API参考

更新时间：
提交缺陷
产品详情
我的收藏

用户只要输入背景图和文字，就能将文字排版到图片上，形成一张完整的图文海报。本文介绍图配文模型的输入输出参数。

相关指南：图配文

模型概览

模型名

模型简介

计费单价

限流（含主账号与RAM子账号）

任务下发接口QPS限制

同时处理中任务数量

wanx-ast

用户只要输入背景图和文字，就能将文字排版到图片上，形成一张完整的图文海报。生成的图片文字布局合理，画面色彩和谐，支持任意宽高比的背景图片，提供多样化字体搭配。

限时免费

2

1

前提条件

您需要已获取API Key并配置API Key到环境变量。

HTTP调用

创建任务

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

请求头（Headers）

图配文

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-ast",
    "input": {
        "title": ["Lorem Ipsum"],
        "subtitle": ["Duis aute irure dolor in reprehenderit"],
        "text": ["VIEW NOW"],
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20240929/vbxgxc/2.png",
        "underlay": 1,
        "logo": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20240927/abtbdg/logo.png"
    },
    "parameters": {
        "n": 1,
        "temperature": 0.7
    }
}'

Content-Type string 必选

请求内容类型。固定为application/json。

Authorization string 必选

推荐您使用百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。

X-DashScope-Async string 必选

是否开启异步处理。必须开启异步处理，设置为enable。

请求体（Request Body）

model string 必选

调用的模型。

input object 必选

输入图像的基本信息，比如图像URL地址。

属性

title array 必选

待添加的标题文本。

文本限制：

  • 文本数量：1个或者多个，如["标题1"]，或者["标题1"，"标题2"]。

  • 文本字数：长度没有限制。

  • 为了生图效果最佳，建议标题的数量不超过3个，每个标题的字符数不超过30。

subtitle array 可选

待添加的副标题文本。

文本限制：

  • 文本数量：1个或者多个，如["副标题1"]，或者["副标题1", "副标题2"]。

  • 文本字数：长度没有限制。

  • 为了生图效果最佳，建议副标题的数量不超过3个，每个副标题的字符数不超过30。

text array 可选

待添加的其他文本。

文本限制：

  • 文本数量：1个或者多个，如["文本1"]，或者["文本1"，"文本2"]。

  • 文本字数：长度没有限制。

  • 为了生图效果最佳，建议其他文本的不超过3个，每个文本的字符数不超过30。

image_url string 必选

输入的背景图的URL地址。

图像限制：

  • 图像格式：目前支持PNG、JPG

  • 图像分辨率：不超过3840 x 2160像素

  • 宽高比：无限制

  • 图片大小：不超过50MB

underlay integer 可选

蒙版（衬底）的数量，蒙版是用来展示在文字背景的矢量元素，可以提高文字的可读性和丰富整体样式。

取值范围[0, 2]，默认为0，为保证图像生成效果，建议设置为0或者1。

logo string 可选

Logo素材的URL地址。

图像限制：

  • 图像格式：目前支持PNG

  • 图像分辨率：不超过1280 x 1280像素

  • 图片大小：不超过5MB

  • 宽高比：无限制

parameters object 必选

用于控制图片生成的参数。

属性

temperature float 可选

采样温度，用于控制模型生成图像的随机性和多样性。

temperature越高，生成的图像越多样性，反之，生成的图像越确定。

取值范围为[0, 1.0]，默认值 0.7。

由于temperature与top_p均可以控制生成图像的多样性，因此建议您只设置其中一个值。

top_p float 可选

生成时，核采样方法的概率阈值，用于控制模型生成图像的多样性。例如，取值为0.8时，仅保留累计概率之和大于等于0.8的概率分布中的token，作为随机采样的候选集。

top_p取值越大，生成的随机性越高；取值越低，生成的随机性越低。

取值范围为[0, 1.0]，默认值 0.7。

n Integer 必选

期望生成的图片数量，默认为1，目前限制最多生成4张。

响应

成功响应

{
    "output": {
        "task_id": "xxxxxxxx",
        "task_status": "PENDING"
    },
    "request_id": "xxxxxxxx"
}

异常响应

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"xxxxxxxx"
}

output object

任务输出信息。

属性

task_id string

任务id。

task_status string

任务状态。

  • PENDING：排队中

  • RUNNING：处理中

  • SUSPENDED：挂起

  • SUCCEEDED：执行成功

  • FAILED：执行失败

  • UNKNOWN：任务不存在或状态未知

code string

请求失败，表示错误码，成功时返回参数中不会包含该参数。

message string

请求失败，表示失败详细信息，成功时返回参数中不会包含该参数。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

根据任务ID查询结果

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

请求头（Headers）

获取任务结果

curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/{your-task-id}

Authorization string 必选

API-KEY，例如：Bearer d1**2a。

URL路径参数（Path parameters）

task_id string 必选

任务ID，任务唯一标识。

响应

任务执行成功

对于本模型，任务状态和结果将保留24小时，生成图像的URL地址有效期也为24小时，需要您在有效期内及时转存生成图像，24小时之后，任务连同结果一起从系统中清除。

{
    "request_id": "85eaba38-0185-99d7-8d16-4d9135238846",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png"
            },
            {
                "url": "https: //dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png"
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 2,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 2
    }
}

作业执行完毕，部分失败

在一次提交中，本模型可以根据客户的需求生成多张图片，只要其中一张图片生成成功，作业将被设置为成功状态，并且对应的作业结果会在查询的时候返回，对于失败的batch，结果中也会返回对应的失败原因；同时在usage计量中，只会对成功的结果计数。

{
  "request_id":"<your request id>",
  "output":{
    "task_id":"<your task id>",
    "task_status":"SUCCEEDED",
    "results":[
      {
        "url":"https://xxx.com/xxx/xxx.png"
      },
      {
        "code": "InternalError.Timeout",
        "message": "An internal timeout error has occured during execution, please try again later or contact service support."
      }
    ],
    "task_metrics":{
      "TOTAL":2,
      "SUCCEEDED":1,
      "FAILED":1
    }
  },
  "usage":{
    "image_count":1
  }
}

任务执行中

{
    "request_id":"<your request id>",
    "output":{
        "task_id":"<your task id>",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

output dict

调用结果信息，返回叠加了文字效果的图像。

属性

task_id string

任务ID，任务唯一标识。

task_status string

任务状态。

  • PENDING：排队中

  • RUNNING：处理中

  • SUSPENDED：挂起

  • SUCCEEDED：执行成功

  • FAILED：执行失败

  • UNKNOWN：任务不存在或状态未知

task_metrics object

每个任务结果统计。

属性

TOTAL integer

总的任务数。

SUCCEEDED integer

任务状态为成功的任务数。

FAILED integer

任务状态为失败的任务数。

code string

请求失败，表示错误码，成功时返回参数中不会返回该参数。

message string

请求失败，表示失败详细信息，成功时返回参数中不会包含该参数。

results list

模型生成的结果对象。

属性

url string

生成的叠加了文字的图片结果，图像分辨率大小与输入图像的相同。

request_id string

本次请求的系统唯一码。

usage dict

输出信息统计。

属性

image_count integer

本次请求成功生成的图片数量。

（可选）配置域名白名单，允许访问图片链接

根据上述查询接口的响应，可以看到返回了图片OSS链接，如https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png。图片OSS链接允许公开访问，您可以使用此链接查看或者下载图片。

需要注意的是，如果您的业务对安全性要求较高，无法随意访问外网链接，您需要单独配置外网访问白名单。请将以下域名添加到您的白名单中，以便顺利访问图片链接。

  • dashscope-result-bj.oss-cn-beijing.aliyuncs.com

  • dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com

  • dashscope-result-sh.oss-cn-shanghai.aliyuncs.com

  • dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com

  • dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com

  • dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com

  • dashscope-result-hy.oss-cn-heyuan.aliyuncs.com

  • dashscope-result-cd.oss-cn-chengdu.aliyuncs.com

  • dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

此API还有特定状态码，具体如下所示。

HTTP状态码

接口错误码（code）

接口错误信息（message）

含义说明

200

Success

Success

处理成功

400

InvalidParameter

Title field missing.

title字段缺失

Title is not [str].

title字段不是字符串列表

Title list is empty.

title字段为空的数组

Subtitle is not [str].

subtitile字段不是字符串列表

Text is not [str].

text字段不是字符串列表

Invalid URL 'https:xxx.png': No host supplied

图片或者素材的URL地址不正确，无法访问

500

InternalError

Inference error

算法内部错误

上一篇：图像背景生成API参考下一篇：AI试衣OutfitAnyone
文档推荐