DEV Community: hongyu

Google SERP API (Search Engine Results Page)Integration Guide

hongyu — Fri, 25 Apr 2025 06:26:30 +0000

Google SERP (Search Engine Results Page) is the results page that users see after entering a query into the Google search engine. It displays organic search results, ads, featured snippets, knowledge graphs, and various other content types, aiming to provide users with the most relevant information.

This article will detail the Google SERP API, which can provide results for queries entered into the Google search engine. The content of the results includes many types, such as featured snippets, knowledge graphs, and images.

This document will outline the integration instructions for the Google SERP API.

Application Process

To use the Google SERP API, you need to apply for the corresponding service on the Google SERP API page. Once you enter the page, click on the "Acquire" button, as shown in the image below:

If you have not logged in or registered, you will automatically be redirected to the login page inviting you to register and log in. After logging in or registering, you will be returned to the current page.

When applying for the first time, a free quota will be granted, allowing you to use the API for free.

Basic Usage

First, understand the basic usage method, which is to input the search keyword to get search results. You only need to pass a query field and specify the corresponding model.

For example, asking: "apple inc," we can then fill in the corresponding content on the interface, as shown in the image below:

Here we can see that we have set the Request Headers, including:

accept: The format of response results you want to receive, here we fill it in as application/json, which means JSON format.
authorization: The key to call the API, which can be selected directly after application.

Additionally, the Request Body is set as follows:

action: The type of resource to search, currently supporting only six types, with search as the default.
query: The search keyword.
country: Custom country for the search results, defaulting to the United States (US).
language: Custom language for the search results, defaulting to English (en).
range: Custom time range for the search results, with no restrictions by default.
number: Custom pagination page size for the search results, defaulting to 10.
page: Custom pagination page number for the search results, defaulting to 1.

After selecting, you can find that the corresponding code is also generated on the right side, as shown in the image below:

Click the "Try" button to test, as shown in the image above; here we obtained the following results:

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQwGQRv5TjjkycpctY66mOg_e2-npacrmjAb6_jAWhzlzkFE3OTjxyzbA&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "description_source": "Wikipedia",
    "description_link": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "Customer service": "1 (800) 275-2273",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Headquarters": "Cupertino, CA",
      "COO": "Jeff Williams",
      "CEO": "Tim Cook (Aug 24, 2011–)",
      "Founded": "April 1, 1976, Los Altos, CA"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        },
        {
          "title": "Careers at Apple",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "iPhone",
          "link": "https://www.apple.com/iphone/?section-banner-soip-suerte"
        },
        {
          "title": "Mac",
          "link": "https://www.apple.com/mac/"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "sitelinks": [
        {
          "title": "History",
          "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
        },
        {
          "title": "List of Apple products",
          "link": "https://en.wikipedia.org/wiki/List_of_Apple_products"
        },
        {
          "title": "Litigation involving Apple Inc.",
          "link": "https://en.wikipedia.org/wiki/Litigation_involving_Apple_Inc."
        },
        {
          "title": "Apple Park",
          "link": "https://en.wikipedia.org/wiki/Apple_Park"
        }
      ],
      "position": 2
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "See the company profile for Apple Inc. (AAPL) including business summary, industry/sector information, number of employees, business summary, ...",
      "position": 3
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, ...",
      "position": 4
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 5
    },
    {
      "title": "Apple Inc - Company Profile and News - Bloomberg Markets",
      "link": "https://www.bloomberg.com/profile/company/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related ...",
      "position": 6
    },
    {
      "title": "Apple | AAPL Stock Price, Company Overview & News - Forbes",
      "link": "https://www.forbes.com/companies/apple/",
      "snippet": "Apple, Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other variety of ...",
      "position": 7
    }
  ],
  "people_also_ask": [
    {
      "question": "What is Apple Inc stand for?",
      "snippet": "It was incorporated as Apple Computer, Inc. in January 1977, and sales of its computers, including the Apple II, saw significant momentum and revenue growth for the company. \"Inc.\" is the abbreviation for incorporated. A corporation is a separate legal entity from the person or people forming it.",
      "title": "What does the 'Inc.' in Apple Inc. mean? - Quora",
      "link": "https://www.quora.com/What-does-the-Inc-in-Apple-Inc-mean"
    },
    {
      "question": "Who owns Apple Inc.?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail and individual investors. Approximately 48.76% of the company's stock is owned by Institutional Investors, 0.11% is owned by Insiders and 51.13% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "Why did Apple change to Apple Inc?",
      "snippet": "During his keynote speech at the Macworld Expo on January 9, 2007, Jobs announced the renaming of Apple Computer, Inc. to Apple Inc., because the company had broadened its focus from computers to consumer electronics. This event also saw the announcement of the iPhone and the Apple TV.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Why Apple Inc is called Apple?",
      "snippet": "With the name Apple, the new computer company would appear ahead of Atari, where Jobs used to work. Jobs confirmed this theory in an 1980 presentation, stating that the name was partly chosen because he liked apples and partly because Apple was ahead of Atari in the phone book.",
      "title": "Why Is Apple Called Apple? - Apple Scoop",
      "link": "https://applescoop.org/story/why-is-apple-called-apple"
    }
  ],
  "related_searches": [
    {
      "query": "Macintosh"
    },
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple company history"
    },
    {
      "query": "Apple company owner"
    },
    {
      "query": "Apple Store"
    },
    {
      "query": "Apple Inc careers"
    },
    {
      "query": "Apple us"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple Inc website"
    }
  ],
  "credits": 1
}

The returned result contains multiple fields, described as follows:

knowledge_graph: The knowledge graph of the search results.
organic: Detailed information from the search results.
people_also_ask: Questions related to the search keywords.
related_searches: Related searches for the search keywords.

As can be seen, there is an organic field returned, which mainly contains the results for the search keyword.

Additionally, if you want to generate corresponding interface code, you can directly copy it, such as the CURL code shown below:

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "query": "apple inc"
}'

The Python interface code is as follows:

import requests

url = "https://api.acedata.cloud/serp/google"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
data = {
    "query": "apple inc"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())

import requests

url = "https://api.acedata.cloud/serp/google"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "query": "apple inc"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Custom Search Type

If you want to customize the type of search resources, we can modify the parameter action, which includes regular resources search, image resources images, news resources news, map resources maps, local resources places, and video resources videos. This article will demonstrate with video resources videos.

Next, let's demonstrate the specific operation.

First, set the action parameter to videos, and pass the query parameter normally, as shown in the image:

The corresponding code is as follows:

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer 018e9d5864524c0fb3ef725c676a0daa' \
-H 'content-type: application/json' \
-d '{
  "action": "videos",
  "query": "apple inc"
}'

You can get the following response:

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQwGQRv5TjjkycpctY66mOg_e2-npacrmjAb6_jAWhzlzkFE3OTjxyzbA&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "description_source": "Wikipedia",
    "description_link": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "Customer service": "1 (800) 275-2273",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Headquarters": "Cupertino, CA",
      "COO": "Jeff Williams",
      "CEO": "Tim Cook (Aug 24, 2011–)",
      "Founded": "April 1, 1976, Los Altos, CA"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        },
        {
          "title": "Careers at Apple",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "Mac",
          "link": "https://www.apple.com/mac/"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "sitelinks": [
        {
          "title": "History",
          "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
        },
        {
          "title": "List of Apple products",
          "link": "https://en.wikipedia.org/wiki/List_of_Apple_products"
        },
        {
          "title": "Litigation involving Apple Inc.",
          "link": "https://en.wikipedia.org/wiki/Litigation_involving_Apple_Inc."
        },
        {
          "title": "Apple Park",
          "link": "https://en.wikipedia.org/wiki/Apple_Park"
        }
      ],
      "position": 2
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "See the company profile for Apple Inc. (AAPL) including business summary, industry/sector information, number of employees, business summary, ...",
      "position": 3
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, ...",
      "position": 4
    },
    {
      "title": "Apple Inc - Company Profile and News - Bloomberg Markets",
      "link": "https://www.bloomberg.com/profile/company/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related ...",
      "position": 5
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 6
    },
    {
      "title": "Apple | AAPL Stock Price, Company Overview & News - Forbes",
      "link": "https://www.forbes.com/companies/apple/",
      "snippet": "Apple, Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other variety of ...",
      "position": 7
    }
  ],
  "places": [
    {
      "title": "Apple Inc.",
      "address": "Austin, TX",
      "cid": "6364221923344007436"
    },
    {
      "title": "Apple Lonestar Design Center",
      "address": "West Lake Hills, TX",
      "cid": "96664910012456098"
    },
    {
      "title": "Apple Barton Creek",
      "address": "Austin, TX",
      "cid": "10695409311125452147"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is Apple Inc stand for?",
      "snippet": "It was incorporated as Apple Computer, Inc. in January 1977, and sales of its computers, including the Apple II, saw significant momentum and revenue growth for the company. \"Inc.\" is the abbreviation for incorporated. A corporation is a separate legal entity from the person or people forming it.",
      "title": "What does the 'Inc.' in Apple Inc. mean? - Quora",
      "link": "https://www.quora.com/What-does-the-Inc-in-Apple-Inc-mean"
    },
    {
      "question": "Who owns Apple Inc.?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail and individual investors. Approximately 48.76% of the company's stock is owned by Institutional Investors, 0.11% is owned by Insiders and 51.13% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "Why did Apple change to Apple Inc?",
      "snippet": "During his keynote speech at the Macworld Expo on January 9, 2007, Jobs announced the renaming of Apple Computer, Inc. to Apple Inc., because the company had broadened its focus from computers to consumer electronics. This event also saw the announcement of the iPhone and the Apple TV.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Why Apple Inc is called Apple?",
      "snippet": "With the name Apple, the new computer company would appear ahead of Atari, where Jobs used to work. Jobs confirmed this theory in an 1980 presentation, stating that the name was partly chosen because he liked apples and partly because Apple was ahead of Atari in the phone book.",
      "title": "Why Is Apple Called Apple? - Apple Scoop",
      "link": "https://applescoop.org/story/why-is-apple-called-apple"
    }
  ],
  "related_searches": [
    {
      "query": "Macintosh"
    },
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple company history"
    },
    {
      "query": "Apple company owner"
    },
    {
      "query": "Apple Store"
    },
    {
      "query": "Apple Inc careers"
    },
    {
      "query": "Apple us"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple Inc website"
    }
  ],
  "credits": 1
}

As we can see, the result obtained is similar to the above text.

Customizing Search Resources by Country

This API also supports limiting search results by country, we can add the country parameter to specify the country, the input parameter is the abbreviation for the country, such as cn (China), us (United States), this article will take China as the following example, here is the specific information:

The output effect is as follows:

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQwGQRv5TjjkycpctY66mOg_e2-npacrmjAb6_jAWhzlzkFE3OTjxyzbA&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "description_source": "Wikipedia",
    "description_link": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "Customer service": "400 666 8800",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Headquarters": "Cupertino, California, United States",
      "COO": "Jeff Williams",
      "CEO": "Tim Cook (Aug 24, 2011–)",
      "Founded": "April 1, 1976, Los Altos, California, United States"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        },
        {
          "title": "India",
          "link": "https://www.apple.com/in/"
        },
        {
          "title": "Apple UK",
          "link": "https://www.apple.com/uk/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "sitelinks": [
        {
          "title": "History",
          "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
        },
        {
          "title": "Litigation involving Apple Inc.",
          "link": "https://en.wikipedia.org/wiki/Litigation_involving_Apple_Inc."
        },
        {
          "title": "Apple Park",
          "link": "https://en.wikipedia.org/wiki/Apple_Park"
        },
        {
          "title": "Apple Watch",
          "link": "https://en.wikipedia.org/wiki/Apple_Watch"
        }
      ],
      "position": 2
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "See the company profile for Apple Inc. (AAPL) including business summary, industry/sector information, number of employees, business summary, ...",
      "position": 3
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 4
    },
    {
      "title": "Apple (中国大陆) - 官方网站",
      "link": "https://www.apple.com.cn/",
      "snippet": "探索Apple 的创新世界，选购各式iPhone、iPad、Apple Watch 和Mac，浏览各类配件、娱乐产品，并获得相关产品的专家服务支持。",
      "position": 5
    },
    {
      "title": "Apple Inc - Company Profile and News - Bloomberg Markets",
      "link": "https://www.bloomberg.com/profile/company/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related ...",
      "position": 6
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, ...",
      "position": 7
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the Apple Inc?",
      "snippet": "Apple Inc., originally Apple Computer, Inc., is a multinational corporation that creates and markets consumer electronics and attendant computer software, and is a digital distributor of media content. Apple's core product lines are the iPhone smartphone, iPad tablet computer, and the Macintosh personal computer.",
      "title": "History of Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
    },
    {
      "question": "Who owns Apple Inc.?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail and individual investors. Approximately 48.76% of the company's stock is owned by Institutional Investors, 0.11% is owned by Insiders and 51.13% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "Why did Apple change to Apple Inc?",
      "snippet": "During his keynote speech at the Macworld Expo on January 9, 2007, Jobs announced the renaming of Apple Computer, Inc. to Apple Inc., because the company had broadened its focus from computers to consumer electronics. This event also saw the announcement of the iPhone and the Apple TV.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Why Apple Inc is called Apple?",
      "snippet": "With the name Apple, the new computer company would appear ahead of Atari, where Jobs used to work. Jobs confirmed this theory in an 1980 presentation, stating that the name was partly chosen because he liked apples and partly because Apple was ahead of Atari in the phone book.",
      "title": "Why Is Apple Called Apple? - Apple Scoop",
      "link": "https://applescoop.org/story/why-is-apple-called-apple"
    }
  ],
  "related_searches": [
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple company history"
    },
    {
      "query": "Apple company owner"
    },
    {
      "query": "Apple Store"
    },
    {
      "query": "Apple us"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple Inc website"
    },
    {
      "query": "Apple Inc headquarters"
    }
  ],
  "credits": 1
}

