DrawNew.comDrawNew.com

Referência da API

POST /api/v1/generate · GET /api/v1/tasks

Endpoints públicos para integrações em lote e com agentes. Autentique-se com a chave de API já emitida para sua conta — nenhum token separado é necessário.

Autenticação

Inclua sua chave de API no cabeçalho Authorization. A chave é a mesma atribuída à sua conta em user_keys (fornecida pelo DrawNew após a ativação do seu plano). Uma chave inválida retorna 401.

HEADER
Authorization: Bearer <your_api_key>
401 RESPONSE
{ "error": { "type": "invalid_api_key", "message": "Invalid API key" } }
POST/api/v1/generate

Criar uma tarefa de geração

Envia a tarefa ao provedor de imagens upstream e retorna imediatamente os task_ids. Para obter a imagem resultante, você pode (A) fazer polling em GET /v1/tasks/:id por conta própria, ou (B) simplesmente abrir o site — a aba Criação de Imagem da mesma conta capturará automaticamente a tarefa e persistirá os resultados em "Meus Trabalhos".

Solicitação

curl -X POST https://www.drawnew.com/api/v1/generate \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene Japanese garden in autumn",
    "model": "flash",
    "mode": "text",
    "aspect": "16:9",
    "imageSize": "2K",
    "count": 1
  }'

Resposta

{
  "task_ids": ["task_abc123"],
  "email": "you@example.com"
}

Parâmetros do body

CampoTipoObrigatórioPadrãoDescrição
promptstring✓—Prompt de geração
modelstringgpt-image-2ID do modelo (veja abaixo)
modetext | edit | fusiontexttext=texto para imagem; edit=edição de imagem única; fusion=combinação de múltiplas imagens
aspectstring1:1Proporção: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9, …
imageSize1K | 2K | 4K2KResolução de saída
countnumber1Quantidade de imagens (limitada por modelo)
imageUrlsstring[][]URLs de imagens de referência para edit / fusion

Modelos disponíveis

modelNomeModos suportados
gpt-image-2GPT Image 2text, edit
proNano Banana Protext, edit
flash2Nano Banana 2text, edit
flashNano Bananatext, edit

Erros

HTTPerror.typeQuando
400invalid_requestBody não é JSON, prompt está vazio, modelo desconhecido ou modelo não suporta o modo
401unauthorizedCabeçalho Authorization ausente ou formato incorreto
401invalid_api_keyChave de API não encontrada em user_keys
403no_creditsCota mensal esgotada. Atualize seu plano em https://drawnew.com/pricing
GET/api/v1/tasks/{task_id}

Consultar uma única tarefa

Retorna o status da tarefa upstream. O status é um entre: queued / in_progress / completed / failed. completed adiciona um campo imageUrl; failed adiciona um campo error.

Solicitação

curl https://www.drawnew.com/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer <your_api_key>"

Resposta

{
  "task_id": "task_abc123",
  "status": "completed",
  "progress": 100,
  "imageUrl": "https://files.example.com/generated/xxx.png"
}
GET/api/v1/tasks?ids=t1,t2

Consultar múltiplas tarefas

Faz polling de muitas tarefas em uma chamada para economizar idas e voltas e consultas de autenticação. Os resultados são retornados na mesma ordem dos ids de entrada. Máximo de 20 ids por solicitação.

Solicitação

curl "https://www.drawnew.com/api/v1/tasks?ids=task_abc,task_def,task_ghi" \
  -H "Authorization: Bearer <your_api_key>"

Resposta

{
  "tasks": [
    { "task_id": "task_abc", "status": "completed", "progress": 100, "imageUrl": "https://..." },
    { "task_id": "task_def", "status": "in_progress", "progress": 60 },
    { "task_id": "task_ghi", "status": "failed", "progress": 0, "error": "model overloaded" }
  ]
}

Erros de polling

HTTPerror.typeQuando
400invalid_requestParâmetro ids ausente ou mais de 20 ids
401unauthorizedCabeçalho Authorization ausente ou formato incorreto
401invalid_api_keyChave de API não encontrada em user_keys
POST/api/v1/upload

Enviar uma imagem de referência (para edit / fusion)

Busca server-side uma imagem de uma URL pública e a hospeda na CDN upstream, retornando uma URL estável. Passe o resultado para imageUrls do generate_image. Máximo de 25 MB por imagem; aceita png / jpeg / webp / gif / bmp.

Solicitação

curl -X POST https://www.drawnew.com/api/v1/upload \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://example.com/cat.png"}'

Resposta

{
  "url": "https://files.example.com/uploads/abc123.png",
  "filename": "cat.png",
  "content_type": "image/png",
  "bytes": 524288
}
GET/api/v1/history?page=1&limit=20

Listar o histórico de gerações da conta

Retorna gerações anteriores atribuídas a esta chave de API, da mais recente para a mais antiga. Paginação via page (indexada em 1) e limit (máximo 50).

Solicitação

curl "https://www.drawnew.com/api/v1/history?page=1&limit=20" \
  -H "Authorization: Bearer <your_api_key>"

Resposta

{
  "items": [
    {
      "id": "tsk_img_xxx",
      "prompt": "a cat in autumn",
      "model": "flash",
      "mode": "text",
      "aspect": "16:9",
      "imageSize": "2K",
      "imageCount": 1,
      "images": ["https://..."],
      "refs": [],
      "createdAt": 1777461252000
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}
GET/api/v1/user/status

Obter nível/status da conta

Retorna o e-mail, nível (trial / starter / standard / pro) e se a chave upstream está configurada. Útil para agentes decidirem se podem usar um modelo de alto custo.

Solicitação

curl https://www.drawnew.com/api/v1/user/status \
  -H "Authorization: Bearer <your_api_key>"

Resposta

{
  "email": "you@example.com",
  "tier": "pro",
  "has_key": true
}

Usar via MCP (Claude Desktop / Cursor / Cline)

Para agentes LLM, a maneira mais fácil de usar o DrawNew é via o servidor MCP oficial publicado como @drawnew/mcp-server no npm. Ele expõe 6 ferramentas (generate_image, get_task, batch_get_tasks, upload_reference_image, list_my_generations, get_account_status) via stdio e funciona com qualquer cliente compatível com MCP. Adicione o trecho abaixo à configuração MCP do seu cliente — é só isso.

npm · @drawnew/mcp-serverREADME completo e configs para Cursor / Cline →

Configuração do Claude Desktop

Caminho: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "drawnew": {
      "command": "npx",
      "args": ["-y", "@drawnew/mcp-server"],
      "env": {
        "DRAWNEW_API_KEY": "<your_api_key>"
      }
    }
  }
}

Observações

  • •Os resultados são automaticamente atribuídos à conta que possui esta chave de API — a tarefa enviada é registrada em pending_tasks; quando a mesma conta abrir a aba Criação de Imagem do site, o frontend assumirá o polling, persistirá os resultados em generations / generation_images, e eles aparecerão em "Meus Trabalhos" e na biblioteca de assets. Se você quiser uma abordagem pura fire-and-forget sem aparecer na interface, dedique uma conta separada de chamadas.
  • •Verificação de créditos no servidor — se você esgotou sua cota mensal, a API retorna HTTP 403 com error.type=no_credits.
  • •Intervalo de polling recomendado: 2-5 segundos. O endpoint de lote aceita no máximo 20 ids por chamada.
  • •Nunca incorpore sua chave de API em código client-side. Use-a apenas do seu próprio backend.
© 2026 DrawNew.com. All rights reserved.