FR
Se connecterEssayer gratuitementSe connecter
REST API v1 · MCP

Neuro dans votre code

Tout ce que fait le tableau de bord : importer une photo, obtenir un devis, lancer une tâche, récupérer les fichiers. Les crédits ne sont débités du solde de l’espace de travail que pour les formats acceptés par le contrôle IA.

# 1. Photo
curl https://api.neurobanner.com/v1/assets -H "Authorization: Bearer $NB_KEY" -F file=@mug.jpg

# 2. Devis
curl https://api.neurobanner.com/v1/estimate -H "Authorization: Bearer $NB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"pack","packs":["direct","vk"],"asset_ids":["<asset id>"]}'

# 3. Tâche
curl https://api.neurobanner.com/v1/jobs -H "Authorization: Bearer $NB_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"mode":"pack","packs":["direct","vk"],"asset_ids":["<asset id>"],"webhook_url":"https://you.app/hooks/nb"}'

# 4. Statut et fichiers
curl https://api.neurobanner.com/v1/jobs/<job id> -H "Authorization: Bearer $NB_KEY"
curl -o result.zip https://api.neurobanner.com/v1/jobs/<job id>/zip -H "Authorization: Bearer $NB_KEY"

Clés

En-tête Authorization: Bearer nb_live_…. Les clés se créent sur la page « API et MCP » et ne s’affichent qu’une fois. Une clé de test nb_test_… ne crée et ne débite rien : répond avec le devis dans le même format qu’une clé de production.

Limites : 120 requêtes par minute par clé, 300 par espace de travail, 30 nouvelles tâches par minute.

Obtenir une clé

Endpoints

URL de base: https://api.neurobanner.com/v1

POST/assetsUpload a photo or bannermultipart `file`, or JSON `{ url }`, or JSON `{ name, mime, bytes }` to get a signed upload URL. JPG, PNG, WEBP up to 20 MB, at least 200 px on the short side.
POST/assets/{id}/completeFinish a signed upload
POST/estimateEstimate the cost before starting
POST/jobsStart a jobAnswers at once with the job id. Credits are reserved now and charged only for accepted formats. With too few credits and `autostart: true` the job is saved as a draft (202).
GET/jobs/{id}Job status and results
POST/jobs/{id}/answerAnswer Neuro's question
POST/jobs/{id}/feedbackRate a resultA 1–5 score for the job, or `output_id` with 1 / -1 for one file. Reasons: text, product, style, composition, rules, quality (and slow, price, ready, saved_time for the job). Voting again replaces the earlier vote. Neuro uses the scores to choose models.
POST/jobs/{id}/cancelCancel a job and refund
GET/jobs/{id}/zipZIP of accepted formats
GET/formatsFormat catalog
GET/outputsResult files
GET/brand-kitsBrand kits of the workspace
GET/webhooksWorkspace webhooks
POST/webhooksAdd a workspace webhookEvery job of the workspace sends its events here. The `secret` is returned once: verify `NB-Signature` with it.
DELETE/webhooks/{id}Remove a workspace webhook
GET/balanceCredit balance

Champs de la tâche