It can be seen that the results include search results in the country of China, with content similar to the above.

Customizing Search Result Language

We can also customize the language of search results, here we additionally add the language field, which contains zh-cn, indicating the language of Simplified Chinese, while other languages are also supported, but the abbreviations of the languages must be input, such as en (English), fr (French), zh-cn (Chinese (Simplified)), etc., as shown in the image:

The corresponding code is as follows:

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "query": "apple inc",
  "language": "zh-cn"
}'

The running result is as follows:

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRgbY1KzXEpuPeTpcw0GwN6BpQTcg1m06TDUsfdG6P-zW3eWrmu78AXyg&s=0",
    "attributes": {
      "founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "established": "April 1, 1976, Los Altos, California",
      "headquarters": "Cupertino, California"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Careers at Apple",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        },
        {
          "title": "Apple UK",
          "link": "https://www.apple.com/uk/"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "sitelinks": [
        {
          "title": "History",
          "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
        },
        {
          "title": "Litigation involving Apple Inc.",
          "link": "https://en.wikipedia.org/wiki/Litigation_involving_Apple_Inc."
        },
        {
          "title": "Apple Park",
          "link": "https://en.wikipedia.org/wiki/Apple_Park"
        },
        {
          "title": "Apple Watch",
          "link": "https://en.wikipedia.org/wiki/Apple_Watch"
        }
      ],
      "position": 2
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, ...",
      "position": 3
    },
    {
      "title": "Apple Inc - Company Profile and News - Bloomberg Markets",
      "link": "https://www.bloomberg.com/profile/company/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related ...",
      "position": 4
    },
    {
      "title": "Apple Inc. (AAPL) Stock Price, News, Quote & History - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.",
      "date": "August 27, 2024",
      "position": 5
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 6
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "See the company profile for Apple Inc. (AAPL) including business summary, industry/sector information, number of employees, business summary, ...",
      "position": 7
    }
  ],
  "people_also_ask": [
    {
      "question": "What does Apple Inc stand for?",
      "snippet": "It was incorporated as Apple Computer, Inc. in January 1977, and sales of its computers, including the Apple II , saw significant momentum and revenue growth for the company. \"Inc.\" is the abbreviation for incorporated. A corporation is a separate legal entity from the person or people forming it.",
      "title": "What does the 'Inc.' in Apple Inc. mean? - Quora",
      "link": "https://www.quora.com/What-does-the-Inc-in-Apple-Inc-mean"
    },
    {
      "question": "Who owns Apple Inc.?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail, and individual investors. Approximately 48.76% of the company's stock is owned by Institutional Investors, 0.11% is owned by Insiders, and 51.13% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "Why did Apple change to Apple Inc?",
      "snippet": "During his keynote speech at the Macworld Expo on January 9, 2007, Jobs announced the renaming of Apple Computer, Inc. to Apple Inc., because the company had broadened its focus from computers to consumer electronics. This event also saw the announcement of the iPhone and the Apple TV.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Why is Apple Inc called Apple?",
      "snippet": "With the name Apple, the new computer company would appear ahead of Atari, where Jobs used to work. Jobs confirmed this theory in a 1980 presentation, stating that the name was partly chosen because he liked apples and partly because Apple was ahead of Atari in the phone book.",
      "title": "Why Is Apple Called Apple? - Apple Scoop",
      "link": "https://applescoop.org/story/why-is-apple-called-apple"
    }
  ],
  "related_searches": [
    {
      "query": "What is apple inc"
    },
    {
      "query": "apple Macau"
    },
    {
      "query": "Apple ID"
    },
    {
      "query": "apple USA"
    },
    {
      "query": "apple official website"
    },
    {
      "query": "apple USA official website"
    },
    {
      "query": "Apple company introduction"
    },
    {
      "query": "apple id official website"
    }
  ],
  "credits": 1
}

It can be seen that the results displayed here are in Simplified Chinese, and the content of the results is similar to the above.

Custom Search Result Time Range

This article can also customize the time range of search results, which includes five types: qdr:h (past hour), qdr:d (past day), qdr:w (past week), qdr:m (past month), and by default, unlimited. We can pass the corresponding time range through range, for example, here set to qdr:d, which indicates searching for results from the past day, hence the input is as follows:

The corresponding code is as follows:

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "range": "qdr:d",
  "query": "apple inc"
}'

The running result is as follows:

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQwGQRv5TjjkycpctY66mOg_e2-npacrmjAb6_jAWhzlzkFE3OTjxyzbA&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "description_source": "Wikipedia",
    "description_link": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "Customer service": "1 (800) 275-2273",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Headquarters": "Cupertino, CA",
      "COO": "Jeff Williams",
      "CEO": "Tim Cook (Aug 24, 2011–)",
      "Founded": "April 1, 1976, Los Altos, CA"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        },
        {
          "title": "Careers at Apple",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "Mac",
          "link": "https://www.apple.com/mac/"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "sitelinks": [
        {
          "title": "History",
          "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
        },
        {
          "title": "List of Apple products",
          "link": "https://en.wikipedia.org/wiki/List_of_Apple_products"
        },
        {
          "title": "Litigation involving Apple Inc.",
          "link": "https://en.wikipedia.org/wiki/Litigation_involving_Apple_Inc."
        },
        {
          "title": "Apple Park",
          "link": "https://en.wikipedia.org/wiki/Apple_Park"
        }
      ],
      "position": 2
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "See the company profile for Apple Inc. (AAPL) including business summary, industry/sector information, number of employees, business summary, ...",
      "position": 3
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, ...",
      "position": 4
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 5
    },
    {
      "title": "Apple Inc - Company Profile and News - Bloomberg Markets",
      "link": "https://www.bloomberg.com/profile/company/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related ...",
      "position": 6
    },
    {
      "title": "Apple | AAPL Stock Price, Company Overview & News - Forbes",
      "link": "https://www.forbes.com/companies/apple/",
      "snippet": "Apple, Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other variety of ...",
      "position": 7
    }
  ],
  "places": [
    {
      "title": "Apple Inc.",
      "address": "Austin, TX",
      "cid": "6364221923344007436"
    },
    {
      "title": "Apple Lonestar Design Center",
      "address": "West Lake Hills, TX",
      "cid": "96664910012456098"
    },
    {
      "title": "Apple The Summit",
      "address": "Birmingham, AL",
      "cid": "15135424056620472574"
    }
  ],
  "people_also_ask": [
    {
      "question": "What does Apple Inc stand for?",
      "snippet": "It was incorporated as Apple Computer, Inc. in January 1977, and sales of its computers, including the Apple II , saw significant momentum and revenue growth for the company. \"Inc.\" is the abbreviation for incorporated. A corporation is a separate legal entity from the person or people forming it.",
      "title": "What does the 'Inc.' in Apple Inc. mean? - Quora",
      "link": "https://www.quora.com/What-does-the-Inc-in-Apple-Inc-mean"
    },
    {
      "question": "Who owns Apple Inc.?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail and individual investors. Approximately 48.76% of the company's stock is owned by Institutional Investors, 0.11% is owned by Insiders and 51.13% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "Why did Apple change to Apple Inc?",
      "snippet": "During his keynote speech at the Macworld Expo on January 9, 2007, Jobs announced the renaming of Apple Computer, Inc. to Apple Inc., because the company had broadened its focus from computers to consumer electronics. This event also saw the announcement of the iPhone and the Apple TV.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Why is Apple Inc called Apple?",
      "snippet": "With the name Apple, the new computer company would appear ahead of Atari, where Jobs used to work. Jobs confirmed this theory in an 1980 presentation, stating that the name was partly chosen because he liked apples and partly because Apple was ahead of Atari in the phone book.",
      "title": "Why Is Apple Called Apple? - Apple Scoop",
      "link": "https://applescoop.org/story/why-is-apple-called-apple"
    }
  ],
  "related_searches": [
    {
      "query": "Macintosh"
    },
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple company history"
    },
    {
      "query": "Apple company owner"
    },
    {
      "query": "Apple Store"
    },
    {
      "query": "Apple Inc careers"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple us"
    },
    {
      "query": "Apple Inc website"
    }
  ],
  "credits": 1
}

We can see that we have successfully obtained the search results from the past day, with the content similar to the above text.

Custom Search Result Pagination

This API also supports custom pagination of search results, where number and page indicate the page size and number of the pagination. This article will set the format to display 20 search results per page, with specific information as shown in the image:

It can be seen that it paginates the search results, displaying 20 results per page, similar to the content above.

Global HTTP/Socks5 Rotating Proxy

hongyu — Thu, 24 Apr 2025 04:24:24 +0000

AceData: All-in-One AI Creative Studio offers comprehensive AI services, including Q&A, image generation, QR codes, music, and more, along with diverse API platform integrations to meet your varied needs. New users receive free usage credits to help you create with ease!"

This document mainly introduces the connection instructions for Ace Data Cloud's global proxy, including application methods, usage methods, and other specific content.

Application Method

To use the global service, you can first apply at the "Application Page", and you will receive 1 free credit for your first application.

If you are not logged in, you will automatically be redirected to the login page. After logging in, you can continue with your application.

Usage Method

After the application is complete, you can check your application results in the "Console," as shown in the figure below:

Click on "Credentials" to view the username and password for using the global proxy service, separated by a colon. The username is 8 characters long, and the password is 32 characters long, as shown in the figure below:

This proxy is a rotating proxy, so you only need to set a fixed proxy address and port for use. The proxy address and port are global.proxy.acedata.cloud and 30007, respectively. This proxy supports HTTP/HTTPS/SOCKS protocols and can be used to request HTTP and HTTPS websites.

Note: This proxy can only be used outside mainland China. It cannot be used within mainland China.

Command Testing

Once you have the proxy username and password, the easiest way to test is by using the curl command line. If you haven't installed it yet, please refer to https://curl.se/ for installation.

Assuming the current proxy username and password are 1f78266a:eff0896726224fa2a99fe82dd1f07562, you can test it using the following curl command:

curl -x 1f78266a:eff0896726224fa2a99fe82dd1f07562@global.proxy.acedata.cloud:30007 https://ipinfo.io

Here, we use the curl -x parameter to specify the proxy address. The default proxy protocol is HTTP/HTTPS. The URL requested is https://ipinfo.io, which can return the real IP address and geographical location of the requesting IP.

Note: The above username and password may be invalid; please replace them with your own username and password.

The output result is as follows:

{
  "ip": "66.206.249.77",
  "hostname": "host-66-206-249-77.public.eastlink.ca",
  "city": "Kirkland Lake",
  "region": "Ontario",
  "country": "CA",
  "loc": "48.1446,-80.0377",
  "org": "AS11260 EastLink",
  "postal": "P2N",
  "timezone": "America/Toronto",
  "readme": "https://ipinfo.io/missingauth"
}

As you can see, the returned country is CA, which represents Canada. If you run it again, you can get different results; each request uses a random IP exit.

Code Connection

Below is an example of how to set up the proxy using Python:

import requests

proxy = 'http://{proxy_username}:{proxy_password}@global.proxy.acedata.cloud:30007'

proxies = {
    'http': proxy,
    'https': proxy
}

for _ in range(3):
    resp = requests.get('https://ipinfo.io', proxies=proxies)
    print(resp.text)

