PT
EntrarExperimentar grátisEntrar
REST API v1 · MCP

Neuro no seu código

Tudo o que o painel faz: enviar uma foto, orçar, iniciar uma tarefa, receber os arquivos. Os créditos são cobrados do saldo do espaço de trabalho só pelos formatos aceitos pelo controle de IA.

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

# 2. Orçamento
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. Tarefa
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. Status e arquivos
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"

Chaves

Cabeçalho Authorization: Bearer nb_live_…. As chaves são criadas na página “API e MCP” e exibidas uma vez. Uma chave de teste nb_test_… não gera nem cobra nada: responde com o orçamento no mesmo formato de uma chave de produção.

Limites: 120 requisições por minuto por chave, 300 por espaço de trabalho, 30 novas tarefas por minuto.

Obter uma chave

Endpoints

URL 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

Campos da tarefa

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

Modos: create, pack, adapt, html5, video, reframe, ctr, enhance, card, background, scene, tryon, model, unify, translate, markup, edit. Em create com auto_pick: true, o Neuro escolhe o esboço; caso contrário, a tarefa espera uma resposta em question — responda via /jobs/{id}/answer. Em markup, envie as páginas do PDF como imagens, em ordem.

Webhooks

Eventos job.step, job.completed, job.failed. Assinatura no cabeçalho NB-Signature: t=…,v1=… — HMAC-SHA256 de `${t}.${body}` com o segredo do endpoint. Novas tentativas: 1, 5, 30 minutos, 2 e 12 horas.

De onde vem o segredo: um endereço para todas as tarefas — POST /v1/webhooks ou a página de desenvolvedores; o segredo vem uma única vez na resposta. Um endereço para uma só tarefa — webhook_url em POST /v1/jobs, o segredo está no campo webhook_secret da resposta. Lista e remoção: 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));
}

Erros

A resposta { "error": { "code", "message" } } — message vem na voz do Neuro, no idioma do Accept-Language.

401 invalid_api_keyChave de API não reconhecida.
402 insufficient_creditsCréditos insuficientes; missing informa quantos.
422 invalid_requestA requisição tem erros; details lista os campos.
429 rate_limitedRequisições demais; veja Retry-After.
503 not_configuredO serviço ainda está sendo configurado.

MCP

Streamable HTTP: https://mcp.neurobanner.com/mcp. A autenticação é a mesma chave de API no cabeçalho Authorization. Tarefas longas retornam um job_id na hora.

list_formatsFormat catalog with tamanhos, 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 tamanhos.
make_format_packPlatform tamanho packs; shared sizes are made and charged once.
enhance_bannerSharpness, light and a clean background.
replace_backgroundRemover or replace the background: transparent PNG, marketplace white, a color or a scene.
product_in_sceneLifestyle gallery shots de 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 de the workspace.