{
  "mode": {
    "type": "string",
    "enum": [
      "create",
      "adapt",
      "pack",
      "enhance",
      "ctr",
      "unify",
      "card",
      "video",
      "html5",
      "edit",
      "reframe",
      "background",
      "scene",
      "translate",
      "tryon",
      "model",
      "markup"
    ]
  },
  "tier": {
    "default": "standard",
    "type": "string",
    "enum": [
      "standard",
      "pro"
    ]
  },
  "title": {
    "type": "string",
    "maxLength": 120
  },
  "asset_ids": {
    "default": [],
    "maxItems": 100,
    "type": "array",
    "items": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "brand_kit_id": {
    "anyOf": [
      {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      {
        "type": "null"
      }
    ]
  },
  "brief": {
    "type": "string",
    "maxLength": 2000
  },
  "art_notes": {
    "type": "string",
    "maxLength": 400
  },
  "lang": {
    "type": "string",
    "enum": [
      "ru",
      "en",
      "es",
      "pt",
      "de",
      "fr"
    ]
  },
  "packs": {
    "maxItems": 30,
    "type": "array",
    "items": {
      "type": "string",
      "pattern": "^[a-z0-9_]{2,32}$"
    }
  },
  "format_keys": {
    "maxItems": 200,
    "type": "array",
    "items": {
      "type": "string",
      "maxLength": 64
    }
  },
  "from_photo": {
    "type": "boolean"
  },
  "sizes": {
    "maxItems": 30,
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "width": {
          "type": "integer",
          "minimum": 16,
          "maximum": 4096
        },
        "height": {
          "type": "integer",
          "minimum": 16,
          "maximum": 4096
        },
        "max_kb": {
          "type": "integer",
          "minimum": 10,
          "maximum": 30000
        },
        "format_keys": {
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 64
          }
        }
      },
      "required": [
        "width",
        "height"
      ]
    }
  },
  "goal": {
    "type": "string",
    "maxLength": 200
  },
  "marketplace": {
    "type": "string",
    "enum": [
      "wb",
      "ozon",
      "ym",
      "kaspi"
    ]
  },
  "characteristics": {
    "type": "string",
    "maxLength": 3000
  },
  "output_ids": {
    "maxItems": 30,
    "type": "array",
    "items": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "instruction": {
    "type": "string",
    "minLength": 2,
    "maxLength": 1000
  },
  "network": {
    "type": "string",
    "enum": [
      "rsya",
      "google"
    ]
  },
  "click_url": {
    "type": "string",
    "format": "uri"
  },
  "video_aspect": {
    "type": "string",
    "pattern": "^\\d{1,2}:\\d{1,2}$"
  },
  "seconds": {
    "type": "integer",
    "minimum": 2,
    "maximum": 30
  },
  "seconds_auto": {
    "type": "boolean"
  },
  "concept": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "maxLength": 120
      },
      "idea": {
        "type": "string",
        "maxLength": 600
      },
      "seconds": {
        "type": "integer",
        "minimum": 2,
        "maximum": 30
      },
      "timing": {
        "maxItems": 8,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "time": {
              "type": "string",
              "maxLength": 40
            },
            "what": {
              "type": "string",
              "maxLength": 300
            }
          },
          "required": [
            "time",
            "what"
          ]
        }
      },
      "prompt": {
        "type": "string",
        "maxLength": 2000
      },
      "frozen": {
        "maxItems": 12,
        "type": "array",
        "items": {
          "type": "string",
          "maxLength": 200
        }
      }
    },
    "required": [
      "title",
      "idea",
      "seconds",
      "timing",
      "prompt",
      "frozen"
    ]
  },
  "reference_asset_id": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "reference_asset_ids": {
    "maxItems": 5,
    "type": "array",
    "items": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "target": {
    "type": "string",
    "enum": [
      "tiktok",
      "reels",
      "shorts",
      "vk_clips",
      "youtube",
      "feed"
    ]
  },
  "source_video": {
    "type": "object",
    "properties": {
      "seconds": {
        "type": "number",
        "minimum": 0.5,
        "maximum": 600
      },
      "width": {
        "type": "integer",
        "minimum": 16,
        "maximum": 8192
      },
      "height": {
        "type": "integer",
        "minimum": 16,
        "maximum": 8192
      },
      "name": {
        "type": "string",
        "maxLength": 200
      }
    },
    "required": [
      "seconds",
      "width",
      "height"
    ]
  },
  "webhook_url": {
    "type": "string",
    "format": "uri"
  },
  "autostart": {
    "type": "boolean"
  },
  "thread_id": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "auto_pick": {
    "type": "boolean"
  },
  "shots": {
    "type": "integer",
    "minimum": 1,
    "maximum": 8
  },
  "scene_aspect": {
    "type": "string",
    "enum": [
      "3:4",
      "1:1",
      "4:5",
      "9:16",
      "16:9"
    ]
  },
  "scenes": {
    "maxItems": 8,
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "prompt": {
          "type": "string",
          "minLength": 3,
          "maxLength": 600
        }
      },
      "required": [
        "title",
        "prompt"
      ]
    }
  },
  "wishes": {
    "type": "string",
    "maxLength": 1000
  },
  "tryon": {
    "type": "object",
    "properties": {
      "model": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "const": "kit"
              },
              "model_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64
              }
            },
            "required": [
              "kind",
              "model_id"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "const": "auto"
              },
              "look": {
                "type": "string",
                "maxLength": 300
              }
            },
            "required": [
              "kind",
              "look"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "const": "ghost"
              }
            },
            "required": [
              "kind"
            ]
          }
        ]
      },
      "poses": {
        "minItems": 1,
        "maxItems": 6,
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "front",
            "three_quarter",
            "back",
            "walk",
            "detail",
            "seated"
          ]
        }
      },
      "setting": {
        "default": "studio",
        "type": "string",
        "enum": [
          "studio",
          "white",
          "street",
          "interior"
        ]
      },
      "styling": {
        "type": "string",
        "maxLength": 300
      },
      "aspect": {
        "default": "3:4",
        "type": "string",
        "enum": [
          "3:4",
          "1:1",
          "4:5",
          "9:16"
        ]
      }
    },
    "required": [
      "model",
      "poses"
    ]
  },
  "model_look": {
    "type": "string",
    "maxLength": 300
  },
  "translate": {
    "type": "object",
    "properties": {
      "langs": {
        "minItems": 1,
        "maxItems": 10,
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "ru",
            "en",
            "kk",
            "uz",
            "ky",
            "tg",
            "az",
            "hy",
            "ka",
            "be",
            "uk",
            "tr",
            "de",
            "fr",
            "es",
            "it",
            "pl",
            "zh",
            "ar"
          ]
        }
      },
      "texts": {
        "maxItems": 60,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            },
            "images": {
              "minItems": 1,
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0,
                "maximum": 19
              }
            },
            "keep": {
              "type": "boolean"
            },
            "to": {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "type": "string",
                "maxLength": 400
              }
            }
          },
          "required": [
            "source",
            "images",
            "to"
          ]
        }
      }
    },
    "required": [
      "langs"
    ]
  },
  "markup": {
    "type": "object",
    "properties": {
      "pages": {
        "maxItems": 30,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "lines": {
              "maxItems": 600,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 400
                  },
                  "y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  }
                },
                "required": [
                  "text",
                  "y"
                ]
              }
            }
          }
        }
      }
    },
    "required": [
      "pages"
    ]
  },
  "background": {
    "type": "object",
    "properties": {
      "kind": {
        "type": "string",
        "enum": [
          "transparent",
          "white",
          "color",
          "scene"
        ]
      },
      "color": {
        "type": "string",
        "pattern": "^#[0-9a-fA-F]{6}$"
      },
      "scene": {
        "type": "string",
        "maxLength": 300
      }
    },
    "required": [
      "kind"
    ]
  }
}

