RunWritingV2

AI writing

Operation description

For instructions on embedding Quanmiao products using an iframe, see Customer integration_Quanmiao public cloud iframe customized solution.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

• Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

• API: The API that you can call to perform the action.

• Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

• Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

  • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
  • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

• Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

• Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action	Access level	Resource type	Condition key	Dependent action
aimiaobi:RunWritingV2	create	*All Resource *	None	None

Request syntax

POST /quanmiao/aimiaobi/runWritingV2 HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	Yes	The unique ID of the Model Studio workspace. For more information, see Obtain a Workspace ID.	xxxx
TaskId	string	No	The unique ID of the task. You can reuse the same task ID for a multi-turn conversation. The system automatically generates a TaskId if you do not specify one. Reusing the same TaskId for subsequent requests groups them into a single conversation.	3f7045e099474ba28ceca1b4eb6d6e21
SessionId	string	No	The ID of a single-turn conversation. This parameter is deprecated and its use is discouraged.	3f7045e099474ba28ceca1b4eb6d6e21
WritingScene	string	No	The writing scene. Valid values: government (government affairs), media, market (marketing), office, and custom.	media
WritingStyle	string	No	The writing style. For a list of supported styles, see ListWritingStyles.	新闻评论
DistributeWriting	boolean	No	Specifies whether to enable step-by-step writing. For more information, see the Step parameter description.	false
PromptMode	string	No	The prompt mode. Valid values: Template (template mode) and PE (advanced PE mode). If this parameter is omitted, you must provide the Prompt parameter. We recommend that the prompt includes the topic, length, requirements, and prohibitions. If PromptMode is set to Template, you must provide WritingParams, which is a dictionary of string key-value pairs. For the required schema, see the .Data.TemplateDefine[].Fields field in the response of the ListWritingStyles operation. If PromptMode is set to PE, you must pass WritingParams with the following two fields: topic: Required. The topic to write about. prompt: Optional. Any additional custom prompts or writing requirements.	Template
Step	string	No	The step for step-by-step writing. Valid values: OutlineGenerate: Outline generation Writing: Article writing When DistributeWriting is true, the default flow for step-by-step writing is to first generate an outline and then write the content based on it.	Writing
Articles	array<object>	No	A list of articles to use as references. Note: When you provide this parameter, web search is disabled, overriding the UseSearch and SearchSources parameters.
	object	No	The article object.
Title	string	No	The title of the article.	文章标题
Content	string	No	The content of the article.	文章内容
Url	string	No	The URL of the article.	https://www.example.com/aaa.docx
Source	string	No	The source of the article.	新华社
SearchSourceName	string	No	The name of the search source.	QuarkCommonNews
PubTime	string	No	The publication time.	2024-11-25 14:25:59
GcNumberSizeTag	string	No	A string that specifies the desired article length. Examples: "about 300 words", "about 600 words", "about 1,000 words", or "about 2,000 words".	2000字左右
GcNumberSize	integer	No	The number of articles to write. If you request multiple articles, the system returns them concurrently, each with a unique session ID.	2
Language	string	No	The output language for the article. en: English zh: Chinese Other languages or specific style requirements can also be specified.	en
Keywords	array	No	A list of keywords used for both search and writing.
	string	No	A keyword used for both search and writing.	关键词
Prompt	string	No	The writing prompt. You must provide either Prompt or WritingParams. For more information, see the description of the PromptMode parameter.	提示词
WritingParams	object	No	The parameters for template-based writing, provided as a dictionary of string key-value pairs. You must provide either Prompt or WritingParams. For more information, see the description of the PromptMode parameter.
	string	No	A template writing parameter.	模板写作参数
Outlines	array<object>	No	A list of outlines for step-by-step writing. This parameter is deprecated. Use OutlineList instead.
	array<object>	No	The outline object.
Outline	string	No	The outline.	大纲
Articles	array<object>	No	A list of articles referenced by the outline.
	object	No	An article referenced by the outline.