Here, we first declare the proxy URL and assign it to the proxy variable. The protocol is HTTP, followed by the username and password for the tunnel proxy (i.e., the username and password displayed in the console, separated by a colon), then an @ symbol, followed by the proxy address and port.

Note: You need to replace {proxy_username}:{proxy_password} in the code above with your proxy username and password. The final result should look like proxy = 'http://1f78266a:eff0896726224fa2a99fe82dd1f07562@global.proxy.acedata.cloud:30007', noting that there are no { and } characters.

Next, we declare a proxies variable that configures two key-value pairs, with the keys named http and https, both set to the proxy variable, indicating that for HTTP and HTTPS websites, the requests will be made using the proxy defined in the proxy variable. We then define a loop to test the proxy three times.

The output result is as follows:

{
  "ip": "103.190.205.165",
  "hostname": "assigned-for-client.adnsl.com",
  "city": "Paltan",
  "region": "Dhaka Division",
  "country": "BD",
  "loc": "23.7362,90.4143",
  "org": "AS38203 ADN Telecom Ltd.",
  "postal": "1000",
  "timezone": "Asia/Dhaka",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "74.111.25.181",
  "hostname": "pool-74-111-25-181.syrcny.fios.verizon.net",
  "city": "Syracuse",
  "region": "New York",
  "country": "US",
  "loc": "43.0481,-76.1474",
  "org": "AS701 Verizon Business",
  "postal": "13201",
  "timezone": "America/New_York",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "207.113.168.248",
  "city": "LaPorte",
  "region": "Indiana",
  "country": "US",
  "loc": "41.6106,-86.7225",
  "org": "AS13428 Surf Air Wireless, LLC",
  "postal": "46350",
  "timezone": "America/Chicago",
  "readme": "https://ipinfo.io/missingauth"
}

As you can see, each run yields a random proxy IP, and the IP's geographical location is indeed from different countries and cities worldwide.

Of course, the above proxy setup method is actually a relatively simple configuration.

In fact, the above code is equivalent to setting an additional Header - Proxy Authorization at the time of the request, so the above code can also be rewritten as follows:

import requests
import base64

proxy_host = 'global.proxy.acedata.cloud'
proxy_port = '30007'
proxy_username = '{proxy_username}' # 8 character username
proxy_password = '{proxy_password}' # 32 character password

credentials = base64.b64encode(
    f'{proxy_username}:{proxy_password}'.encode()).decode()

proxies = {
    'http': f'http://{proxy_host}:{proxy_port}',
    'https': f'http://{proxy_host}:{proxy_port}'
}

headers = {
    'Proxy-Authorization': f'Basic {credentials}'
}

for _ in range(3):
    resp = requests.get('https://ipinfo.io',
                        proxies=proxies, headers=headers)
    print(resp.text)

As you can see, here we have set the proxy username and password via the Proxy-Authorization request header (which needs to be Base64 encoded), achieving the same result as before.

For other languages, such as JavaScript's axios, a similar setup method can also be used:

const axios = require("axios");
const base64 = require("base64");

const proxy_host = "global.proxy.acedata.cloud";
const proxy_port = "30007";
const proxy_username = "{proxy_username}"; // 8-character username
const proxy_password = "{proxy_password}"; // 32-character password

const credentials = base64.encode(`${proxy_username}:${proxy_password}`);

const proxies = {
  http: `http://${proxy_host}:${proxy_port}`,
  https: `http://${proxy_host}:${proxy_port}`,
};

const headers = {
  "Proxy-Authorization": `Basic ${credentials}`,
};

for (let i = 0; i < 3; i++) {
  axios
    .get("https://ipinfo.io", { proxies, headers })
    .then((resp) => console.log(resp.data))
    .catch((err) => console.error(err));
}

The running effect is the same.

For the configuration methods in other languages, please refer to the above text and rewrite accordingly.

Region Filtering

We can filter the region by adding the region in the username, for example, if you want to choose a proxy from the United States, the original username is 1f78266a, you can change the username to 1f78266a-region-us, the above curl can be rewritten as follows:

curl -x 1f78266a-region-us:eff0896726224fa2a99fe82dd1f07562@global.proxy.acedata.cloud:30007 https://ipinfo.io

Region list:
| Country or Region Name | Country/Region Code |
| ------------------- | ------------------ |
| United States | us |
| Hong Kong | hk |
| Andorra | ad |
| United Arab Emirates | ae |
| Afghanistan | af |
| Antigua and Barbuda | ag |
| Anguilla | ai |
| Albania | al |
| Armenia | am |
| Angola | ao |
| Antarctica | aq |
| Argentina | ar |
| American Samoa | as |
| Austria | at |
| Australia | au |
| Aruba | aw |
| Åland Islands | ax |
| Azerbaijan | az |
| Bosnia and Herzegovina | ba |
| Barbados | bb |
| Bangladesh | bd |
| Belgium | be |
| Burkina Faso | bf |
| Bulgaria | bg |
| Bahrain | bh |
| Burundi | bi |
| Benin | bj |
| Saint Barthélemy | bl |
| Bermuda | bm |
| Brunei | bn |
| Bolivia | bo |
| Dutch Caribbean | bq |
| Brazil | br |
| Bahamas | bs |
| Bhutan | bt |
| Bouvet Island | bv |
| Botswana | bw |
| Belarus | by |
| Belize | bz |
| Canada | ca |
| Cocos (Keeling) Islands | cc |
| Central African Republic | cf |
| Switzerland | ch |
| Chile | cl |
| Cameroon | cm |
| Colombia | co |
| Costa Rica | cr |
| Cuba | cu |
| Cape Verde | cv |
| Christmas Island | cx |
| Cyprus | cy |
| Czech Republic | cz |
| Germany | de |
| Djibouti | dj |
| Denmark | dk |
| Dominica | dm |
| Dominican Republic | do |
| Algeria | dz |
| Ecuador | ec |
| Estonia | ee |
| Egypt | eg |
| Western Sahara | eh |
| Eritrea | er |
| Spain | es |
| Finland | fi |
| Fiji | fj |
| Micronesia | fm |
| Faroe Islands | fo |
| France | fr |
| Gabon | ga |
| Grenada | gd |
| Georgia | ge |
| French Guiana | gf |
| Ghana | gh |
| Gibraltar | gi |
| Greenland | gl |
| Guinea | gn |
| Guadeloupe | gp |
| Equatorial Guinea | gq |
| Greece | gr |
| Guatemala | gt |
| Guam | gu |
| Guinea-Bissau | gw |
| Guyana | gy |
| Heard Island and McDonald Islands | hm |
| Honduras | hn |
| Croatia | hr |
| Haiti | ht |
| Hungary | hu |
| Indonesia | id |
| Ireland | ie |
| Israel | il |
| Isle of Man | im |
| India | in |
| British Indian Ocean Territory | io |
| Iraq | iq |
| Iran | ir |
| Iceland | is |
| Italy | it |
| Jersey | je |
| Jamaica | jm |
| Jordan | jo |
| Japan | jp |
| Cambodia | kh |
| Kiribati | ki |
| Comoros | km |
| Kuwait | kw |
| Cayman Islands | ky |
| Lebanon | lb |
| Liechtenstein | li |
| Sri Lanka | lk |
| Liberia | lr |
| Lesotho | ls |
| Lithuania | lt |
| Luxembourg | lu |
| Latvia | lv |
| Libya | ly |
| Morocco | ma |
| Monaco | mc |
| Moldova | md |
| Montenegro | me |
| French Saint Martin | mf |
| Madagascar | mg |
| Marshall Islands | mh |
| Macedonia | mk |
| Mali | ml |
| Myanmar | mm |
| Macau | mo |
| Martinique | mq |
| Mauritania | mr |
| Montserrat | ms |
| Malta | mt |
| Maldives | mv |
| Malawi | mw |
| Mexico | mx |
| Malaysia | my |
| Namibia | na |
| Niger | ne |
| Norfolk Island | nf |
| Nigeria | ng |
| Nicaragua | ni |
| Netherlands | nl |
| Norway | no |
| Nepal | np |
| Nauru | nr |
| Oman | om |
| Panama | pa |
| Peru | pe |
| French Polynesia | pf |
| Papua New Guinea | pg |
| Philippines | ph |
| Pakistan | pk |
| Poland | pl |
| Pitcairn Islands | pn |
| Puerto Rico | pr |
| Palestine | ps |
| Palau | pw |
| Paraguay | py |
| Qatar | qa |
| Réunion | re |
| Romania | ro |
| Serbia | rs |
| Russia | ru |
| Rwanda | rw |
| Solomon Islands | sb |
| Seychelles | sc |
| Sudan | sd |
| Sweden | se |
| Singapore | sg |
| Slovenia | si |
| Slovakia | sk |
| Sierra Leone | sl |
| San Marino | sm |
| Senegal | sn |
| Somalia | so |
| Suriname | sr |
| South Sudan | ss |
| São Tomé and Príncipe | st |
| El Salvador | sv |
| Syria | sy |
| Eswatini | sz |
| Turks and Caicos Islands | tc |
| Chad | td |
| Togo | tg |
| Thailand | th |
| Tokelau | tk |
| East Timor | tl |
| Tunisia | tn |
| Tonga | to |
| Turkey | tr |
| Tuvalu | tv |
| Tanzania | tz |
| Ukraine | ua |
| Uganda | ug |
| Uruguay | uy |
| Vatican City | va |
| Venezuela | ve |
| British Virgin Islands | vg |
| United States Virgin Islands | vi |
| Vietnam | vn |
| Wallis and Futuna | wf |
| Samoa | ws |
| Yemen | ye |
| Mayotte | yt |
| South Africa | za |
| Zambia | zm |
| Zimbabwe | zw |
| Congo (Brazzaville) | cg |
| Congo (Kinshasa) | cd |
| Mozambique | mz |
| Guernsey | gg |
| Gambia | gm |
| Northern Mariana Islands | mp |
| Ethiopia | et |
| New Caledonia | nc |
| Vanuatu | vu |
| French Southern Territories | tf |
| Niue | nu |
| United States Minor Outlying Islands | um |
| Cook Islands | ck |
| United Kingdom | gb |
| Trinidad and Tobago | tt |
| Saint Vincent and the Grenadines | vc |
| Taiwan | tw |
| New Zealand | nz |
| Saudi Arabia | sa |
| Laos | la |
| North Korea | kp |
| South Korea | kr |
| Portugal | pt |
| Kyrgyzstan | kg |
| Kazakhstan | kz |
| Tajikistan | tj |
| Turkmenistan | tm |
| Uzbekistan | uz |
| Saint Kitts and Nevis | kn |
| Saint Pierre and Miquelon | pm |
| Saint Helena | sh |
| Saint Lucia | lc |
| Mauritius | mu |
| Ivory Coast | ci |
| Kenya | ke |
| Mongolia | mn |

Fixed IP

Similar to the above content, we can achieve a fixed IP for a period of time by adding session in the username followed by a 5-digit fixed number. The effective period is about 10 minutes.

For example, if you want to achieve a fixed IP for a period of time, and the original username is 1f78266a, you can change the username to 1f78266a-session-12345, where 12345 remains the same, thus the IP will remain unchanged for a period of time. The above curl command can be rewritten as follows:

curl -x 1f78266a-session-12345:eff0896726224fa2a99fe82dd1f07562@global.proxy.acedata.cloud:30007 https://ipinfo.io

Purchase More

If your package has run out, you need to purchase more to continue using the proxy service.

To purchase more, please go to the "Application Page" and directly click the "Purchase More" button to make a selection. The more you buy at one time, the cheaper the unit price.

Suno Song Generation API Integration Guide

hongyu — Tue, 22 Apr 2025 02:51:43 +0000

With the widespread application of AI, various AI programs have gradually become popular. AI has gradually penetrated all aspects of people's work and life. The industries involved in AI are also increasing, from initial writing to medical education, and now to music.

Suno is a professional high-quality AI song and music creation platform. Users only need to input simple text prompts to generate songs with vocals based on genre style and lyrics. This AI music generator is developed by team members from well-known tech companies like Meta, TikTok, Kensho, aiming to allow everyone to create beautiful music without any instrumental tools.

Suno has recently upgraded its music generation model to version V3, capable of generating 2-minute songs.

However, Suno does not officially provide an API. AceDataCloud offers a set of Suno APIs that simulate integration with Suno's official platform, allowing for easy and quick music generation.

Application and Usage

To use the Suno Audios API, first, visit the Suno Audios Generation API page and click the "Acquire" button to obtain the credentials needed for requests:

