How to use Postman or cURL to make HTTP requests - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Este artigo descreve como usar o Postman e o cURL para chamar APIs de geração de imagem ou vídeo no Alibaba Cloud Model Studio (Bailian). Este guia usa um exemplo de texto para imagem para demonstrar o processo completo, da criação da tarefa à obtenção do resultado.

Postman: ferramenta gráfica e intuitiva para testar requisições HTTP. Recomendada para iniciantes.
cURL: ferramenta de linha de comando poderosa, ideal para desenvolvedores familiarizados com esse ambiente.

Nota

O Postman e o cURL destinam-se a testes rápidos e verificações funcionais. Em ambientes de produção, use os SDKs oficiais ou implemente suas próprias chamadas HTTP.

Mecanismo de chamada assíncrona

As tarefas de geração de imagem e vídeo podem demorar muito para concluir, variando de mais de dez segundos a vários minutos. Para evitar conexões HTTP longas e tempos limite, a API utiliza um mecanismo de chamada assíncrona. O processo divide-se em duas etapas:

Crie uma tarefa: chame a API para criar uma tarefa. O serviço retorna sincronamente um ID de tarefa (task_id).
Consulte o resultado: use o ID da tarefa para consultar o status periodicamente até a conclusão e, em seguida, obtenha a URL final da imagem ou do vídeo.

Exemplo de chamada HTTP (texto para imagem)

Método 1: Usar o Postman (recomendado)

Configure o Postman a partir do cURL

Ao converter um comando cURL para uma requisição no Postman, os parâmetros são mapeados da seguinte forma:

Parâmetro do cURL	Interface do Postman	Descrição
`curl -X POST` ou `curl -X GET`	Menu suspenso de método de requisição	Seleciona o método de requisição HTTP.
`https://<api-endpoint-url>`	Caixa de entrada de URL	A URL do endpoint da API.
`-H 'Key: Value'`	Aba Headers	Configura os cabeçalhos da requisição como pares chave-valor.
`-d '{...}'`	Aba Body	Configura o corpo da requisição.

Pré-requisitos

Antes de chamar a API, obtenha uma chave de API para sua região e baixe o Postman.

Etapa 1: Crie uma tarefa

Use o seguinte comando cURL para configurar o Postman.

A URL base a seguir refere-se à região de Singapura. Use a URL base correspondente à sua região.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

No Postman, clique em new ou + para criar uma nova requisição e selecione HTTP como tipo de requisição.
No menu suspenso de método de requisição, selecione POST e insira a URL referente à região de implantação do seu modelo:
- Singapura: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis. Substitua WorkspaceId pelo seu ID do Workspace real, conforme descrito em Obter ID do Workspace.
- EUA (Virgínia): https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- China (Pequim): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Para verificar os modelos compatíveis em cada região, consulte o console do Model Studio. A região atual e o escopo de implantação do serviço baseiam-se nas relações de vinculação predefinidas do sistema , e combinações personalizadas não são suportadas.

Clique em Headers e adicione os três pares chave-valor a seguir.

Chave	Valor	Descrição	Na aba Headers do Postman, defina X-DashScope-Async como `enable`, Authorization como `Bearer <your-api-key>` e Content-Type como `application/json`.
X-DashScope-Async	enable	Ative chamadas assíncronas.
Authorization	Bearer sk-xxx (Substitua sk-xxx pela sua chave de API)	Credencial de autenticação.
Content-Type	application/json	Declara que o corpo da requisição está no formato JSON.

Configure o corpo da requisição:
- Clique em Body, selecione o botão de opção raw, escolha JSON no menu suspenso de formato à direita e cole o conteúdo JSON após -d do exemplo cURL na caixa de entrada.
```
{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}
```
- (Opcional) Clique em Beautify no lado direito da página para formatar o JSON e facilitar a leitura.
Clique em Send para enviar a requisição e obter o task_id. O task_id é válido por 24 horas. Após esse período, não será possível consultar o resultado. Recupere o resultado prontamente.
```
{
    "request_id": "896b2ccd-a0cd-40a8-a557-bb73cee5cf95",
    "output": {
        "task_id": "42442de9-917d-4c41-80a7-37fb7ad25ed2",
        "task_status": "PENDING"
    }
}
```

Etapa 2: Consultar resultado pelo ID da tarefa

Após obter o ID da tarefa, chame o endpoint de consulta para recuperar o resultado final.

Singapura: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis. Substitua WorkspaceId pelo seu ID do Workspace real.
EUA (Virgínia): https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
China (Pequim): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Configure a requisição de consulta no Postman:
1. Crie uma nova requisição HTTP.
2. Defina o método de requisição como GET.
3. De acordo com a região, insira a URL de consulta e substitua {task_id} na URL pelo task_id real obtido na Etapa 1.
4. Na aba Headers, adicione o cabeçalho Authorization usando a mesma chave de API da Etapa 1.
5. Clique em Send.

