Geração e edição de imagem

A Norlen oferece três endpoints de imagem: geração (texto → imagem), edição (imagem + instrução → imagem) e composição (2–3 referências + prompt → imagem nova). Todos retornam a imagem em base64 e seguem o espírito da API de imagens da OpenAI.

Geração (texto → imagem)

Gera uma imagem a partir de um prompt de texto. Segue o formato de images/generations da OpenAI.

Base URL diferente

A geração de imagem fica em app.norlen.io/api/v1 — não em api.norlen.io. A autenticação (Bearer key) é a mesma.

POST https://api.norlen.io/v1/images/generations
Authorization: Bearer SUA_API_KEY
Content-Type: application/json

Parâmetros

Campo	Tipo	Obrigatório	Descrição
model	string	sim	qwen-image (padrão) ou flux — ver abaixo
prompt	string	sim	Descrição da imagem desejada
size	string	não	Dimensões, ex. 1024x1024 (padrão e recomendado)
n	integer	não	Número de imagens (padrão 1)

Dica

Dois modelos de imagem: qwen-image (rápido, poucos passos) e flux (FLUX.1 Kontext — texto mais nítido e edição que preserva o sujeito; um pouco mais lento). Mesma cobrança nos dois. Troque pelo campo model.

Exemplo

curl

curl https://api.norlen.io/v1/images/generations \
  -H "Authorization: Bearer $NORLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image",
    "prompt": "Uma bússola de latão sobre um mapa náutico, luz de estúdio",
    "size": "1024x1024"
  }'

Python

import base64, requests

r = requests.post(
    "https://api.norlen.io/v1/images/generations",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    json={"model": "qwen-image", "prompt": "Uma bússola de latão sobre um mapa náutico", "size": "1024x1024"},
    timeout=120,
)
data = r.json()["data"][0]["b64_json"]
with open("imagem.png", "wb") as f:
    f.write(base64.b64decode(data))

Node.js

const r = await fetch("https://api.norlen.io/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORLEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "qwen-image", prompt: "Uma bússola de latão sobre um mapa náutico", size: "1024x1024" }),
});
const { data } = await r.json();
const buffer = Buffer.from(data[0].b64_json, "base64");
await require("fs/promises").writeFile("imagem.png", buffer);

Resposta

{
  "created": 1750000000,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
  ]
}

A imagem vem em data[0].b64_json (PNG em base64). Decodifique e salve, ou exiba com data:image/png;base64,<...>.

Edição (imagem + instrução → imagem)

Edite uma imagem existente por instrução — descreva a mudança e a Norlen a aplica preservando o resto da cena (modelo Qwen-Image-Edit). Segue o espírito de images/edits da OpenAI.

POST https://api.norlen.io/v1/images/edits
Authorization: Bearer SUA_API_KEY

Aceita dois formatos de entrada:

• multipart/form-data (como a SDK da OpenAI): campo image com o arquivo + prompt com a instrução.
• JSON: { "image": "<base64 ou data URL>", "prompt": "..." }.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
image	arquivo | string	sim	A imagem a editar — arquivo (multipart) ou base64/data URL (JSON). Máx. ~10MB
prompt	string	sim	A instrução de edição, ex. “deixe a maçã azul”. Até 2000 caracteres
n	integer	não	Número de variações (1–4, padrão 1)

Campo model opcional: qwen-image (padrão, Qwen-Image-Edit) ou flux (FLUX.1 Kontext — edição que preserva melhor o sujeito).

Exemplo

curl

curl https://api.norlen.io/v1/images/edits \
  -H "Authorization: Bearer $NORLEN_API_KEY" \
  -F image=@foto.png \
  -F prompt="deixe a maçã azul"

Python

import base64, requests

r = requests.post(
    "https://api.norlen.io/v1/images/edits",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    files={"image": open("foto.png", "rb")},
    data={"prompt": "deixe a maçã azul"},
    timeout=180,
)
open("editada.png", "wb").write(base64.b64decode(r.json()["data"][0]["b64_json"]))

Node.js

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("image", new Blob([await readFile("foto.png")]), "foto.png");
form.append("prompt", "deixe a maçã azul");