If you are not logged in or registered, you will be automatically redirected to the login page, inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page.

Upon the first application, a free quota will be given, allowing free use of the API.

Basic Usage

Think of any song, you can input any text, for example, if I want to generate a song about Christmas, I can input a song for Christmas, as shown in the picture:

The generated code is as follows:

You can click the "Try" button to directly test the API, wait for 1-2 minutes, and the result is as follows:

{
  "success": true,
  "data": [
    {
      "state": "succeeded",
      "id": "2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5",
      "title": "Winter Wonderland",
      "image_url": "https://cdn1.suno.ai/image_2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5.png",
      "lyric": "[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near",
      "audio_url": "https://cdn1.suno.ai/2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5.mp3",
      "video_url": "https://cdn1.suno.ai/2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5.mp4",
      "created_at": "2024-05-10T16:21:37.624Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "holiday"
    },
    {
      "state": "succeeded",
      "id": "5dca232b-17cc-4896-a2d1-4b59178bf410",
      "title": "Winter Wonderland",
      "image_url": "https://cdn1.suno.ai/image_5dca232b-17cc-4896-a2d1-4b59178bf410.png",
      "lyric": "[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near",
      "audio_url": "https://cdn1.suno.ai/5dca232b-17cc-4896-a2d1-4b59178bf410.mp3",
      "video_url": "https://cdn1.suno.ai/5dca232b-17cc-4896-a2d1-4b59178bf410.mp4",
      "created_at": "2024-05-10T16:21:37.624Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "holiday"
    }
  ]
}

As you can see, we have obtained the content of two songs, including the title, preview image, lyrics, audio, video, and other content.

Field descriptions are as follows:

success: Whether the generation was successful, if successful, it is true, otherwise it is false.
data: A list containing detailed information about the generated songs.
- state: Song generation status, mainly includes four types, as follows:
- succeeded: Generation successful
- pending: In queue
- running: In progress
- error: Failed
- id: Song ID
- title: Song title
- image_url: Song cover image
- lyric: Song lyrics
- audio_url: Song audio file, which opens as an mp3 audio.
- video_url: Song video file, which opens as an mp4 video.
- created_at: Creation time
- model: Model used, generally the latest v3 model
- style: Style

Custom Generation

If you want to customize the generation of lyrics, you can input lyrics:

At this time, the lyric field can be passed with content similar to the following:

[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near

Note, the \n in the lyrics here is a newline character. If you don't know how to generate lyrics, you can use the lyrics generation API provided by AceDataCloud to generate lyrics through a prompt. The API is Suno Lyrics Generation API.

Next, we want to customize the generation of songs based on lyrics, title, and style, and you can specify the following content:

lyric: Lyrics text
custom: Set to true, representing custom generation. This parameter defaults to false, representing generation using prompt.
file: Song title.
style: Song style, optional.

Sample filling is as follows:

After completing the form, the code automatically generated is as follows:

Corresponding code:

curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
"custom": true
}'

Testing is allowed, and the generated effect is similar.

Custom Singer Style Generation Function

If you want to use a singer's style to generate a song, first generate a song through the basic usage in the text above,
specific parameters are shown in the picture below:

After completing the form, the code automatically generated is as follows:

Corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "prompt": "A song for Christmas",
    "model": "chirp-v4"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Click run, and you will find that the result is obtained as follows:

{
  "success": true,
  "task_id": "04067c0f-6655-44b6-8c4f-f443af573ebf",
  "trace_id": "c0a574b6-d5b1-4ddc-9529-b1a3d502a7e9",
  "data": [
    {
      "id": "8bc267d2-9794-412c-a504-974ce3cba254",
      "title": "Jingle All the Way",
      "image_url": "https://cdn2.suno.ai/image_8bc267d2-9794-412c-a504-974ce3cba254.jpeg",
      "lyric": "[Verse]\nSnowflakes dancing in the street\nWarm cocoa can't be beat\nNeighbours laugh as carolers sing\nJoyful bells begin to ring\n[Verse 2]\nCandy canes and mistletoe\nSparkling lights that gleam and glow\nWrinkled paper ribbons flying\nSmiling faces never lying\n[Chorus]\nJingle all the way tonight\nStars above are shining bright\nGifts of laughter love and cheer\nMaking memories so dear\n[Verse 3]\nStockings hanging by the fire\nEvery heart is full of desire\nSilent wishes whispered low\nUnderneath the mistletoe\n[Bridge]\nChildren dreaming of delight\nSanta's sleigh takes flight tonight\nMagic sparkles in the air\nChristmas wonder everywhere\n[Verse 4]\nWrapping presents with a bow\nFeeling love in every show\nFamily gathered round the tree\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/8bc267d2-9794-412c-a504-974ce3cba254.mp3",
      "video_url": "https://cdn1.suno.ai/8bc267d2-9794-412c-a504-974ce3cba254.mp4",
      "created_at": "2025-01-04T03:26:59.710Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "pop",
      "duration": 181.56
    },
    {
      "id": "8ebdcf48-1d4d-4b8a-94bc-ec46a793f590",
      "title": "Jingle All the Way",
      "image_url": "https://cdn2.suno.ai/image_8ebdcf48-1d4d-4b8a-94bc-ec46a793f590.jpeg",
      "lyric": "[Verse]\nSnowflakes dancing in the street\nWarm cocoa can't be beat\nNeighbours laugh as carolers sing\nJoyful bells begin to ring\n[Verse 2]\nCandy canes and mistletoe\nSparkling lights that gleam and glow\nWrinkled paper ribbons flying\nSmiling faces never lying\n[Chorus]\nJingle all the way tonight\nStars above are shining bright\nGifts of laughter love and cheer\nMaking memories so dear\n[Verse 3]\nStockings hanging by the fire\nEvery heart is full of desire\nSilent wishes whispered low\nUnderneath the mistletoe\n[Bridge]\nChildren dreaming of delight\nSanta's sleigh takes flight tonight\nMagic sparkles in the air\nChristmas wonder everywhere\n[Verse 4]\nWrapping presents with a bow\nFeeling love in every show\nFamily gathered round the tree\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/8ebdcf48-1d4d-4b8a-94bc-ec46a793f590.mp3",
      "video_url": "https://cdn1.suno.ai/8ebdcf48-1d4d-4b8a-94bc-ec46a793f590.mp4",
      "created_at": "2025-01-04T03:26:59.710Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "pop",
      "duration": 203.8
    }
  ]
}

Finally, the song needs to be set to the singer's style, and then you need to enter the Suno Persona API to generate an ID parameter persona_id for a singer's style according to the official generated music ID audio_id. Specific parameters are shown in the picture below:

After completing the form, the code automatically generated is as follows:

Corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/persona"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "name": "Christmas",
    "audio_id": "8bc267d2-9794-412c-a504-974ce3cba254"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Click run, and you will find that the result is obtained as follows:

{
  "success": true,
  "task_id": "807dde07-ca91-4a51-ba45-d3b3f12f6a54",
  "data": {
    "persona_id": "194a0114-3705-4bd2-b975-abc20fec77f3"
  }
}

We use the above audio_id and persona_id as 8bc267d2-9794-412c-a504-974ce3cba254, 194a0114-3705-4bd2-b975-abc20fec77f3 as the sample data. Then you can set the parameter action to artist_consistency, and input the ID you need to continue generating songs and the singer style ID, fill in the sample as follows:

After filling it out, the code is automatically generated as follows:

Corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4",
    "custom": True,
    "audio_id": "8bc267d2-9794-412c-a504-974ce3cba254",
    "persona_id": "194a0114-3705-4bd2-b975-abc20fec77f3",
    "lyric": "[Verse]\\nSnowflakes dancing in the street\\nWarm cocoa can't be beat\\nNeighbours laugh as carolers sing\\nJoyful bells begin to ring\\n[Verse 2]\\nCandy canes and mistletoe\\nSparkling lights that gleam and glow\\nWrinkled paper ribbons flying\\nSmiling faces never lying\\n[Chorus]\\nJingle all the way tonight\\nStars above are shining bright\\nGifts of laughter love and cheer\\nMaking memories so dear\\n[Verse 3]\\nStockings hanging by the fire\\nEvery heart is full of desire\\nSilent wishes whispered low\\nUnderneath the mistletoe\\n[Bridge]\\nChildren dreaming of delight\\nSanta's sleigh takes flight tonight\\nMagic sparkles in the air\\nChristmas wonder everywhere\\n[Verse 4]\\nWrapping presents with a bow\\nFeeling love in every show\\nFamily gathered round the tree\\nHoliday spirit wild and free"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clicking run, you can see a result like this:

{
  "success": true,
  "task_id": "77fd7f95-9f75-4f5f-8c7a-4d78d284ef54",
  "trace_id": "f34b8b11-2839-48ea-b4e6-5525cb74d72f",
  "data": [
    {
      "id": "8b730866-dc0b-436e-aeee-d703a46c8187",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_8b730866-dc0b-436e-aeee-d703a46c8187.jpeg",
      "lyric": "[Verse]\\nSnowflakes dancing in the street\\nWarm cocoa can't be beat\\nNeighbours laugh as carolers sing\\nJoyful bells begin to ring\\n[Verse 2]\\nCandy canes and mistletoe\\nSparkling lights that gleam and glow\\nWrinkled paper ribbons flying\\nSmiling faces never lying\\n[Chorus]\\nJingle all the way tonight\\nStars above are shining bright\\nGifts of laughter love and cheer\\nMaking memories so dear\\n[Verse 3]\\nStockings hanging by the fire\\nEvery heart is full of desire\\nSilent wishes whispered low\\nUnderneath the mistletoe\\n[Bridge]\\nChildren dreaming of delight\\nSanta's sleigh takes flight tonight\\nMagic sparkles in the air\\nChristmas wonder everywhere\\n[Verse 4]\\nWrapping presents with a bow\\nFeeling love in every show\\nFamily gathered round the tree\\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/8b730866-dc0b-436e-aeee-d703a46c8187.mp3",
      "video_url": "https://cdn1.suno.ai/8b730866-dc0b-436e-aeee-d703a46c8187.mp4",
      "created_at": "2025-01-04T03:54:22.060Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 120.28
    },
    {
      "id": "13cff259-a8f2-4729-ba1b-3dc48e92f18a",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_13cff259-a8f2-4729-ba1b-3dc48e92f18a.jpeg",
      "lyric": "[Verse]\\nSnowflakes dancing in the street\\nWarm cocoa can't be beat\\nNeighbours laugh as carolers sing\\nJoyful bells begin to ring\\n[Verse 2]\\nCandy canes and mistletoe\\nSparkling lights that gleam and glow\\nWrinkled paper ribbons flying\\nSmiling faces never lying\\n[Chorus]\\nJingle all the way tonight\\nStars above are shining bright\\nGifts of laughter love and cheer\\nMaking memories so dear\\n[Verse 3]\\nStockings hanging by the fire\\nEvery heart is full of desire\\nSilent wishes whispered low\\nUnderneath the mistletoe\\n[Bridge]\\nChildren dreaming of delight\\nSanta's sleigh takes flight tonight\\nMagic sparkles in the air\\nChristmas wonder everywhere\\n[Verse 4]\\nWrapping presents with a bow\\nFeeling love in every show\\nFamily gathered round the tree\\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/13cff259-a8f2-4729-ba1b-3dc48e92f18a.mp3",
      "video_url": "https://cdn1.suno.ai/13cff259-a8f2-4729-ba1b-3dc48e92f18a.mp4",
      "created_at": "2025-01-04T03:54:22.060Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 120.44
    }
  ]
}

It can be seen that the result content is consistent with the above, which also achieves the function of generating songs using the singer's style.

Continue Generation Function

If you want to continue generating the already generated Suno song, you can set the parameter action to extend, and input the ID of the song you want to continue generating. The song ID is obtained based on basic usage, as shown in the image below:

At this time, you can see the song ID is:

"id": "b9e9fa11-0bf3-47cd-a3d7-85735aee3e07"

Note, the id in the lyrics here is the ID of the generated song. If you don't know how to generate a song, you can refer to the basic usage above to generate a song.

If you want to continue generating your uploaded song, you can set the parameter action to upload_extend, and input the ID of the custom uploaded song you want to continue generating. The song ID is obtained using the Suno Upload Generation API, as shown in the image below:

Next, we must fill in the lyrics and style to customize the song generation, and you can specify the following content:

lyric: Lyrics text
custom: Fill in true, representing custom generation, this parameter defaults to false, representing generation using prompt.
style: The style of the song, optional.
continue_at: Continue the existing audio time in seconds. For example, 213.5 means continuing to 3 minutes and 33.5 seconds.