Title	string	No	The title of the article.	标题
Content	string	No	The content of the article.	正文内容
Url	string	No	The URL of the article.	文章URL
Summarization	array<object>	No	A list of summarization objects, used for step-by-step writing.
	object	No	The summarization object.
Event	string	No	The name of the event.	事件名称
Message	string	No	The summary of the event.	事件摘编
MiniDocs	array<object>	No	A list of article snippets.
	object	No	The article snippet object.
Content	string	No	The content of the snippet.	片段内容
Star	boolean	No	Specifies whether to prioritize this snippet.	true
Index	string	No	The index of the article snippet in the referenced article.	索引
UseSearch	boolean	No	Specifies whether to enable web search. If true, the system uses its built-in web search feature. Default: false.	true
SearchSources	array<object>	No	A list of specified search sources to use.
	object	No	The search source object.
Code	string	No	The type of search source. Valid values: SystemSearch (built-in system search), CustomSemanticSearch (search of a custom semantic index), and ThirdSearch (search through a third-party API).	SystemSearch
Name	string	No	The description of the search source. This parameter is deprecated and has no effect.	互联网搜索
DatasetName	string	No	The unique identifier of the data source.	QuarkCommonNews
OutlineList	array	No	A list of outlines for step-by-step writing.
	WritingOutline	No	The outline.
SourceTraceMethod	string	No	The source tracing method. Currently, only modelSourceTrace is supported. If set to modelSourceTrace, the model adds citation markers (for example, [[1]]) to the end of each cited snippet in the generated text. The citation index starts at 1.	modelSourceTrace

API request examples

1. Direct writing (using a prompt)

{
  // Workspace ID
  "WorkspaceId": "your-workspace-id",
  // Enable search
  "UseSearch":true,
  // Writing prompt
  "Prompt": "Write a news commentary on the development of artificial intelligence. The word count must be 800-1000 words. The response must have a clear viewpoint, a logical structure, and avoid exaggerated expressions."
}

2. Template-based writing (PromptMode=Template)

{
  "WorkspaceId": "your-workspace-id",
  "WritingScene": "media",
  "WritingStyle": "news-commentary",
  "PromptMode": "Template",
  "WritingParams": {
    "topic": "Breakthroughs in AI applications in healthcare: a hospital successfully uses an AI-assisted diagnostic system with an accuracy rate above 95%.",
    "corePerspective": "The rapid growth of AI in healthcare shows how technological innovation reshapes traditional industries. However, it also requires robust laws, regulations, and ethical standards to ensure the safe and fair use of the technology."
  }
}

Template field descriptions (media scene):

• topic (required): The topic for the article. Describe the news event in plain language or find a fresh angle on common news stories. 1,000–2,000 characters.
• corePerspective (required): The core perspective. Clearly state a value judgment and reflect the topic's social significance or industry impact. 1,000–2,000 characters.

3. PE mode (PromptMode=PE)

{
  "WorkspaceId": "your-workspace-id",
  "PromptMode": "PE",
  "WritingParams": {
    "topic": "AI development trends",
    "prompt": "Word count: 800-1000 words. Writing style: Clear viewpoint, logical structure, and vivid language. Content requirements: Must include a background, current situation analysis, and future outlook, with an emphasis on innovation. Prohibitions: Avoid exaggerated language and overly technical terms. Other requirements: Must cite specific data and have a well-defined structure."
  }
}

Template field descriptions (PE mode):

• topic (required): The main topic of the content.

• prompt (optional): Additional custom instructions and writing requirements. Organize the content using the following format:

  • Word count: e.g., "800-1000 words" or "around 1500 words"
  • Writing style: e.g., "clear viewpoint and logical structure" or "vivid and engaging language"
  • Content requirements: e.g., "must include a background, current situation analysis, and future outlook" or "emphasize innovation"
  • Prohibitions: e.g., "do not use exaggerated language" or "avoid technical jargon"
  • Other requirements: e.g., "must cite specific data" or "requires a well-defined structure"

  You can separate multiple requirements with periods, semicolons, or line breaks. Recommended format: "Word count: XXX. Writing style: XXX. Content requirements: XXX. Prohibitions: XXX. Other requirements: XXX."