Modes : create, pack, adapt, html5, video, reframe, ctr, enhance, card, background, scene, tryon, model, unify, translate, markup, edit. Pour create avec auto_pick: true, Neuro choisit lui-même l’esquisse ; sinon la tâche attend une réponse dans question — répondez via /jobs/{id}/answer. Pour markup, envoyez les pages du PDF en images, dans l’ordre.

Webhooks

Événements job.step, job.completed, job.failed. Signature dans l’en-tête NB-Signature: t=…,v1=… — HMAC-SHA256 de `${t}.${body}` avec le secret de l’endpoint. Nouvelles tentatives : 1, 5, 30 minutes, 2 et 12 heures.

D’où vient le secret : une adresse pour toutes les tâches — POST /v1/webhooks ou la page développeurs ; le secret arrive une seule fois dans la réponse. Une adresse pour une seule tâche — webhook_url dans POST /v1/jobs, le secret est dans le champ webhook_secret de la réponse. Liste et suppression : GET /v1/webhooks, DELETE /v1/webhooks/{id}.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, rawBody, header) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const mac = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Erreurs

La réponse { "error": { "code", "message" } } — message parle avec la voix de Neuro, dans la langue d’Accept-Language.

401 invalid_api_keyClé API non reconnue.
402 insufficient_creditsPas assez de crédits ; missing indique combien.
422 invalid_requestLa requête contient des erreurs ; details liste les champs.
429 rate_limitedTrop de requêtes ; voir Retry-After.
503 not_configuredLe service est encore en cours de configuration.

MCP

Streamable HTTP: https://mcp.neurobanner.com/mcp. L’authentification utilise la même clé API dans l’en-tête Authorization. Les tâches longues renvoient aussitôt un job_id.

list_formatsFormat catalog with tailles, weight limits, rules and popular sizes.
estimate_costEstimates a task in credits before it starts.
create_bannerBanner from a product photo: 3 sketches, a 2K final.
adapt_bannerAn existing banner into any tailles.
make_format_packPlatform taille packs; shared sizes are made and charged once.
enhance_bannerSharpness, light and a clean background.
replace_backgroundRetirer or replace the background: transparent PNG, marketplace white, a color or a scene.
product_in_sceneLifestyle gallery shots sur the product.
translate_creativeLocalize a creative into 1–10 languages, same layout.
dress_on_modelYour garment on a model.
create_modelA new model by description.
improve_ctrCTR review and 3 variants.
unify_style2–100 images in one style.
make_marketplace_cardMain image and 5 slides by marketplace rules.
animate_to_videoAnimated video from a banner.
make_html5Animated HTML5 banner.
make_html_layoutAn image layout or PDF pages (as images, in order) into responsive HTML: live text, cut-out photos, a ZIP with index.html, fragment.html and images.
get_jobJob status, question and result links.
answer_questionAnswers the job question.
list_outputsAccepted files with 1-hour links.
rate_result-1 для одного файла. Причины: text, product, style, composition, rules, quality (для задачи ещё slow, price, ready, saved_time). По оценкам Нейро выбирает модели.
get_balanceCredit balance and plan.
list_brand_kitsBrand kits sur the workspace.