Sample filling is as follows:

After filling it out, the code is automatically generated as follows:

The corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "audio_id": "b9e9fa11-0bf3-47cd-a3d7-85735aee3e07",
    "continue_at": 10,
    "style": "cute",
    "lyric": "la la la"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clicking run, you will find a result, as follows:

{
  "success": true,
  "task_id": "baf55c32-1207-4bdf-bd00-32a864f0474d",
  "data": [
    {
      "id": "5a3d0054-a6c5-43a9-a348-eae22d1f0efe",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_5a3d0054-a6c5-43a9-a348-eae22d1f0efe.jpeg",
      "lyric": "la la la",
      "audio_url": "https://cdn1.suno.ai/5a3d0054-a6c5-43a9-a348-eae22d1f0efe.mp3",
      "video_url": "https://cdn1.suno.ai/5a3d0054-a6c5-43a9-a348-eae22d1f0efe.mp4",
      "created_at": "2024-07-25T11:15:49.320Z",
      "model": "chirp-v3.5",
      "prompt": null,
      "style": "cute",
      "duration": 7.96
    },
    {
      "id": "9ae90c96-adcf-4aad-a591-361485168f13",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_9ae90c96-adcf-4aad-a591-361485168f13.jpeg",
      "lyric": "la la la",
      "audio_url": "https://cdn1.suno.ai/9ae90c96-adcf-4aad-a591-361485168f13.mp3",
      "video_url": "https://cdn1.suno.ai/9ae90c96-adcf-4aad-a591-361485168f13.mp4",
      "created_at": "2024-07-25T11:15:49.321Z",
      "model": "chirp-v3.5",
      "prompt": null,
      "style": "cute",
      "duration": 4.2
    }
  ]
}

It can be seen that the content of the result is consistent with the above, which also realizes the song continuation function.

Getting the Complete Song

When you continue to generate a song based on the existing song, the returned song does not contain the original song content. To get the complete song content, you need to use the concatenation feature, where you can specify the following:

action: content is concat.
audio_id: the ID of the last segment.

For example, if the extended song ID is: 0550d2ea-1e2e-4800-a163-60f172c0b51e, then you can set the parameters as follows:

{
  "action": "concat",
  "audio_id": "0550d2ea-1e2e-4800-a163-60f172c0b51e"
}

Other parameters remain unchanged, and the result returned is a complete song, which is the concatenation of all song segments, but the result is only one song, as below:

{
  "success": true,
  "data": [
    {
      "state": "succeeded",
      "id": "b7cc1054-4ecf-4fb3-a711-ec25f8878ac7",
      "title": "Piggy Dreams",
      "image_url": "https://cdn2.suno.ai/image_0550d2ea-1e2e-4800-a163-60f172c0b51e.jpeg",
      "lyric": "[Verse]\nSaw a pig with dreams today\nDancing in the mud and hay\nSnorting tunes in his own way\nLiving large in piggy sway\n\n[Verse 2]\nOinking songs from dawn to dusk\nRolling round in rustic musk\nDreaming big without no fuss\nPiggy life’s a simple trust\n\n[Chorus]\nPiggy dreams you can’t suppress\nDancing round in muddy dress\nLiving life without the stress\nIn their world they’re truly blessed\n\n[Verse 3]\nApple cores and pumpkin pie\nPigs don’t need a reason why\nEvery day just to defy\nAny doubt that they can\"t fly\n\n[Bridge]\nThrough the fields they trotter free\nUnderneath the apple tree\nDreamin\" of what they could be\nPiggy dreams wild and carefree\n\n[Chorus]\nPiggy dreams you can’t suppress\nDancing round in muddy dress\nLiving life without the stress\nIn their world they’re truly blessed",
      "audio_url": "https://cdn1.suno.ai/b7cc1054-4ecf-4fb3-a711-ec25f8878ac7.mp3",
      "video_url": "https://cdn1.suno.ai/b7cc1054-4ecf-4fb3-a711-ec25f8878ac7.mp4",
      "created_at": "2024-12-08T15:50:00.105Z",
      "model": null,
      "prompt": null,
      "style": null,
      "duration": 259
    }
  ],
  "task_id": "394f3ff7-d952-4dbc-901e-9248d4d5ecf5"
}

Music Remake

When you continue to generate a song based on the existing one, the style of the returned song may not be quite suitable. If you want to remake the previously generated song (this also supports custom uploaded music), you need to use the music remake method, where you can specify the following:

action: content is cover, when performing a remake operation on custom uploaded music the content must be specified as: upload_cover.
audio_id: the ID of the previously generated song.

For instance, if the previously generated song ID is: e0347cce-97f7-4a1c-84c4-d59246428241, then you can set the parameters as follows:

{
  "action": "cover",
  "lyric":"girl girl girl",
  "style": "rock, punk",
  "model": "chirp-v4-tau",
  "audio_id": "e0347cce-97f7-4a1c-84c4-d59246428241"
}

Other parameters remain the same, and the result returned is a remade version of the song, which is the result of the original song being remade, as shown below:

{
    "success": true,
    "task_id": "87d0de46-8976-4e26-a28d-4d83211f8e26",
    "trace_id": "b0375262-5c96-4b13-b80a-df5dc5f16ad2",
    "data": [
        {
            "id": "d1df73a1-38f3-4405-bbdc-f0a433c19dc7",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_d1df73a1-38f3-4405-bbdc-f0a433c19dc7.jpeg",
            "lyric": "girl girl girl",
            "audio_url": "https://cdn1.suno.ai/d1df73a1-38f3-4405-bbdc-f0a433c19dc7.mp3",
            "video_url": "https://cdn1.suno.ai/d1df73a1-38f3-4405-bbdc-f0a433c19dc7.mp4",
            "created_at": "2024-12-22T03:50:50.822Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "rock, punk",
            "duration": 161.68
        },
        {
            "id": "2c45f5ba-6af7-40a6-b62f-9ced54548b12",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_2c45f5ba-6af7-40a6-b62f-9ced54548b12.jpeg",
            "lyric": "girl girl girl",
            "audio_url": "https://cdn1.suno.ai/2c45f5ba-6af7-40a6-b62f-9ced54548b12.mp3",
            "video_url": "https://cdn1.suno.ai/2c45f5ba-6af7-40a6-b62f-9ced54548b12.mp4",
            "created_at": "2024-12-22T03:50:50.822Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "rock, punk",
            "duration": 170.28
        }
    ]
}

The generated result is similar to the above, completing the process of creating a cover version of the originally generated song.

Replace Section

When a song is generated and you need to perform a separate operation of replacing a song section for secondary creation, you can replace a specific section of the song. You can specify the following content:

action: Content is replace_section.
audio_id: The ID of the previously generated song.
model: Song generation model,
lyric: The complete lyrics after replacement (only needs to have overlap with the prompt, not the full lyrics),
prompt: The part of the lyrics that needs to be replaced.
style: The style of the song, optional.
replace_section_start: The start time of the lyric on the lyrics timeline.
replace_section_end: The end time of the lyric on the lyrics timeline.

For example, if the ID of the originally generated song is: ade7241b-0357-4a5e-9b3d-4ec4f4b3a0c0, you can set the parameters as follows:

{
  "action": "replace_section",
  "lyric": "[Chorus]\nHappy New Year Everyone sings joyfully\nBlessings spread to every corner\nHappy New Year Many fireworks in the heart\nWishes come true, life is like golden waves\n[Verse 2]\nPlum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth",
  "prompt": "Plum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth",
  "replace_section_start": 28.94100580270793,
  "replace_section_end": 85.39410058027079,
  "model": "chirp-v4",
  "audio_id": "ade7241b-0357-4a5e-9b3d-4ec4f4b3a0c0",
  "custom": false,
  "instrumental": false
}

Other parameters remain unchanged, and the returned result is a song with the replaced section, which is the result after replacing a section of the originally generated song, as shown in the example below:

{
    "success": true,
    "task_id": "7a37c35d-7081-413d-908d-ab2d3f8139bf",
    "trace_id": "1ed92d6e-9a19-48f7-ab34-68c82c792303",
    "data": [
        {
            "id": "2a1467dc-51a4-4872-9ccc-ccd96e4fbbb6",
            "title": "Happy New Year",
            "image_url": "https://cdn2.suno.ai/image_dc1b5edc-fbae-44a3-8962-d596dbd2b0d7.jpeg",
            "lyric": "[Chorus]\nHappy New Year Everyone sings joyfully\nBlessings spread to every corner\nHappy New Year Many fireworks in the heart\nWishes come true, life is like golden waves\n[Verse 2]\nPlum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth",
            "audio_url": "https://cdn1.suno.ai/2a1467dc-51a4-4872-9ccc-ccd96e4fbbb6.mp3",
            "video_url": "",
            "created_at": "2025-04-18T01:55:02.930Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "traditional influences, female vocals",
            "duration": 202.52,
            "concat_history": [
                {
                    "id": "ade7241b-0357-4a5e-9b3d-4ec4f4b3a0c0",
                    "type": "gen",
                    "source": "ios",
                    "infill_start_s": 28.94100580270793,
                    "infill_end_s": 85.39410058027079,
                    "infill_dur_s": 56.45309477756285,
                    "infill_context_start_s": 0,
                    "infill_context_end_s": 115.39410058027079,
                    "include_future_s": 2,
                    "include_history_s": 2,
                    "infill": true,
                    "infill_lyrics": "Plum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth"
                },
                {
                    "id": "dc1b5edc-fbae-44a3-8962-d596dbd2b0d7"
                }
            ]
        }
    ]
}

The generated result is similar to the above, completing the process of replacing a section of the originally generated song.

Vocal and Instrumental Separation

When a song is generated and you need to perform separate operations for accompaniment and vocals for secondary creation, you can separate pure music accompaniment and a cappella vocals. You can specify the following content:

action: Content is stems.
audio_id: The ID of the previously generated song.

For example, if the ID of the originally generated song is: ec13e502-d043-4eb2-92ee-e900c6da69d1, you can set the parameters as follows:

{
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}

Other parameters remain unchanged, and the output is simply a revamped version of the song—it's the result of remixing the originally generated song. Sample:

{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "Deck the Sky - Vocals",
      "image_url": "https://cdn2.suno.ai/image_e3de0928-085a-42c4-b982-3b24738d1989.jpeg",
      "lyric": "[Verse]\nSnowflakes dance on rooftops high\nChildren's laughter fills the sky\nCarols ring from church bells loud\nHolidays a joyful crowd\n[Verse 2]\nCandy canes and cocoa warm\nWrapped up tight in our own storm\nStockings hung with dreams and cheer\nMagic growing every year\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright\n[Verse 3]\nFireside tales of long ago\nReindeer prance in icy glow\nEvergreen and tinsel’s gleam\nChristmas time a lovely dream\n[Bridge]\nHearts are full with friends and kin\nMistletoe for love to win\nGifts of love and hope we share\nChristmas spirit everywhere\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright",
      "audio_url": "https://cdn1.suno.ai/e3de0928-085a-42c4-b982-3b24738d1989.mp3",
      "video_url": "https://cdn1.suno.ai/e3de0928-085a-42c4-b982-3b24738d1989.mp4",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "Deck the Sky - Instrumental",
      "image_url": "https://cdn2.suno.ai/image_ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb.jpeg",
      "lyric": "",
      "audio_url": "https://cdn1.suno.ai/ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb.mp3",
      "video_url": "https://cdn1.suno.ai/ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb.mp4",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    }
  ]
}

The generated result is similar to the text above, completing the process of sound and track separation for the originally created song.

Asynchronous Callback

Since Suno's music generation takes relatively a longer time, around 1-2 minutes, if the API doesn't respond for a long time, the HTTP request remains connected, leading to extra consumption of system resources. Therefore, this API also provides asynchronous callback support.

The overall flow is: when the client makes a request, it additionally specifies a callback_url field. After the client initiates an API request, the API immediately returns a result containing a task_id field, representing the current task ID. Once the task is complete, the generated music result will be sent to the client-specified callback_url in POST JSON format, which also includes the task_id field, allowing the task result to be linked through the ID.

Below is an example to illustrate how to operate.

First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes here, we use a public Webhook sample at https://webhook.site/. Visiting this site provides a Webhook URL, as shown below:

Copy this URL, and it can be used as a Webhook. In this example, it's https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2.

Next, we can set the field callback_url to the Webhook URL above and fill in prompt, as shown below:

Click run, and we can immediately get a result like this:

{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}

After waiting for a moment, we can observe the generated song result at https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2, as shown:

The content is as follows:

{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn1.suno.ai/image_da4324e5-84b2-484b-b0e9-dd261381c594.png",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn1.suno.ai/da4324e5-84b2-484b-b0e9-dd261381c594.mp3",
      "video_url": "https://cdn1.suno.ai/da4324e5-84b2-484b-b0e9-dd261381c594.mp4",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn1.suno.ai/image_b878a87b-a0db-4046-8ccd-ecd2fb3d4372.png",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn1.suno.ai/b878a87b-a0db-4046-8ccd-ecd2fb3d4372.mp3",
      "video_url": "https://cdn1.suno.ai/b878a87b-a0db-4046-8ccd-ecd2fb3d4372.mp4",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}

You can see that the result contains a task_id field, and other fields are similar to the above text, through which the task can be associated.

Error Handling

If an error occurs, you will receive an error message similar to the following:

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Song Description contained artist name: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}

Below is a list of HTTP Status Code, error.code, error.message:

Status Code	`error.code`	`error.message`
400	`bad_request`	`instrumental must be a boolean`
400	`bad_request`	`style must be less than or equal 120`
400	`bad_request`	`custom must be a boolean`
400	`bad_request`	`audio_id is required when extend audio`
400	`bad_request`	`continue_at is required when extend audio`
400	`bad_request`	`continue_at must be a number greater than 0`
400	`bad_request`	`lyric is required when extend audio and instrumental is false`
400	`bad_request`	`prompt is required when generate audio`
400	`bad_request`	`lyric is required when generate custom audio`
403	`forbidden`	`Prompt likely malformed`
403	`forbidden`	`Prompt likely copyrighted`
403	`forbidden`	`Prompt contained inappropriate material`
403	`forbidden`	`Song Description flagged for moderation`
403	`forbidden`	`Song Description contained artist name`
403	`forbidden`	`Song Description contained producer tag`
500	`api_error`	`Unable to generate lyrics from song description`
500	`api_error`	`job failed with unknown error`
500	`api_error`	`no available worker in system`
500	`api_error`	`service under maintenance, generation paused`
504	`timeout`	`timeout while waiting for audio generation`

Midjourney Imagine API Application and Usage

hongyu — Mon, 21 Apr 2025 09:16:40 +0000

Midjourney is a very powerful AI drawing tool that can generate exquisite images in just one or two minutes by inputting keywords. Midjourney stands out in the industry for its outstanding drawing capabilities and has been widely used across various industries and fields, with its influence becoming increasingly significant.

This document mainly introduces the usage process of the Imagine operation in the Midjourney API, enabling us to easily generate the required images through text.

Application Process

To use the Midjourney Imagine API, first visit the Midjourney Imagine API page and click the "Acquire" button to obtain the credentials needed for the request:

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page.

When applying for the first time, there will be a free quota provided, allowing you to use the API for free.

Basic Usage

Next, you can fill in the corresponding content on the interface, as shown in the image:

When using the interface for the first time, we need to fill in at least two pieces of content: one is authorization, which you can select directly from the dropdown list. The other parameter is prompt, which is the description of the image we want to generate. It is recommended to use English descriptions for more accurate results. Here we used the example content Lamborghini speeds inside a volcano, which means we want to draw a Lamborghini speeding inside a volcano.

You can also notice that there is a corresponding code generation on the right side. You can copy the code to run it directly or simply click the "Try" button for testing.

After calling, we find the returned result as follows:

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234197197067915365/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_f47263b6-ff92-44a3-88ee-51cf0e706aae.png?ex=662fdb36&is=662e89b6&hm=ca9be54907726937ed02517a13466bef2afb2825b7cda4b313de56a3c3310d0d&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234197197067915365",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234197197067915365/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_f47263b6-ff92-44a3-88ee-51cf0e706aae.png?ex=662fdb36&is=662e89b6&hm=ca9be54907726937ed02517a13466bef2afb2825b7cda4b313de56a3c3310d0d&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "1bae3bec-3ac4-4180-a148-74ee6cb68b98",
  "success": true
}

The returned result contains multiple fields, as described below:

task_id: The ID of the task for generating this image, used to uniquely identify the image generation task.
image_id: The unique identifier for the image, which needs to be passed for transformation operations on the image next time.
image_url: The URL of the thumbnail, which can be opened directly to view the generated effect.
image_width: The pixel width of the thumbnail.
image_height: The pixel height of the thumbnail.
raw_image_url: The URL of the original image, which is the same as the thumbnail content but has higher resolution, and the loading speed may be slower.
raw_image_width: The pixel width of the original image.
raw_image_height: The pixel height of the original image.
actions: A list of further operations that can be performed on the generated image. Here, a total of 8 options are listed, where upscale represents enlargement, and variation represents transformation. Therefore, upscale1 represents the enlargement operation on the top-left first image, and variation3 indicates transformation based on the bottom-left third image.

Opening the link corresponding to image_url or raw_image_url shows the image as illustrated.

It can be seen that a 2x2 preview image has been generated here. Up to now, the first API call has been completed.

Image Enlargement and Transformation

Next, we will attempt to perform further operations on the currently generated photo. For example, if we find the second image in the upper right corner quite satisfactory but want to make some transformations, we can set the action to variation2 and pass the image_id accordingly:

The result obtained at this time is as follows:

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234201336543969401/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_10dc56a7-ec16-4bac-878e-2338f2ae5f5d.png?ex=662fdf10&is=662e8d90&hm=9aec96bca35ae20b6f9ab536101b9c4ea255eb6216cbf7000ac554937da071f3&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234201336543969401",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234201336543969401/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_10dc56a7-ec16-4bac-878e-2338f2ae5f5d.png?ex=662fdf10&is=662e8d90&hm=9aec96bca35ae20b6f9ab536101b9c4ea255eb6216cbf7000ac554937da071f3&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "f4961620-1104-409f-9dc1-ba3ed15c2f4d",
  "success": true
}

Open image_url, the newly generated image is shown below:

As you can see, for the last image in the top right corner, we have once again obtained four similar photos.

At this point, we can select one for detailed upscale operation, for example, if we choose the fourth one, we can pass action as upscale4 and then pass the current image's ID via image_id again.

Note: The upscale operation will take less time compared to variation in Midjourney.

The return result is as follows:

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234202545208033400/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_34edc3f5-2bd0-4f5b-a372-03270b02289b.png?ex=662fe031&is=662e8eb1&hm=f8006c4d33a03dfd027dffe4eb46ab0d113a4910aef07497f0b335c8998b7858&width=512&height=512",
  "image_width": 512,
  "image_height": 512,
  "image_id": "1234202545208033400",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234202545208033400/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_34edc3f5-2bd0-4f5b-a372-03270b02289b.png?ex=662fe031&is=662e8eb1&hm=f8006c4d33a03dfd027dffe4eb46ab0d113a4910aef07497f0b335c8998b7858&",
  "raw_image_width": 1024,
  "raw_image_height": 1024,
  "progress": 100,
  "actions": [
    "upscale_2x",
    "upscale_4x",
    "variation_subtle",
    "variation_strong",
    "zoom_out_2x",
    "zoom_out_1_5x",
    "pan_left",
    "pan_right",
    "pan_up",
    "pan_down"
  ],
  "task_id": "03f62b17-a6f1-4c8e-9b4d-1fc7bd5b1180",
  "success": true
}

Among them, image_url is shown as follows:

Thus, we successfully obtained a photo of a Lamborghini.

At the same time, note that the actions include several operations that can be performed, as described below:

upscale_2x: Upscale the image by 2 times, obtaining a 2x high-definition image.
upscale_4x: Upscale the image by 4 times, obtaining a 4x high-definition image.
zoom_out_2x: Perform a zoom out operation of two times (filling in the surrounding area).
zoom_out_1_5x: Perform a zoom out operation of 1.5 times (filling in the surrounding area).
pan_left: Perform a left panning operation on the image.
pan_right: Perform a right panning operation on the image.
pan_up: Perform an upward panning operation on the image.
pan_down: Perform a downward panning operation on the image.

You can continue to input the corresponding transformation instructions according to the above process for continuous image generation operations.

Image Rewrite (Base Image)

This API also supports image rewriting, commonly known as base image. We can input an image URL and the description text to be rewritten, and this API will return the rewritten image.

Note: The input image URL must be a pure image, not an image displayed within a webpage; otherwise, it cannot be rewritten. It is advisable to use an image hosting service to upload and obtain the image URL.

For example, we have an image of a sunset on a road, with some trees and buildings beside the road, as shown below:

Now we want to rewrite it to a beach scene with a car parked on the side of the road. We can construct the following prompt:

https://cdn.acedata.cloud/v014oc.png an illustration of a car parked on the beach --iw 2

As you can see, the beginning of our prompt is an HTTPS-starting image link, followed by a space and then the content of the prompt text. Here we also used some additional advanced parameters, such as —iw 2 to adjust the image weight.

We can send the above content as a whole to the prompt field, as shown below:

The output result is as follows:

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234427310434947145/1234539663515975690/atmateosa5693_An_illustration_of_a_car_parked_on_the_beach_id26_cc8650ec-7e4b-4685-8911-78172430d8a7.png?ex=66311a28&is=662fc8a8&hm=c39707a1f22bc7f12874060ea6ed58ba37c188139ccc9a13c61ed9f37e66ea74&width=1456&height=816",
  "image_width": 1456,
  "image_height": 816,
  "image_id": "1234539663515975690",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234427310434947145/1234539663515975690/atmateosa5693_An_illustration_of_a_car_parked_on_the_beach_id26_cc8650ec-7e4b-4685-8911-78172430d8a7.png?ex=66311a28&is=662fc8a8&hm=c39707a1f22bc7f12874060ea6ed58ba37c188139ccc9a13c61ed9f37e66ea74&",
  "raw_image_width": 2912,
  "raw_image_height": 1632,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "24a79e8b-a79d-471a-aef7-089dc0627ee8",
  "success": true
}

At this point, we have obtained the following generated image:

As you can see, with the overall style and composition of the original image remaining unchanged, the entire scene has been transformed into a beach scene, and a car has appeared on the road. This is Prompt with Image.

Image Fusion

This API also supports image fusion, allowing us to pass in multiple images to achieve different image fusion effects.

For example, here we have two images: one is a teddy bear, and the other is a chainsaw, shown below:

Now we want to combine the two, making the bear hold the chainsaw. How do we do that?

We can construct the following prompt:

https://cdn.acedata.cloud/8fapzl.png https://cdn.acedata.cloud/c1igbw.png The bear is holding the chainsaw --iw 2

It can be seen that similar to Image with Prompt, we place multiple image URLs at the beginning of the prompt, separated by spaces, and then add the text prompt at the end, passing the above content as a whole to the prompt parameter. The effect of running it is as follows:

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234547236830973972/kcisok_The_bear_is_holding_the_chainsaw_id8873344_ad605bc4-ba19-4807-b94f-367dab672f7a.png?ex=66312136&is=662fcfb6&hm=0fb1e2261c9a30b04de9da9b23b7562eb73677f1bbda1fae52c7243b12d25aac&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234547236830973972",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234547236830973972/kcisok_The_bear_is_holding_the_chainsaw_id8873344_ad605bc4-ba19-4807-b94f-367dab672f7a.png?ex=66312136&is=662fcfb6&hm=0fb1e2261c9a30b04de9da9b23b7562eb73677f1bbda1fae52c7243b12d25aac&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "891f2645-ee15-4c7b-ac24-d98163c8e57e",
  "success": true
}

We have obtained the following result:

It can be seen that we have successfully achieved image fusion.

Note: Image fusion can support up to 5 image URLs as input, meaning it can support fusing up to 5 images, with the input format as above.

Local Transformation

This API also supports the localized drawing function for images, but it only supports generating images based on the content mentioned above. We can pass in a unique ID for the generated image, the action parameter for local redrawing action, and the mask for the area to be redrawn, in order to achieve redrawing in the masked area.

For example, here we have a generated image of a cat:

Now we want to redraw the cat's face. How do we do that?

First, we need to obtain the mask for that area. This mask is obtained through a grayscale image encoded in Base64. Below is some code to get the mask:

Example Python code to obtain the mask:

import sys
import os
from PySide6.QtWidgets import *
from PySide6.QtGui import QPainter, QMouseEvent, QPen, QColor, QImage
from PySide6.QtCore import Qt, QPoint