4. Step-by-step writing - Step 1: Generate an outline

{
  "WorkspaceId": "your-workspace-id",
  "WritingStyle": "outlineWriting",
  "WritingScene": "others",
  "Step": "OutlineGenerate",
  "Prompt": "Generate an outline for a news commentary on the development of artificial intelligence. The final article should be 800-1000 words and include three sections: background, current situation analysis, and future outlook."
}

Description:

• The first step generates an outline. The response contains the Outlines field, which includes the generated outline structure.
• The Prompt should clearly specify the outline's topic, word count, and structural requirements.
• Save the returned Outlines structure to pass to the second step.

5. Step-by-step writing - Step 2: Write using the outline

{
  "WorkspaceId": "your-workspace-id",
  "WritingStyle": "outlineWriting",
  "WritingScene": "others",
  "Step": "Writing",
  "OutlineList": [
    {
      "OutlineId": "outline-001",
      "Outline": "Background of AI development",
      "WordCount": "200-300 words",
      "Children": [
        {
          "OutlineId": "outline-001-001",
          "Outline": "Origins of AI technology",
          "WordCount": "100-150 words",
          "Children": []
        },
        {
          "OutlineId": "outline-001-002",
          "Outline": "Current state of development",
          "WordCount": "100-150 words",
          "Children": []
        }
      ]
    },
    {
      "OutlineId": "outline-002",
      "Outline": "Analysis of AI applications",
      "WordCount": "300-400 words",
      "Children": []
    },
    {
      "OutlineId": "outline-003",
      "Outline": "Future development trends",
      "WordCount": "300-400 words",
      "Children": []
    }
  ],
  "Prompt": "Write the article based on the generated outline. The word count should be 800-1,000 words, and the article must have a clear viewpoint, a logical structure, and vivid language."
}

Description:

• In the second step, write the content by passing the Outlines structure from the first step.

• The OutlineList parameter is required and contains the outline tree. Each outline node includes:

  • OutlineId (required): The outline node ID.
  • Outline (required): The outline name.
  • WordCount (optional): The word count requirement for this section.
  • Children (optional): A list of child outlines, which have the same structure as the parent outline.

• You can use the Prompt parameter to specify additional writing requirements, such as word count, writing style, and content requirements.

6. Imitative writing

{
  "WorkspaceId": "your-workspace-id",
  "WritingScene": "custom",
  "WritingStyle": "imitateWriting",
  "PromptMode": "Template",
  "WritingParams": {
    "topic": "The new energy vehicle market is experiencing rapid growth, with sales exceeding 8 million units in 2024, up 35% year-over-year. Policy support, technological advancements, and increasing consumer acceptance are the key driving factors.",
    "styleStructReferenceContent": "[{\"title\":\"The AI industry is seeing explosive growth\",\"content\":\"【Introduction】\\nArtificial intelligence technology is profoundly changing how we work and live. From smart voice assistants and autonomous vehicles to medical diagnostics and financial risk control, the applications for AI continue to expand.\\n\\n【Current Status】\\nAccording to statistics, the global AI market reached $150 billion in 2023 and is projected to exceed $300 billion by 2025. As the world's second-largest AI market, China has made significant progress in algorithms, computing power, and data.\\n\\n【Key Drivers】\\nFirst, increased policy support. The government has introduced multiple policies to support the AI industry, establishing special funds and building innovation platforms.\\nSecond, continuous technological breakthroughs. Technologies like large models and deep learning are maturing, steadily lowering the barrier to adoption.\\nThird, sustained market demand. The acceleration of corporate digital transformation is driving a growing demand for AI solutions.\\n\\n【Challenges and Outlook】\\nDespite rapid development, the AI industry still faces challenges such as data security, algorithmic fairness, and talent shortages. The future requires continuous effort in technological innovation, standards development, and talent cultivation to promote the healthy and sustainable growth of the AI industry.\"}]"
  }
}