const r = await fetch("https://api.norlen.io/v1/images/edits", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NORLEN_API_KEY}` },
  body: form,
});
const { data } = await r.json();
const fs = await import("node:fs/promises");
await fs.writeFile("editada.png", Buffer.from(data[0].b64_json, "base64"));

JSON (base64)

curl https://api.norlen.io/v1/images/edits \
  -H "Authorization: Bearer $NORLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"<base64-ou-data-url>","prompt":"deixe a maçã azul"}'

A resposta tem o mesmo formato da geração: { "created": ..., "data": [{ "b64_json": "..." }] }.

Composição (combinar referências → imagem nova)

Envie 2 a 3 imagens de referência junto com um prompt e receba uma imagem nova que combina elementos das referências seguindo a sua descrição — ex.: a pessoa de uma imagem segurando o produto de outra, ou um personagem dentro de um cenário. Usa o modelo Qwen-Image-Edit 2509 (multi-imagem).

POST https://api.norlen.io/v1/images/compose
Authorization: Bearer SUA_API_KEY

Aceita dois formatos de entrada:

• multipart/form-data: repita o campo image para cada referência (2–3×) + prompt.
• JSON: { "images": ["<base64 ou data URL>", ...], "prompt": "...", "size": "1024x1024" }.

No prompt, refira-se às imagens pela ordem em que foram enviadas — “imagem 1”, “imagem 2”…

Parâmetros

Campo	Tipo	Obrigatório	Descrição
image / images	arquivo[] | string[]	sim	2 a 3 referências — campos image repetidos (multipart) ou array images (JSON). Máx. ~10MB cada
prompt	string	sim	Como combinar as referências. Até 2000 caracteres
size	string	não	Dimensões da saída, ex. 1024x1024 (padrão)
n	integer	não	Número de imagens (1–4, padrão 1)

Nota

A composição roda só no qwen-image — o campo model é aceito mas flux é convertido para qwen-image automaticamente.

Exemplo

curl

curl https://api.norlen.io/v1/images/compose \
  -H "Authorization: Bearer $NORLEN_API_KEY" \
  -F image=@pessoa.png \
  -F image=@produto.png \
  -F prompt="a pessoa da imagem 1 segurando o produto da imagem 2, luz de estúdio" \
  -F size=1024x1024

Python

import base64, requests

r = requests.post(
    "https://api.norlen.io/v1/images/compose",
    headers={"Authorization": "Bearer SEU_TOKEN"},
    files=[
        ("image", open("pessoa.png", "rb")),
        ("image", open("produto.png", "rb")),
    ],
    data={"prompt": "a pessoa da imagem 1 segurando o produto da imagem 2", "size": "1024x1024"},
    timeout=180,
)
open("composicao.png", "wb").write(base64.b64decode(r.json()["data"][0]["b64_json"]))

Node.js

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("image", new Blob([await readFile("pessoa.png")]), "pessoa.png");
form.append("image", new Blob([await readFile("produto.png")]), "produto.png");
form.append("prompt", "a pessoa da imagem 1 segurando o produto da imagem 2");

const r = await fetch("https://api.norlen.io/v1/images/compose", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NORLEN_API_KEY}` },
  body: form,
});
const { data } = await r.json();
const fs = await import("node:fs/promises");
await fs.writeFile("composicao.png", Buffer.from(data[0].b64_json, "base64"));

JSON (base64)

curl https://api.norlen.io/v1/images/compose \
  -H "Authorization: Bearer $NORLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"images":["<base64-1>","<base64-2>"],"prompt":"a pessoa da imagem 1 segurando o produto da imagem 2"}'

A resposta tem o mesmo formato: { "created": ..., "data": [{ "b64_json": "..." }] }.

Cobrança

Cada plano inclui uma cota mensal de imagens — válida para geração, edição e composição (cada chamada conta como uma imagem). Imagens além da cota custam $0.03 cada, debitadas do seu saldo. Veja Preços & cotas.

Dica

Uma geração leva em torno de 7–16s. A edição e a composição partem de ~12–15s quando o modelo está quente; a primeira chamada (ou logo após uma geração) pode levar ~1–1,5min enquanto o modelo de edição carrega.