NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

Biblioteca da comunidade

Explore, pesquise, favorite e clone personagens, locais e objetos da Biblioteca da comunidade pela API REST, e denuncie uma publicação para moderação.

Disponível em Nodaro Cloud · Business edition

A API da Biblioteca da comunidade permite explorar o catálogo compartilhado de personagens, locais e objetos da sua instância do Nodaro e clonar uma publicação para a sua própria biblioteca. O catálogo tem curadoria: quem publica são os administradores da instância, e todo usuário com login pode pesquisar, favoritar, clonar e denunciar as publicações.

A biblioteca é um recurso multiusuário. Ela existe no Nodaro Cloud e na Business edition auto-hospedada. Em uma instância da Community Edition, essas rotas não são registradas e respondem 404. As rotas aceitam um token Bearer: um token de API pessoal (ndr_…), um token de app OAuth (ndr_app_…) ou o token da sua sessão. Veja Autenticação.

Uma implantação que não permite trabalhos públicos não oferece nenhuma publicação. GET /v1/community/browse e GET /v1/community/favorites respondem listas vazias, e o cartão de uma publicação (GET /v1/community/detail/:slug), o detalhe completo e um clone respondem 404 not_found.

Endpoints

MétodoCaminhoO que faz
GET/v1/community/browseLista as publicações públicas, uma página por vez.
GET/v1/community/detail/:slugRetorna uma publicação pelo slug.
GET/v1/community/favoritesAs publicações que você favoritou.
POST/v1/community/listings/:id/cloneCopia uma publicação para a sua biblioteca.
POST/v1/community/listings/:id/favoriteAdiciona ou remove um favorito.
POST/v1/community/listings/:id/reportDenuncia uma publicação para moderação.

O que uma publicação contém

Toda rota de leitura retorna as publicações apenas com estes campos públicos.

CampoO que contém
id, slugO ID da publicação, usado pelas rotas de escrita, e o slug, usado pela rota de detalhes.
entity_typecharacter, location ou object.
title, description, category, style, tagsO que o administrador escreveu ao publicar.
creator_display_nameQuem fez a publicação.
preview_media_url, preview_imagesA imagem de prévia e a galeria de imagens.
clone_count, favorite_countQuantas vezes a publicação foi clonada e favoritada.
created_atQuando a publicação foi feita.

GET /v1/community/browse retorna { data: Listing[], nextCursor }. Para a próxima página, envie nextCursor de volta como cursor. Ele é null quando não há mais resultados.

Parâmetro de consultaO que faz
entityTypecharacter, location ou object.
qBusca de texto completo no título, na descrição e nas tags.
categorySomente uma categoria.
sortnewest (o padrão) ou popular, com as mais clonadas primeiro.
limitTamanho da página: 20 por padrão e no máximo 50.
cursorO nextCursor da página anterior.
curl "https://app.nodaro.ai/v1/community/browse?entityType=character&sort=popular&limit=20" \
  -H "Authorization: Bearer $NODARO_API_KEY"