Template field descriptions (quick imitative writing):

• topic (required): The article's topic. Describe the main theme and core information for the article. Max 3,000 characters.
• styleStructReferenceContent (required): A list of reference articles that the system uses to learn structure and style. This list must be a JSON-serialized string. Each element in the array must contain title and content fields.

Additional notes:

• Reference articles should have a clear, well-defined structure (e.g., Introduction, Current Status, Analysis, Conclusion).
• The system learns the structure and writing style from the reference articles and then generates a new article based on the provided topic.
• For best results, provide a single reference article with a distinct structure to ensure the generated output is structurally consistent.

Response elements

Element	Type	Description	Example
	object	BaseLlmResponse
Header	object	The response header.
ErrorCode	string	The error code.	错误码
ErrorMessage	string	The error message.	错误信息
Event	string	The type of event. The service returns two types of events: writing events and other events. The writing event, task-progress-start-generating, indicates that the output contains the complete article information. Other events, such as writing-instruction-analysis (instruction analysis), task-progress-news-search-end (web search), and result-intent-recognition-end (intent recognition), can be monitored through the payload.output.text field or ignored.	task-progress-start-generating
OriginSessionId	string	The parent session ID.	3f7045e099474ba28ceca1b4eb6d6e21
SessionId	string	The session ID.	3f7045e099474ba28ceca1b4eb6d6e21
StatusCode	integer	The HTTP status code.	400
TaskId	string	The task ID.	3f7045e099474ba28ceca1b4eb6d6e21
TraceId	string	The trace ID.	全链路ID
Payload	object	The response payload.
Output	object	The output.
Articles	array<object>	The reference articles.
	object	A reference article.
Author	string	The author.	作者
Content	string	The content.	文章内容
DocId	string	The custom unique ID for the document.	文档-自定义的唯一ID
DocUuid	string	The internal unique identifier for the document.	98229f6001cf4deeb1668191d4eccc75
PubTime	string	The publication time.	2024-08-28 11:38:28
Source	string	The source.	央视网
Summary	string	The article summary.	文章摘要
Tag	string	The tag.	文章标签
Title	string	The title.	文章标题
Url	string	The article URL.	https://www.example.com/aaa.docx
MiniDoc	array	A list of refined article snippets.	文章精排之后的片段
	string	A refined article snippet.	文章精排之后的片段
SearchQuery	string	The result of the query rewrite.	大模型改变世界
Text	string	The generated text.	文本生成结果
Outlines	array	A list of outlines. This field is returned when writingStyle is set to outlineWriting and step is outlineWriting.
	WritingOutline	An outline.
Title	string	The article title. This field is returned when writingStyle is set to outlineWriting and step is outlineWriting.	文章标题
SearchResult	OutlineSearchResult	The search result. This field is returned when writingStyle is set to outlineWriting and step is OutlineSearch.
GenerateTraceability	GenerateTraceability	A traceability object, returned when the modelSourceTrace parameter is provided.
Usage	object	The token usage statistics.
InputTokens	integer	The number of input tokens.	78
OutputTokens	integer	The number of output tokens.	34
TokenMap	object	A detailed breakdown of token consumption.
	integer	The number of tokens used for a specific sub-task.	44
TotalTokens	integer	The total number of tokens.	38
RequestId	string	The request ID.	3f7045e099474ba28ceca1b4eb6d6e21
End	boolean	Indicates whether this is the final message in the response stream.	true

Examples

Success response

JSON format

