DrawNew.comDrawNew.com

Riferimento API

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

Endpoint pubblici per integrazioni batch e agent. Autenticati con la chiave API già assegnata al tuo account — non è necessario un token separato.

Autenticazione

Includi la tua chiave API nell'intestazione Authorization. La chiave è la stessa assegnata al tuo account in user_keys (fornita da DrawNew dopo l'attivazione del tuo piano). Una chiave errata restituisce 401.

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

Creare un task di generazione

Invia il task al fornitore di immagini a monte e restituisce immediatamente i task_ids. Per ottenere l'immagine risultante puoi (A) interrogare direttamente GET /v1/tasks/:id, oppure (B) aprire semplicemente il sito web — la stessa scheda Creazione immagini dell'account recupererà automaticamente il task e persisterà i risultati in "Le mie opere".

Richiesta

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
  }'

Risposta

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

Parametri del body

CampoTipoObbligatorioPredefinitoDescrizione
promptstring✓—Prompt di generazione
modelstringgpt-image-2ID del modello (vedi sotto)
modetext | edit | fusiontexttext=testo in immagine; edit=modifica immagine singola; fusion=fusione multi-immagine
aspectstring1:1Rapporto: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9, …
imageSize1K | 2K | 4K2KRisoluzione di output
countnumber1Numero di immagini (limitato per modello)
imageUrlsstring[][]URL di immagini di riferimento per edit / fusion

Modelli disponibili

modelNomeModalità supportate
gpt-image-2GPT Image 2text, edit
proNano Banana Protext, edit
flash2Nano Banana 2text, edit
flashNano Bananatext, edit

Errori

HTTPerror.typeQuando
400invalid_requestIl body non è JSON, il prompt è vuoto, modello sconosciuto o il modello non supporta la modalità
401unauthorizedIntestazione Authorization mancante o formato errato
401invalid_api_keyChiave API non trovata in user_keys
403no_creditsQuota mensile esaurita. Aggiorna il tuo piano su https://drawnew.com/pricing
GET/api/v1/tasks/{task_id}

Interrogare un singolo task

Restituisce lo stato del task a monte. status è uno tra queued / in_progress / completed / failed. completed aggiunge un campo imageUrl; failed aggiunge un campo error.

Richiesta

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

Risposta

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

Interrogare più task

Interroga più task in una chiamata per risparmiare round-trip e ricerche di autenticazione. I risultati vengono restituiti nello stesso ordine degli id in input. Massimo 20 id per richiesta.

Richiesta

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

Risposta

{
  "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" }
  ]
}

Errori di interrogazione

HTTPerror.typeQuando
400invalid_requestParametro ids mancante, o più di 20 id
401unauthorizedIntestazione Authorization mancante o formato errato
401invalid_api_keyChiave API non trovata in user_keys
POST/api/v1/upload

Caricare un'immagine di riferimento (per edit / fusion)

Il server recupera un'immagine da un URL pubblico e la riospita sul CDN a monte, restituendo un URL stabile. Passa il risultato a generate_image's imageUrls. Massimo 25 MB per immagine; png / jpeg / webp / gif / bmp accettati.

Richiesta

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"}'

Risposta

{
  "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

Elenca la cronologia di generazione dell'account

Restituisce le generazioni passate attribuite a questa chiave API, le più recenti per prime. Paginazione tramite page (indicizzata da 1) e limit (massimo 50).

Richiesta

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

Risposta

{
  "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

Ottieni livello / stato dell'account

Restituisce l'e-mail, il livello (trial / starter / standard / pro) e se la chiave a monte è configurata. Utile per gli agent per decidere se possono permettersi un modello ad alto costo.

Richiesta

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

Risposta

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

Utilizzo tramite MCP (Claude Desktop / Cursor / Cline)

Per gli agent LLM, il modo più semplice di utilizzare DrawNew è tramite il server MCP ufficiale pubblicato come @drawnew/mcp-server su npm espone 6 strumenti (generate_image, get_task, batch_get_tasks, upload_reference_image, list_my_generations, get_account_status) tramite stdio e funziona con qualsiasi client compatibile con MCP. Aggiungi lo snippet qui sotto alla configurazione MCP del tuo client — ecco fatto.

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

Configurazione Claude Desktop

Percorso: ~/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>"
      }
    }
  }
}

Note

  • •I risultati vengono automaticamente attribuiti all'account che possiede questa chiave API — il task inviato viene registrato in pending_tasks; quando lo stesso account apre successivamente la scheda Creazione immagini del sito web, il frontend si fa carico dell'interrogazione, persiste i risultati in generations / generation_images, e appaiono sotto "Le mie opere" e la libreria delle risorse. Se desideri un puro fire-and-forget senza apparire nell'interfaccia, usa un account chiamata dedicato.
  • •Controllo crediti lato server — se hai esaurito la quota mensile, l'API restituisce HTTP 403 con error.type=no_credits.
  • •Intervallo di interrogazione consigliato: 2-5 secondi. L'endpoint batch accetta al massimo 20 id per chiamata.
  • •Non inserire mai la tua chiave API nel codice lato client. Usala solo dal tuo backend.
© 2026 DrawNew.com. All rights reserved.