import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const { data, nextCursor } = await client.community.browse({
  entityType: 'character',
  sort: 'popular',
  limit: 20,
})
{
  "data": [
    {
      "id": "e4b2d8f1-6a3c-4e9b-8d7f-1c5a3e9b2d6f",
      "entity_type": "character",
      "slug": "detective-mara",
      "title": "Detective Mara",
      "description": "Noir-styled investigator",
      "category": "people",
      "style": "realistic",
      "tags": ["noir", "detective"],
      "creator_display_name": "Nodaro Team",
      "preview_media_url": "https://cdn.nodaro.ai/community/detective-mara.png",
      "clone_count": 128,
      "favorite_count": 41,
      "created_at": "2026-08-30T14:02:11Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0zMCJ9"
}

GET /v1/community/detail/:slug retorna { data: Listing }, ou 404 not_found quando a publicação não existe ou foi removida. GET /v1/community/favorites retorna { data: Listing[] }.

Clonar uma publicação

POST /v1/community/listings/:id/clone copia uma publicação para a sua biblioteca e retorna { entityType, id }: o tipo e o ID do seu novo personagem, local ou objeto. O corpo é { entityType }, que precisa corresponder ao tipo da publicação.

  • É uma cópia, não um vínculo. As imagens e os clipes da publicação são copiados para o seu próprio armazenamento. Alterações posteriores na original, ou a remoção da publicação, não afetam a sua cópia.
  • É sua. O clone é um personagem, local ou objeto comum. Renomeie, edite, gere as mídias novamente ou exclua o clone.
  • Os nomes não entram em conflito. Quando você já tem um com o mesmo nome, o clone recebe o mesmo nome seguido de um número, como “Lanterna 2”.
  • Usa o seu armazenamento. Quando a sua conta passa do limite de armazenamento, a clonagem é recusada com 413 storage_limit_exceeded.

Um token de app OAuth precisa do escopo assets:write para clonar. Tokens de API pessoais não precisam de escopo.

curl -X POST https://app.nodaro.ai/v1/community/listings/e4b2d8f1-6a3c-4e9b-8d7f-1c5a3e9b2d6f/clone \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityType": "character" }'
const { id } = await client.community.clone(listingId, 'character')
const mara = await client.characters.get(id)
{ "entityType": "character", "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e" }

Use o novo ID com a API de Personagens, de Locais ou de Objetos.

Favoritar uma publicação

POST /v1/community/listings/:id/favorite alterna o seu favorito e retorna { favorited }: true depois de adicionar e false depois de remover.

const { favorited } = await client.community.favorite(listingId)
const { data: favorites } = await client.community.favorites()

Denunciar uma publicação

POST /v1/community/listings/:id/report sinaliza uma publicação para a análise dos administradores e retorna { ok: true }. O corpo é { reason }, com um destes valores:

reasonUse quando a publicação…
real_person_no_consentMostra uma pessoa real que não deu consentimento.
inappropriateTem conteúdo impróprio.
ip_violationViola a propriedade intelectual de alguém.
otherTem qualquer outro problema.
await client.community.report(listingId, 'real_person_no_consent')

Uma publicação pode ser removida após uma denúncia. As cópias que os usuários já clonaram continuam nas bibliotecas deles.

Nodaro Keepers: o catálogo compartilhado

O Nodaro Keepers é uma prateleira de personagens, criaturas, locais e objetos prontos que todos podem usar. Os administradores da plataforma escolhem os itens dela. Como a Biblioteca da comunidade, ela existe no Nodaro Cloud e na Business edition.

Usar um item o copia para a sua própria conta, com a mesma regra da clonagem de uma publicação:

  • A cópia é uma linha sua. Você pode editá-la no Estúdio, ela aparece na lista com os seus outros itens, e você pode excluí-la.
  • Ela traz o que mantém as renderizações consistentes: o texto público, a imagem principal e as mídias de variação, como ângulos, expressões e poses. Todo arquivo é copiado para o seu próprio armazenamento e conta no limite dele.
  • Vozes: uma voz pronta ou da biblioteca é levada junto. Uma voz personalizada ou clonada fica reduzida ao nome e à amostra.
  • Nunca levados: as escolhas de seletores do dono, as fotos de referência e os campos de modelo treinado.
  • A original nunca muda. Uma alteração posterior nela não chega às cópias, e tirá-la da prateleira não remove nenhuma cópia.

Ler a prateleira e copiar um item não custam créditos.

MétodoCaminhoO que faz
GET/v1/keepers/catalogA prateleira. Pública: não precisa de token, então um visitante pode explorá-la.
POST/v1/keepers/catalog/:kind/:id/copyCopia um item para a sua conta.

Ler a prateleira. GET /v1/keepers/catalog aceita kind (character, creature, location ou object), limit (de 1 a 200, padrão 50) e cursor (o next de uma página anterior). Sem kind, a página percorre os tipos nessa ordem. Ela retorna { data, next }. Cada item é { id, kind, name, description, imageUrl, previewUrl, category, sort, createdAt }:

  • previewUrl é uma cópia de imageUrl com 480 pixels de largura, para um bloco.
  • category é o título da seção na prateleira, e sort é a ordem na prateleira: o menor primeiro, depois o mais novo primeiro.
  • A prateleira contém apenas campos de exibição: nunca um ID de usuário, um prompt, uma foto de referência ou um campo de modelo treinado.
  • Um cursor que não pode ser lido responde 400 validation_error, nunca a primeira página.
  • A resposta fica em cache por 60 segundos, então uma alteração na prateleira aparece em até um minuto. Um endereço pode ler a prateleira 60 vezes por minuto, e acima disso recebe 429.

Copiar um item. POST /v1/keepers/catalog/:kind/:id/copy retorna { id, name, kind, created }. id é a sua própria linha: leia-a com GET /v1/characters/:id e com as outras rotas de entidades. A cópia vai para o seu projeto padrão, com um novo ID de canvas.

  • Uma cópia por pessoa e item. Uma segunda chamada, ou duas chamadas ao mesmo tempo, retorna a mesma cópia com created: false.
  • Uma cópia que você arquivou volta desarquivada.
  • Uma cópia que você já tem continua sua, esteja o item ainda na prateleira ou não.
  • Um token de app OAuth precisa do escopo assets:write.
StatusCódigoSignificado
404not_foundO item não está na prateleira, e você não tem nenhuma cópia dele.
413storage_limit_exceededOs arquivos dele não cabem no seu armazenamento. Nada é mantido.
403personal_space_disabledA sua organização fechou o espaço pessoal para onde a cópia vai.
# Anyone can read the shelf
curl "https://app.nodaro.ai/v1/keepers/catalog?kind=character&limit=20"

# A signed-in user copies one item
curl -X POST "https://app.nodaro.ai/v1/keepers/catalog/character/$ITEM_ID/copy" \
  -H "Authorization: Bearer $NODARO_API_KEY"
{ "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e", "name": "Mira", "kind": "character", "created": true }

Toda leitura de personagem, criatura, local e objeto traz o estado na prateleira como catalog, catalogSort e catalogCategory. Eles são false, 0 e null nas suas próprias linhas e em toda cópia.

A publicação tem curadoria

O catálogo tem curadoria dos administradores da instância. Publicar um item não faz parte da API pública nem do SDK. Veja Biblioteca da comunidade.

Erros

StatusCódigoSignificado
400validation_errorUm campo está ausente ou é inválido.
401unauthorizedO token está ausente, é inválido ou foi revogado.
403insufficient_scopeUm token de app OAuth não tem assets:write para uma clonagem.
404not_foundA publicação não existe ou foi removida, ou a instância é da Community Edition.
413storage_limit_exceededA sua conta passou do limite de armazenamento.

Perguntas frequentes

Uma publicação clonada fica vinculada à original?

Não. A clonagem copia as imagens e os clipes da publicação para o seu próprio armazenamento. Você pode editar a cópia como quiser, e ela continua existindo se a original for alterada ou removida.

Posso publicar meu próprio personagem na Biblioteca da comunidade pela API?

Não. O catálogo tem curadoria dos administradores da instância. A API permite que todo usuário com login explore, favorite, clone e denuncie publicações.

Por que a API da Biblioteca da comunidade retorna 404 na minha instância?

A biblioteca é um recurso multiusuário do Nodaro Cloud e da Business edition. Uma instância da Community Edition não registra essas rotas, então toda chamada retorna 404.

O que acontece se eu clonar uma publicação com o armazenamento cheio?

A clonagem é recusada com 413 storage_limit_exceeded, e nada é copiado. Libere espaço de armazenamento e tente de novo.

O que é o Nodaro Keepers?

O Nodaro Keepers é uma prateleira compartilhada de personagens, criaturas, locais e objetos prontos. GET /v1/keepers/catalog a lê sem token, e POST /v1/keepers/catalog/:kind/:id/copy copia um item para a sua conta de graça.

Última atualização

Nesta página