{
  "Header": {
    "ErrorCode": "错误码",
    "ErrorMessage": "错误信息",
    "Event": "task-progress-start-generating",
    "OriginSessionId": "3f7045e099474ba28ceca1b4eb6d6e21",
    "SessionId": "3f7045e099474ba28ceca1b4eb6d6e21",
    "StatusCode": 400,
    "TaskId": "3f7045e099474ba28ceca1b4eb6d6e21",
    "TraceId": "全链路ID"
  },
  "Payload": {
    "Output": {
      "Articles": [
        {
          "Author": "作者",
          "Content": "文章内容",
          "DocId": "文档-自定义的唯一ID",
          "DocUuid": "98229f6001cf4deeb1668191d4eccc75",
          "PubTime": "2024-08-28 11:38:28",
          "Source": "央视网",
          "Summary": "文章摘要",
          "Tag": "文章标签",
          "Title": "文章标题",
          "Url": "https://www.example.com/aaa.docx"
        }
      ],
      "MiniDoc": [
        "文章精排之后的片段"
      ],
      "SearchQuery": "大模型改变世界",
      "Text": "文本生成结果",
      "Outlines": [
        {
          "WritingTips": "大纲写作要求、写作提示",
          "OutlineId": "xxx",
          "Outline": "大纲名称",
          "SearchKeyWordList": [
            "检索关键词"
          ],
          "WordCount": "写作字数要求的描述",
          "Articles": [
            {
              "Url": "http://www.example.com/xxxx.html",
              "Title": "新闻标题",
              "Content": "新闻内容",
              "SearchSource": "检索源编码",
              "SearchSourceName": "检索源名称",
              "PubTime": "2023-04-11 06:14:07",
              "PrimaryOutline": "一级大纲名称",
              "Outline": "大纲名称"
            }
          ],
          "Children": [
            {
              "WritingTips": "大纲写作要求、写作提示",
              "OutlineId": "xxx",
              "Outline": "大纲名称",
              "SearchKeyWordList": [
                "检索关键词"
              ],
              "WordCount": "写作字数要求的描述",
              "Articles": [
                {
                  "Url": "http://www.example.com/xxxx.html",
                  "Title": "新闻标题",
                  "Content": "新闻内容",
                  "SearchSource": "检索源编码",
                  "SearchSourceName": "检索源名称",
                  "PubTime": "2023-04-11 06:14:07",
                  "PrimaryOutline": "一级大纲名称",
                  "Outline": "大纲名称"
                }
              ],
              "Children": [
                {
                  "WritingTips": "大纲写作要求、写作提示",
                  "OutlineId": "xxx",
                  "Outline": "大纲名称",
                  "SearchKeyWordList": [
                    "检索关键词"
                  ],
                  "WordCount": "写作字数要求的描述",
                  "Articles": [
                    {
                      "Url": "http://www.example.com/xxxx.html",
                      "Title": "新闻标题",
                      "Content": "新闻内容",
                      "SearchSource": "检索源编码",
                      "SearchSourceName": "检索源名称",
                      "PubTime": "2023-04-11 06:14:07",
                      "PrimaryOutline": "一级大纲名称",
                      "Outline": "大纲名称"
                    }
                  ],
                  "Children": []
                }
              ]
            }
          ]
        }
      ],
      "Title": "文章标题",
      "SearchResult": {
        "Query": "高校环保义卖案例 大学生旧物循环利用率的文章",
        "Outline": "晨光中的自律：清晨6:30的校园",
        "OutlineId": "xxxxxx",
        "PrimaryOutline": "大学生正能量的一天",
        "Articles": []
      },
      "GenerateTraceability": {
        "News": [
          {
            "Url": "http://www.example.com/xxx.html\n",
            "Title": "新闻标题",
            "PubTime": "2024-01-22 10:29:00",
            "SearchSourceName": "检索源编码\n\n",
            "SearchSource": "检索源唯一标识",
            "Index": 2
          }
        ]
      }
    },
    "Usage": {
      "InputTokens": 78,
      "OutputTokens": 34,
      "TokenMap": {
        "key": 44
      },
      "TotalTokens": 38
    }
  },
  "RequestId": "3f7045e099474ba28ceca1b4eb6d6e21",
  "End": true
}

Error codes

HTTP status code	Error code	Error message	Description
403	NoPermission	You are not authorized to perform this action.	Please check the workspaceId assignment

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.