Início rápido

#Carteiro

Ferramenta de teste de API

Postman é uma ferramenta gráfica de teste HTTP que facilita o teste QwenCloud APIs. Use-o para validar rapidamente endpoints de API, testar operações assíncronas para geração de imagens/vídeos e integrações de protótipos antes de escrever código.

Início rápido

Comece a correr em alguns minutos:

# 1. Install
Download Postman from postman.com/downloads

# 2. Create request (New → HTTP Request)
Method: POST
URL: https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation

# 3. Configure (Headers tab)
Authorization: Bearer sk-ws-xxx
Content-Type: application/json

# 4. Test (Body tab → raw → JSON)
{
  "model": "qwen-plus",
  "input": {
    "messages": [{"role": "user", "content": "Hello, who are you?"}]
  }
}

Você deverá ver: resposta JSON com a resposta do modelo

Configuração

Configuração básica

Configurar o Postman para QwenCloud API:

• Pontos de extremidade da API: https://maas.qwencloudapi.com

• Autenticação: token de portador com chave API

• Tipo de conteúdo: application/json

  Cota e cobrança gratuitas:

  • Usuários iniciantes recebem uma cota gratuita. Consulte Cota gratuita para obter detalhes.
  • Ativar somente cota gratuita para evitar cobranças inesperadas.

Tipos de API

QwenCloud oferece dois padrões de API:

APIs síncronas

Exemplo de geração de texto

Criar pedido

Novo → Solicitação HTTP → POST

Set URL

```
https://maas.qwencloudapi.com/api/v1/services/aigc/text-generation/generation
```

Add headers

Add body

```json
{
  "model": "qwen-plus",
  "input": {
    "messages": [
      {"role": "user", "content": "Write a haiku about coding"}
    ]
  },
  "parameters": {
    "temperature": 0.7
  }
}
```

Enviar pedido

Clique em **Enviar** → Ver resposta

APIs assíncronas

Para tarefas demoradas (imagens, vídeos), use o padrão assíncrono:

Etapa 1: Criar tarefa

Configura o pedido

Método: **POST**
URL: `https://maas.qwencloudapi.com/api/v1/services/aigc/text2image/image-synthesis`

Add headers

Add body

```json
{
  "model": "wan2.5-t2i-preview",
  "input": {
    "prompt": "A serene mountain landscape at sunset"
  },
  "parameters": {
    "size": "1024*1024",
    "n": 1
  }
}
```

Send and save task_id

Clique em **Enviar**. A resposta contém `output.task_id` - salve este valor. O `task_id` é válido por 24 horas. Recupere o resultado antes que ele expire.

```json
{
  "request_id": "896b2ccd-a0cd-40a8-a557-bb73cee5cf95",
  "output": {
    "task_id": "42442de9-917d-4c41-80a7-37fb7ad25ed2",
    "task_status": "PENDING"
  }
}
```

Etapa 2: resultado da consulta

Configurar a consulta

Método: **OBTER**
URL: `https://maas.qwencloudapi.com/api/v1/tasks/{task_id}`
Substituir `{task_id}` com ID real

Add headers

Poll for completion

Envie a solicitação a cada 3 a 5 segundos até `output.task_status` é `SUCCEEDED`. A resposta contém o URL da imagem:

```json
{
  "output": {
    "task_status": "SUCCEEDED",
    "results": [
      {
        "orig_prompt": "A serene mountain landscape at sunset",
        "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/..."
      }
    ]
  }
}
```



  O `task_id` é válido por 24 horas. Baixe os arquivos gerados antes que expirem.

mapeamento cURL para Postman

Convertendo exemplos cURL para Postman:

Variáveis de ambiente

Configure variáveis reutilizáveis:

Criar ambiente

Ambientes → Criar novo → Nomeie-o "QwenCloud"

Add variables

Use em pedidos

- Cabeçalhos: `Bearer {{api_key}}`
- URL: `{{base_url}}/api/v1/...`
- Corpo: `"model": "{{model}}"`

Coleções

Organize solicitações relacionadas:

1. Criar coleção: Coleções → Nova coleção
2. Adicionar solicitações: arraste as solicitações para a coleção
3. Compartilhar: exporte como JSON ou compartilhe link
4. Executar tudo: Corredor → Selecionar coleção → Executar

Dicas de teste

Validação de resposta

Adicione testes na guia Testes:

pm.test("Status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("Has output", () => {
  const json = pm.response.json();
  pm.expect(json).to.have.property("output");
});

Automação de pesquisa assíncrona

Automatize a pesquisa de tarefas com scripts:

// In Tests tab of create task request
const taskId = pm.response.json().output.task_id;
pm.environment.set("task_id", taskId);

// Set next request to query task
postman.setNextRequest("Query Task Status");

Solução de problemas

401 Não autorizado

Solução:

• Verifique se a chave da API está correta
• Verifique o prefixo "Bearer" no cabeçalho de autorização
• Certifique-se de que a chave de API tenha cota

400 solicitação incorreta

Solução:

• Validar sintaxe JSON no corpo
• Verifique se os campos obrigatórios estão presentes
• Verifique se o nome do modelo está correto

Tarefa travada em PENDENTE

Solução:

• A geração de imagem/vídeo pode levar alguns minutos
• Continue pesquisando a cada 3-5 segundos
• Verifique o progresso da tarefa_metrics

Tempo limite de conexão

Solução:

• Aumente o tempo limite em Configurações → Geral
• Verifique a conectividade da rede
• Tente primeiro uma solicitação mais simples

Notas de produção

Postman é apenas para teste. Em produção:

• Use SDKs oficiais para o seu idioma
• Implementar tratamento adequado de erros
• Adicione lógica de nova tentativa para tarefas assíncronas
• Armazene chaves de API com segurança

Recursos relacionados

• Referência da API: Documentação completa da API →
• Modelos: Modelos disponíveis → | Preços →
• SDKs: Bibliotecas clientes oficiais →
• Documentos do Postman: Guia oficial do Postman →