Verifique a resposta. Continue consultando este endpoint periodicamente até que o task_status seja SUCCEEDED para obter a URL da imagem. A URL da imagem é válida por 24 horas. Baixe a imagem dentro desse período de validade.

"results": [
            {
                "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
                "actual_prompt": "A cozy and elegant flower shop, with an exterior decorated with exquisitely carved windows. The window frames are light-colored wood, set with transparent glass that reveals the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate, giving it a quaint and textured feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including roses, lilies, hydrangeas, and tulips—are arranged in a staggered, vibrant display. Some bouquets are wrapped in kraft paper and tied with twine, exuding a fresh, natural scent. The background features a quiet European town streetscape, with stone-paved roads and greenery adding to the charm. The overall image is in a realistic photographic style, with soft lighting and a warm color palette that highlights the shop's exquisite and romantic atmosphere.",
                "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/3a/20251203/7a2bee47/42442de9-917d-4c41-80a7-37fb7ad25ed2.png?xxx"
            }
        ]

Método 2: Usar o cURL

Desenvolvedores familiarizados com a linha de comando podem usar o cURL para testar rapidamente a API.

Pré-requisitos

Antes de executar o comando cURL:

Ative o serviço de modelo e obtenha uma chave de API.
Certifique-se de ter instalado o cURL e configurado a chave de API como uma variável de ambiente para referenciar diretamente a variável $DASHSCOPE_API_KEY posteriormente.
Verificar se o cURL está instalado
Execute o seguinte comando para verificar se o cURL está instalado.
```
curl --version
```
Se você vir uma saída semelhante à seguinte, o cURL está instalado:
```
curl 8.x.x (x86_64-apple-darwin23.0) libcurl/8.x.x (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.58.0
Release-Date: 2023-10-11
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS GSS-API HSTS HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL threadsafe UnixSockets
```
Caso não esteja instalado, você poderá ver uma mensagem como uma das seguintes:
- Windows: 'curl' is not recognized as an internal or external command, operable program or batch file.
- Linux/macOS: command not found: curl.
Acesse a página de download do curl para instalá-lo.

Etapa 1: Crie uma tarefa

Execute o seguinte comando no terminal:

A URL base a seguir refere-se à região de Singapura. Use a URL base correspondente à sua região.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

Uma requisição bem-sucedida retorna um task_id. O ID é válido por 24 horas e não pode ser usado para consultas após expirar. Recupere o resultado prontamente.

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'
{"request_id":"ca3b5224-bc60-4e47-80f4-2790040e9e55","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d318061c43","task_status":"PENDING"}}

task_id-intl-zh

Etapa 2: Consultar resultado pelo ID da tarefa

Substitua {task_id} no comando a seguir pelo ID da tarefa obtido na Etapa 1, copie o comando para o terminal e execute-o.

A URL base a seguir refere-se à região de Singapura. Use a URL base correspondente à sua região.
```
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
```

Quando a tarefa for concluída (o task_status for SUCCEEDED), a resposta conterá uma URL de imagem. A URL da imagem é válida por 24 horas. Baixe-a prontamente.

Como o modelo leva muito tempo para processar (de dezenas de segundos a vários minutos), talvez seja necessário consultar esta API periodicamente. Recomendamos consultar a API a cada 3 a 5 segundos até que o task_status deixe de ser RUNNING .

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"24143559-9964-4898-8f9c-d968bba182b9","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d3f8061c43","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:19:18.293","scheduled_time":"2025-12-03 10:19:18.320","end_time":"2025-12-03 10:19:31.890","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A cozy, elegant flower shop. The exterior wall features exquisitely carved windows with dark brown wooden frames, and the glass is clean and bright, revealing the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate that exudes a strong artisanal feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including blooming roses, elegant hydrangeas, fresh daisies, and green eucalyptus leaves—are arranged in a staggered yet harmonious display. The background is a quiet European town streetscape, with a stone-paved road and a vine-covered neighboring wall enhancing the romantic atmosphere. The overall image is in a realistic photographic style, with soft, natural lighting that highlights the wood texture and floral details.","url":"https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/59/20251203/7a2bee47/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43.png?Expires=1764814771&OSSAccessKeyId=xxx"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}

result-intl-zh

Próximas etapas

Após gerar sua primeira imagem com sucesso, explore os seguintes recursos:

Saiba mais sobre os parâmetros da API: consulte a documentação da API de texto para imagem para conhecer parâmetros adicionais.
Experimente a geração de vídeo: teste a API de primeiro quadro para vídeo para criar um vídeo.
Explore mais modelos: acesse o console do Model Studio para ver todos os modelos de imagem e vídeo compatíveis com o Alibaba Cloud Model Studio (Bailian).