class DrawingWidget(QWidget):
    def __init__(self, imagePath):
        super().__init__()
        self.setAttribute(Qt.WA_StaticContents)
        self.background_image = QImage(imagePath)
        imageSize = self.background_image.size()*0.8
        self.setFixedSize(imageSize)
        self.foreground_image = QImage(self.size(), QImage.Format_ARGB32)
        self.foreground_image.fill(Qt.transparent)
        self.drawing = False
        self.lastPoint = QPoint()
        self.pen_color = QColor(255, 255, 255, 255)
        self.pen_size = 50

    def set_pen_size(self, size):
        self.pen_size = size

    def mousePressEvent(self, event: QMouseEvent):
        if event.button() == Qt.LeftButton:
            self.drawing = True
            self.lastPoint = event.pos()

    def mouseMoveEvent(self, event: QMouseEvent):
        if event.buttons() & Qt.LeftButton and self.drawing:
            painter = QPainter(self.foreground_image)
            painter.setRenderHint(QPainter.Antialiasing, True)
            pen = QPen(self.pen_color, self.pen_size,
                       Qt.SolidLine, Qt.RoundCap, Qt.RoundJoin)
            painter.setPen(pen)
            painter.drawLine(self.lastPoint, event.pos())
            self.lastPoint = event.pos()
            self.update()

    def mouseReleaseEvent(self, event: QMouseEvent):
        if event.button() == Qt.LeftButton and self.drawing:
            self.drawing = False

    def paintEvent(self, event):
        canvasPainter = QPainter(self)
        canvasPainter.drawImage(
            self.rect(), self.background_image, self.background_image.rect())
        canvasPainter.drawImage(
            self.rect(), self.foreground_image, self.foreground_image.rect())

    def save_image(self, path):
        self.foreground_image.save(path)

class MainWindow(QDialog):
    def __init__(self, imagePath):
        super().__init__()
        self.setWindowTitle("mask tool")
        self.drawing_widget = DrawingWidget(imagePath)
        self.currentPath = os.getcwd().replace("\\", "/")
        self.tempPath = self.currentPath + "/temp.jpg"
        self.projectPath = ""
        self.setDone = False

    def init_ui(self):
        layout = QVBoxLayout()
        layout.addWidget(self.drawing_widget)
        controls_layout = QHBoxLayout()
        size_label = QLabel("pen size:")
        controls_layout.addWidget(size_label)
        self.size_slider = QSlider(Qt.Horizontal)
        self.size_slider.setMinimum(100)
        self.size_slider.setMaximum(400)
        self.size_slider.setValue(400)
        self.size_slider.valueChanged.connect(self.update_pen_size)
        controls_layout.addWidget(self.size_slider)
        self.lineEdit_addPromp = QLineEdit()
        layout.addWidget(self.lineEdit_addPromp)
        save_button = QPushButton("   Start partial redrawing   ")
        save_button.clicked.connect(self.save_image)
        controls_layout.addWidget(save_button)
        dont_button = QPushButton("   Cancel partial redraw   ")
        dont_button.clicked.connect(self.dont_image)
        controls_layout.addWidget(dont_button)
        layout.addLayout(controls_layout)
        self.setLayout(layout)

    def update_pen_size(self):
        size = self.size_slider.value()
        self.drawing_widget.set_pen_size(size)

    def save_image(self):
        tempImage = self.currentPath + "/temp.jpg"
        self.drawing_widget.save_image(self.tempPath)
        self.prompt = self.lineEdit_addPromp.text()
        self.setDone = True
        self.close()

    def dont_image(self):
        self.setDone = False
        self.close()

    def closeEvent(self, event):
        if self.setDone:
            pass
        else:
            self.setDone = False
        event.accept()

if __name__ == '__main__':
    imagePath = "test.png"
    app = QApplication(sys.argv)
    mainWindow = MainWindow(imagePath)
    mainWindow.init_ui()
    mainWindow.exec()

By using the above code, a mask image can be obtained. During this process, we need to ensure that the mask image is the same size as the original image. The white area in the mask image indicates the area to be redrawn. Below is a comparison of the mask image for the cat that needs to be redrawn with the original image:

Original image:

Mask image:

Finally, we also need to convert the mask image to Base64 encoding. Below is the code for converting to Base64 encoding:

import cv2
import base64

image_path = 'temp.jpg'
gray_image = cv2.imread(image_path)
_, buffer = cv2.imencode('.jpg', gray_image)
base64_encoded = base64.b64encode(buffer).decode('utf-8')
with open('grayscale_image_base64.txt', 'w') as f:
    f.write(base64_encoded)

print("success!")

Note: The above Python code describes the process of generating a mask. If you want to integrate it into your product, please write the corresponding language code based on its principles.

With the above code, we obtained the mask mask that needs to be redrawn. Next, we also need to set the parameter action to variation_region, generate the image ID image_id (reference this parameter based on the content above), and pass the corresponding mask mask. Other parameter information is as follows:

action: The behavior for manipulating the image; here it is variation_region, indicating partial redrawing of the image.
prompt: Description words for partial redrawing of the image (optional parameter).
image_id: Unique identification of the image, facilitating partial redrawing.
mask: Base64 encoding of the corresponding mask area of the image (the image specified by the above image_id).

Therefore, based on the above rules, we need to set the correct parameters. The parameter prompt is a non-mandatory parameter; for convenience in comparison, the prompt for the mask area is set to A cute cat. The specific parameter settings are shown in the figure below:

Code Example

It can be observed that various language codes have been automatically generated on the right side of the page, as shown in the figure:

Some code examples are shown below:

Response Example

After a successful request, the API will return the image results after face swapping. For example:

{
  "image_url": "https://platform.cdn.acedata.cloud/midjourney/6c9450d8-1c22-4f85-a527-e7a7bfb4a61b.png?imageMogr2/thumbnail/!50p",
  "image_width": 1024,
  "image_height": 1024,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "raw_image_url": "https://platform.cdn.acedata.cloud/midjourney/6c9450d8-1c22-4f85-a527-e7a7bfb4a61b.png",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "image_id": "1265876571323891712",
  "task_id": "6c9450d8-1c22-4f85-a527-e7a7bfb4a61b",
  "success": true
}

It can be seen that this is a redrawing operation of the image in the mask area, and the returned result is consistent with the above-mentioned content, as shown in the figure below:

As can be seen, we have successfully achieved partial redrawing of the generated image in a custom area.

CURL

curl -X POST 'https://api.acedata.cloud/midjourney/imagine' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cute cat",
  "action": "variation_region",
  "image_id": "1265875488702726144",
  "mask": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCAGaAZoDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD+f+iiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKA//Z"
}'

Python

import requests 

url = "https://api.acedata.cloud/midjourney/imagine" 

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
} 

