API somente leitura

Acesso e disponibilidade

Este guia apresenta a versão prévia da API somente leitura. Confira a disponibilidade em Chaves de API na sua conta do Studio. É necessária uma assinatura Studio ou Scale ativa e paga; apenas um pacote de créditos não dá acesso.

As consultas não consomem créditos de geração, mesmo com saldo zero. Esta versão não permite enviar fotos, iniciar gerações, baixar arquivos, alterar projetos ou gerenciar cobranças. É uma API HTTP, não um servidor MCP nem um plugin do ChatGPT.

Crie uma chave e conecte

1. Abra Chaves de API na sua conta do Studio, dê à chave o nome da integração e crie-a. Todas as chaves têm o escopo metadata:read.
2. Copie o segredo quando ele aparecer: ele só é exibido uma vez. Guarde-o em um gerenciador de segredos no servidor ou em uma variável de ambiente chamada SEGMENTIT_API_KEY.
3. Envie a chave pelo cabeçalho Authorization: Bearer usando HTTPS. O exemplo abaixo lê uma variável de ambiente já configurada; não a substitua por um segredo em código compartilhado.

cURL · Bash

curl --fail-with-body --get \
  'https://segmentit.com/api/v1/projects' \
  --data-urlencode 'limit=20' \
  --header \
  "Authorization: Bearer $SEGMENTIT_API_KEY"

Node.js · JavaScript no servidor

Defina SEGMENTIT_API_KEY no seu servidor e execute este exemplo com Node.js 22 ou posterior. Crie sua chave em Studio → Conta → API.

const apiKey = process.env.SEGMENTIT_API_KEY;
if (!apiKey) throw new Error('Set SEGMENTIT_API_KEY');

const response = await fetch(
  'https://segmentit.com/api/v1/projects?limit=20',
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    redirect: 'error',
    signal: AbortSignal.timeout(10_000),
  },
);

if (!response.ok) {
  const retryAfter = response.headers.get('Retry-After');
  throw new Error(
    `API error: ${response.status}` +
    (retryAfter ? `; retry after ${retryAfter}s` : ''),
  );
}

const { data: projects, pagination } = await response.json();
console.log(projects);
console.log('Next offset:', pagination.nextOffset);

Endpoints disponíveis

A URL base é https://segmentit.com/api/v1. Todas as solicitações exigem autenticação e acessam apenas os dados do dono da chave. Use os UUIDs retornados pela API. Os campos JSON e os valores de status permanecem em inglês em todos os idiomas.

As tarefas mostram o último estado salvo: queued, running, succeeded, failed ou cancelled. Consultar uma tarefa não atualiza o provedor de processamento nem inicia trabalho. Atualize o projeto no Studio para obter o estado de processamento mais recente.

Esquema OpenAPI · JSON

Paginação e respostas

As listas retornam data e pagination. O limite padrão é 20; escolha de 1 a 50 itens e um offset entre 0 e 10000. Use nextOffset na próxima solicitação e pare quando for null. Um projeto ou uma tarefa individual retorna apenas um objeto data. As datas seguem ISO 8601.

{
  "data": [
    {
      "id": "7b5e26c3-e260-409a-bbb9-b5719f9dbfb0",
      "name": "Launch",
      "kind": "personal",
      "latestJobId": null,
      "createdAt": "2026-10-09T10:00:00.000Z",
      "updatedAt": "2026-10-09T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "nextOffset": null
  }
}

Limites, erros e novas tentativas

Uma conta pode ter 3 chaves ativas, com validade de 90 dias. Todas compartilham o limite de 60 solicitações por minuto por conta. Em uma resposta 429, aguarde os segundos indicados em Retry-After antes de tentar novamente; evite consultas contínuas.

A elegibilidade é verificada a cada solicitação. Se sua assinatura deixar de ser elegível, a API retorna 403 mesmo que a chave ainda não tenha expirado. Você continua podendo revogar as chaves no Studio. Uma chave revogada ou expirada retorna 401; crie outra quando o acesso estiver disponível.

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required."
  }
}

Proteja sua integração

Execute as solicitações no seu servidor ou em um script local confiável. Nunca coloque chaves em URLs, JavaScript do navegador, repositórios públicos, capturas de tela ou logs. Revogue imediatamente qualquer chave exposta. Uma chave pode ler metadados de todos os seus projetos, não apenas de um projeto selecionado.

As respostas contêm apenas metadados: nenhuma foto original, máscara, conteúdo GLB, URL de arquivo ou credencial do provedor. Continue usando o Studio para visualizar e baixar suas criações.