payload =
{
    "prompt": "A cute cat ",
    "action": "variation_region",
    "image_id": "1265875488702726144",
    "mask": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCAGaAZoDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD+f+iiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiv12/4Jcf8GoX7XX7X+nab8af2y9Tvfgt4GmvZYZPDOpaHIni7VIYbmGOTFncxxx6dHLH9pEdzceZKJIY5PsssUschAPyJor+tT4X/wDBqr/wRb8B+AbLwf4i/Z51/wAb6naCaOfxP4n8f6ol9fb5ZHAmj0+5tbVfLB8oeVDHxHk5kzIen/4hdP8Aghd/0Y1/5kzxP/8ALSgD+QSiv3u/b4/4Myb/AMOeFZPF/wDwTc+POoa9d6fYO9z4F+KU9rHdajLFHcyZtdStYoohLL/osMVtNDFECZJZbuMYjr8Ufj/8Bfi3+yx8YvEPwD/aD+H1/wCF/GPhfUjaa1oN9jzbV8Eg5GY5Y5I/LkjljJjlikjkjLxuDQB5/RRRQAUUUUAFFfrt+wH/AMGi37dP7U3hGL4hftS+MdP+BGj32nCbSdP1fSTq+u3JeO2liaSxjnhjtIjHLKCJrhLqKW2MclqAfMH6Ef8AEFh/wSy/6L78ff8AwqdC/wDlNQB/MDRX9Mviz/gy0/4JzXfhvUtO8D/tFfG3TtafT5o9Kv8AVdX0e9tbe5MZEM0tvHp8LzRiTJMQliLhcCSMkGvzQ/4Kdf8ABsN+3V/wT18M618bfh3e6b8YfhdoWny3us+JvD9l9i1LSbaOK3Es15pksskgiEksh320t0I4rWWaX7MOAAfmTRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQB+5/wDwaS/8EgIPij4sb/gqR+0F4N0288OeHtUm0/4VaDrej3LGbWIpI/N16JpCsMkdsfMtoT++H2rzpP3MtjEZP6La8i/Yj/Zf8PfsafsmfD39lPwm+nyWngTwtY6VPe6dpEenR6hcxwr9pvvs8RIikubnzbqUb5CZZ5CZJDkn12gAooooAK+RP+Cvv/BLP4P/APBU79krV/g34w8N2K+OtHsbu8+FHiy4mMEuh6y0f7rzJkhlk+wzSpHHdReXKHixIB5sUMsX13RQB/CH8f8A4C/Fv9lj4xeIfgH+0H8Pr/wv4x8L6kbTWtBvsebavgkHIzHLHJH5ckcsZMcsUkckZeNwa8/r+yL/AIK2f8EQP2Vv+CuXhew1H4pvqXhX4g+HNPubTwt8QvDyRfaYYpI5fKtb2OQf6fYx3MnneSTFKCJBFND50xl/CD9n3/g09/4Kk/Fn9onW/hL8TfDeg+AvCvhfWzp+r/ErWL8zWWpQg2shm0m2ixc3++2uTLF5kdvCTDLbSzW1xHJFGAfl5X9NH/BrF/wRq8Lfs3fAjRv+CiH7RHgPTLn4m+P9L+2/Dq4fUo7z/hHfDF1bxGGaOMR+XDe3Uck3mSeZJJHayQw/uTLdxH6N/wCCbP8Awbkf8E5f+Cdn9k+Po/AX/Cz/AImae0M7ePvHlnHcfYbyL7LIZdOsv+Paw8u6tvOilxLdw+bJH9qkFfoPQAUUUUAFFFFAH8+v/B2R/wAEZvDHgPS5/wDgqd+y/wCAtN0m0mv8fHOxtdQjt0e6urmKOy1mK28sZkluZjDdGOTMksttN5OftU1fgbX953xe+FPgf41fCnxN8GPiZoDaj4b8X6FfaN4g04XkkX2uxuonhuIvMiIkTzI5HH7sgjsRX8fP/BaP/glR48/4JR/tj6r8G/J8Qah8OtaIv/hh431u0iQazYeXEZYTJD+7NzayyC2lGIj/AKqbyoormIUAfG9FFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAfpP/AMG73/BaG3/4Jd/tCXnw4+PHiPXpvgh47UJ4isbJ/Pg8Pap+5EWvJbeWZJPLjjMU0duY5JYmEmLmS1toT/VR8I/i58MPjn4Asfij8G/iVoPi/wAN6o039n+IfDOrxahYXRimkil8m5hJilEcsckeQTzI5UjNcGJw+HX7bc1Lk86BNcKz1H9Gm7bmHBIX9kUsxtEkz1TpRUkBqHnUr4gmbHH9pk4v1xPJKmOlOu7WiuJlxZ6H6GlBrvBygjFSZlfYIJdB6YY1OwW3AWtLe3hUk09+b+BOm8Hv8H60bPI4fJh/KBcUfDPPrY3bKpKtG9uLJ6VDceText/iBB7JiYEkGJI4eEgnHIFcs8jPTEe4odwY0fHW6cX8/Xx+45GFl1IeSJE5Hh+HJvA+q7HxaDwvF03mvxgfdH+V8U2dMflhAsufPPf8h15/wDgsi8Vc5uHRUibr3HeXywWcNjKe3qz1aJhff7f9l+K3g27nxToNFJpb6nATEaHIkj3Loe/iODckAWx7ikokg7Ym/s7ID5Y71J/rGpK8Rn/jzT/al4Efo2uPfx+/wv2T5VIn4sR8T9DsNBk1NKgpRHginU4Od7iY59Ol7v3MNbfL/wC0Un4PtxfjtG+k7ZL98FAVV8t3Dwv0a8/wDA/IYXhzDB2llIdncV29Rzg+RpDGeZOv1VYm8adUwx1U8MrCMh/mMAAAAAABX5yZtuwQhG1GH1x6uxbLlg1h0j3ieEycEExSIdw5vDKAQAAAAAwqj4c8bcylIwpaZHVjKwTgItRklgAs1JZSd2cUSI/AwAAAAB6WqnPyCjsr4dlZk3hDK9So1czJXkh9TJNerL1dolMclrccscZIkkgIvKeCM8QlLU/2WbvcgfjQmE753GI9OnLgokyCQAAAAwGzH4S5S3RUw/e3w3/reE74p89QXDhWIylTtSvZoW1ZitaVpUNPftLsD4rVGUkG/8At9B5V4clKNB498coWCDVjbL1/pY0yM0eYJt0R0p/fgMmBM0qxuleYsn/AiLAE9L8q8myRZ9S/4DjsUlSvuim+3dd6kSYBJGeZJh2VMG7qmZT40kOBmpKCOI7c5UVIdSxlR8qPUCqW9g1cDv5vENQLGLuPS43/rPD9e7ffrNfRefoG4kvF1XH+LNnsHhzL3YnAYzpzZWCe20iMRkU2/dVUm4u2zHu8zI4hweOqgl7R0dUHgZWrgX3gbfWf+Lqbw8iJetq1HneUcCMswV4Ke0n4mcJVEimJo9Eq5oB5IgAk9Z9UibfyJZZy/r5o7KvPZ7IHGwnFeA7PcA0w1RtKZywPW07OFHuEZMLQrvHrNTGWW6/iLRbiH96yHJsOY4Wcd1nAWzyXtoZgr5/mq7VgAAAAAAkH9h9e9/ywvr1PgY67h92IvcFVK9ULGHVS/mgBp7Vvv+H7Av8RfgtN5ODzz97+C3Qeq0EGzzElEA63B+FJXnMCf+Yc1e5AcsGAS6lA/88AwiRhqqZjGZG+pDkt5D5nU8PCD0fQtScActwzS0+50A+3GYerOdQbIu30VgPgM0FHz3vlGvB2Eu9BteDbNEHo91jd9NNSqkGVL0A0twUtNnlFRHDp2+Hp3xzjP/SwyDnpT5D9UCAAAAAAAABM+d+nLy8Pyh8KkZOlVFnYwvJfTxfFV5YVQ6ePq0yFErWDlRdM5t+4xajjhy1vGZnURueJBmfB/2yzsvmbwz20Yv/YtHBeVcGnhBTjje3ID/Sp8epj0RFvd+/en/QdPYwr0+8cUzWsewm9Utk8wNedWhoP8g9Wct6Dur14Yzbb0zbxWy+5W4fzsCq3MmxpzJskhu2HxeEf8A9zjBNBE5ltYshExMccXR7kFP9FhfxIejUsZFFW2XeNyN5FZzQY417mx0yH1m3/1QegAIAAAAAAAAAB57n0FFya2LZevnFD15mTpKBnk+HEM9HqqA/cVwERNGqSSJaPMETzRsqrMchTd8c0WF25BHaKT+1VW3to4awe5oobNtv2yGlZHZPI15+r5+Jh4Ak8UoKH5-gdHgQW10+iwr/hFL3eS4m06UhiMIgyU2jyH/ORendWf//ZpHd53ylS+awKkTheOc82+b8Kt4keYbRGx9mOwm43q2heVBjbXF6pAPuSBqg+OWarH/+y1qwf8/8Ab7dsFfdH6pmUF1F3EOI8lSvS/A+mbawXgV0D/SVfVsIK6UU9Zmv9kJG+GIAbY4H3HGgtEP9gMcsMwDbyA1mVBuUCY8DxrZ8AQBchzMkFgMkcOBNNIVdpTyflMbQWBuuyzZ10WSwE84xzz7TEAiolkUEeoieUy4UlMjhVgbigDgJJAsAwD+wVpEybG7aOwzMg7WsTuOH+UAA3eBrIhgU9TUnU4t55as4+p+TUThufA2NSmbvaJe8TOyV7dade9tkAAM7KdzRPS+FUzMIXlN5LZ2sbj6Gql11A7G0IiSbkd06ejVEh4lKOOp4WINdmKgHPsp8+ZXB4BQcMhxbkdloiUjWGGGrDgDCBG//AN+fJ5uO/5I8iGa24UbtSBRubPyQPqYAdDZoTPwJJHp7B4eWmqpsnr7xdAo0uO53AXnwpEJoinedBR1ssnr0R6bgO8VxmXq4FJWh+2Dba1tOV0WsZFuMSGnIi8gfedEqEC1m/sp+iFTfh4nN35NKe5cvZmB0TdvVd8N3SK09vDAAaVsbBeZa0+1mN3iiiC2oQFAg5pjgMJpMkWaDrEzowkBQZUt5IzxOXnZELLZUEPUEGUjNSxUpuZxWDGh3nRMnGls0alupeWhTPiDlIVda4mZLF4E5XsW0NgBHzqFG0uxQE//FKeBCVYXVLupmyW+GpjZ1CSMmmDACbXeumlVJjk9WTJlXUolb7CDN/FlD+UIPAU7EMa2q07+4rMvsklTZCN5XVcmpmKayh7SuU4TmazE2BqxW

python
response = requests.post(url, json=payload, headers=headers)
print(response.text)


## Asynchronous Callback

Since generating images with Midjourney requires a waiting period, this API is also designed by default for long wait mode. However, in certain scenarios, long waits may incur additional resource overhead, so this API also provides an asynchronous Webhook callback method. When the image generation is successful or fails, the result will be sent to the specified Webhook callback URL via an HTTP request. The callback URL can then perform further processing upon receiving the result.

Below demonstrates the specific calling process.

First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes, a public webhook sample site [https://webhook.site/](https://webhook.site/ "https://webhook.site/") is used here, opening the site will provide a Webhook URL, as shown in the figure:

![](https://cdn.acedata.cloud/srf3tq.png)

Copy this URL to use as the Webhook. The sample here is [https://webhook.site/995d0a91-d737-40a7-a3b9-5baf68ed924c](https://webhook.site/995d0a91-d737-40a7-a3b9-5baf68ed924c "https://webhook.site/995d0a91-d737-40a7-a3b9-5baf68ed924c").

Next, we can set the field `callback_url` to the above Webhook URL and fill in `prompt`, as shown in the figure:

![](https://cdn.acedata.cloud/hclosy.png)

After clicking test, a response with a `task_id` will be received immediately, used to identify the current generation task's ID, as shown in the figure:

<p><img src="https://cdn.acedata.cloud/vkr32a.png" width="300" class="m-auto"></p>

After a brief wait, once the image generation is complete, the Webhook URL will receive an HTTP request, as shown in the figure:

![](https://cdn.acedata.cloud/6znvgq.png)

The result contains the current task's result, as follows:

json
{
"success": true,
"task_id": "f6e39eaf-652a-4bf5-a15c-79d8b143b80a",
"image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234551030549839932/kcisok_A_cat_sitting_on_a_table_id2724480_591c5c85-ec80-42ab-9fe5-9adfbed192e4.png?ex=663124be&is=662fd33e&hm=da725eb74aae375d60beec38b4cd26c5a7b373b1662f222ff838a8ea6fd5e798&width=1024&height=1024",
"image_width": 1024,
"image_height": 1024,
"image_id": "1234551030549839932",
"raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234551030549839932/kcisok_A_cat_sitting_on_a_table_id2724480_591c5c85-ec80-42ab-9fe5-9adfbed192e4.png?ex=663124be&is=662fd33e&hm=da725eb74aae375d60beec38b4cd26c5a7b373b1662f222ff838a8ea6fd5e798&",
"raw_image_width": 2048,
"raw_image_height": 2048,
"progress": 100,
"actions": [
"upscale1",
"upscale2",
"upscale3",
"upscale4",
"reroll",
"variation1",
"variation2",
"variation3",
"variation4"
]
}


The `success` field indicates whether the task was executed successfully. If successful, there will also be the same `actions`, `image_id`, `image_url` fields, and the return result is the same as mentioned earlier. Additionally, there is a `task_id` to identify the task, associating the Webhook result with the original API request.

If the image generation fails, the Webhook URL will receive a similar content as follows:

json
{
"success": false,
"task_id": "7ba0feaf-d20b-4c22-a35a-31ec30fc7715",
"error": {
"code": "bad_request",
"message": "Unrecognized argument(s): -c, x"
}
}


Here, the `success` field will be `false`, and there will also be `error.code` and `error.message` fields describing the details of the task error, allowing the Webhook server to process according to the respective results.

## Streaming Output

Midjourney officially has progress while generating images. Initially, it starts as a blurry photo, and after several iterations, the image gradually becomes clear, resulting in a complete image.

Therefore, the image generation process can be roughly divided into the stages of "sending command" -> "starting image generation (gradually becoming clear through multiple iterations)" -> "image generation complete".

Without enabling streaming output, this API's process from initiating the request to returning the result actually encompasses the whole "sending command" -> "image generation complete" process, with the intermediate image generation process included. Due to Midjourney's relatively slow image generation speed, the entire process may take about a minute or longer.

To enhance user experience, this API supports streaming output, meaning that results are returned as soon as "image generation starts," streaming the result each time there is a change in drawing progress until the image generation is finished.

If you want to return a response in streaming mode, you can change the `accept` parameter in the request header to `application/x-ndjson`, but the calling code needs corresponding modifications to support streaming response.

Python sample code:

python
import requests

url = 'https://api.acedata.cloud/midjourney/imagine'
headers = {
'content-type': 'application/json',
'accept': 'application/x-ndjson',
'authorization': 'Bearer {token}'
}
body = {
"prompt": "a beautiful cat --v 6"
}
r = requests.post(url, headers=headers, json=body, stream=True)
for line in r.iter_lines():
print(line.decode())


Running result:

json
{"image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558451443699803/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba7&is=662fda27&hm=4625d5f12158bffc07c4faaf6ce75af6f1396122f148b33b91f3e20b48fecc8b&width=256&height=256","image_width":256,"image_height":256,"image_id":"1234558451443699803","raw_image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558451443699803/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba7&is=662fda27&hm=4625d5f12158bffc07c4faaf6ce75af6f1396122f148b33b91f3e20b48fecc8b&","raw_image_width":512,"raw_image_height":512,"progress":35,"actions":[],"task_id":"49589d2c-b6b3-4fbf-9f82-93068509c76f","success":true}
{"image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558458595115149/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba9&is=662fda29&hm=9af53fa645127131a88dfbb3930add7abda710c12a3d6c30c457d6a067b36bab&width=256&height=256","image_width":256,"image_height":256,"image_id":"1234558458595115149","raw_image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558458595115149/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba9&is=662fda29&hm=9af53fa645127131a88dfbb3930add7abda710c12a3d6c30c457d6a067b36bab&","raw_image_width":512,"raw_image_height":512,"progress":75,"actions":[],"task_id":"49589d2c-b6b3-4fbf-9f82-93068509c76f","success":true}
{"image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558483408490566/kcisok_A_landscape_painting_of_a_beautiful_sunset_id5963392_eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc.png?ex=66312baf&is=662fda2f&hm=185ea8f130806bf8bd96911bd251808455fd65596edcdb459f9b3cfd7860387c&width=1024&height=1024","image_width":1024,"image_height":1024,"image_id":"1234558483408490566","raw_image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558483408490566/kcisok_A_landscape_painting_of_a_beautiful_sunset_id5963392_eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc.png?ex=66312baf&is=662fda2f&hm=185ea8f130806bf8bd96911bd251808455fd65596edcdb459f9b3cfd7860387c&","raw_image_width":2048,"raw_image_height":2048,"progress":100,"actions":["upscale1","upscale2","upscale3","upscale4","reroll","variation1","variation2","variation3","variation4"],"task_id":"49589d2c-b6b3-4fbf-9f82-93068509c76f","success":true}


You can see that after enabling streaming output, the returned result is a line-by-line JSON.

In the Node.js environment, the implementation code can be written as follows:

javascript
const axios = require("axios");

const url = "https://api.acedata.cloud/midjourney/imagine";
const headers = {
"content-type": "application/json",
accept: "application/x-ndjson",
authorization: "Bearer {token}",
};
const body = {
prompt: "a beautiful cat --v 6",
action: "generate",
};

axios
.post(url, body, { headers: headers, responseType: "stream" })
.then((response) => {
console.log(response.status);
response.data.on("data", (chunk) => {
console.log(chunk.toString());
});
})
.catch((error) => {
console.error(error);
});




The results of these examples are all similar.

Please note that there is a field called progress in the streaming output result, which indicates the generation progress, ranging from 0 to 100. If needed, you can display this information on the page.

> Note: When the generation is not fully completed, the actions field is empty, indicating that no further processing operations can be performed on the intermediate image. After completion, the image_url generated in the process will be destroyed.

Additionally, you can combine streaming results with asynchronous callbacks by specifying the request header accept=application/x-ndjson and the request body callback_url, which can receive multiple POST requests of streaming results.