Guia do Estúdio

Projetos de imagem e de vídeo do Estúdio, o formato dos documentos, a validação e os limites.

Um projeto do Estúdio guarda o documento que o editor desenha: uma imagem (uma ou mais pranchetas com camadas) ou um vídeo (faixas com clipes numa linha do tempo). O servidor não renderiza nada; ele valida o documento inteiro a cada gravação e guarda a versão.

As rotas estão no grupo Estúdio da Referência da API. As mídias que um documento usa (assetId) são ids da biblioteca de mídia do workspace, e o guia Mídia gerada mostra como gerar imagens, áudios e vídeos com IA.

Rotas

Método e caminhoPara que serve
GET /studio/projectsLista os projetos, do editado mais recentemente para o mais antigo, sem o documento. kind filtra; limit vai até 100 (padrão 30) e offset desloca.
POST /studio/projectsCria um projeto. Responde 201.
GET /studio/projects/{id}Abre o projeto com o documento e a versão atual.
PATCH /studio/projects/{id}Salva o nome e ou o documento a partir da versão do cabeçalho If-Match.
DELETE /studio/projects/{id}Arquiva o projeto: ele some da lista e não abre mais, mas não é apagado.
POST /studio/projects/{id}/exportsGuarda na biblioteca um arquivo exportado pelo editor (MP4, GIF e WebP animado em vídeo; PDF e SVG em imagem).
GET /studio/animation-presetsPredefinições de animação prontas e do workspace.

Projeto

CampoTipoRegra
kindstringimage ou video. Não muda depois de criado.
namestringObrigatório, até 120 caracteres; espaços repetidos viram um só.
documentobjetoO documento do tipo, validado inteiro. Até 10 MB.
versioninteiroNa resposta. Começa em 1 e vai no If-Match ao salvar.

O documento é lido de forma estrita: um campo desconhecido em qualquer nível recusa o documento inteiro com document invalid.

Documento de imagem (versão 2)

CampoRegra
schemastudio.image.
version2. O formato anterior (version 1, com canvas, layers e groups no topo) continua aceito.
artboardsAo menos uma prancheta.
stylesOpcional. Estilos que as camadas referenciam por id.

Cada prancheta:

CampoRegra
idLetras minúsculas, dígitos, _ e -, começando por letra ou dígito, até 64 caracteres. Único no documento.
nameOpcional, até 128 caracteres.
x, yPosição na área de trabalho, de -100000 a 100000.
componentOpcional. Uma prancheta componente pode ser repetida em outras por camadas instance.
canvaswidth e height de 100 a 4096, background em #rrggbb ou #rrggbbaa e gradient opcional.
layersAs camadas, de baixo para cima. Os ids seguem a regra do id e são únicos no documento inteiro.
groupsOpcional. Grupos de camadas, que podem ser aninhados sem ciclos.

Tipos de camada (type):

TipoCampos principais
imageassetId obrigatório; crop e filters opcionais.
texttext (de 1 a 2000 caracteres), fontId da lista de fontes, fontSize de 0,005 a 0,5, fontWeight de 100 a 900 em centenas, align left, center ou right.
shapeshape: rect, ellipse, line, arrow, triangle, star, polygon ou path (com path).
iconiconId.
paintsurface, a pintura à mão.
instancecomponentId, o id de uma prancheta componente.
chart, table, qrchart, table e qr, com a especificação de cada um.

Toda camada tem transform normalizado: x e y (centro) de -1 a 2, w e h de 0,001 a 4, rotation de -360 a 360 e opacity de 0 a 1. Cores são #rrggbb ou #rrggbbaa.

fontId aceita: work-sans, lato, rubik, manrope, outfit, space-grotesk, plus-jakarta-sans, josefin-sans, raleway, nunito, open-sans, roboto, poppins, montserrat, dm-sans, inter, fraunces, lora, merriweather, libre-baskerville, eb-garamond, cormorant-garamond, dm-serif-display, playfair-display, archivo-black, alfa-slab-one, abril-fatface, staatliches, oswald, bebas-neue, anton, righteous, fredoka, titan-one, bungee, lobster, creepster, caveat, kaushan-script, shadows-into-light, amatic-sc, dancing-script, sacramento, great-vibes, pacifico, space-mono, ibm-plex-mono, dm-mono, roboto-mono e jetbrains-mono.

Documento de vídeo (versão 1)

CampoRegra
schemastudio.video.
version1.
canvasaspect (square, portrait, story ou landscape) e background em #rrggbb.
durationMsDe 0 a 600000 (10 minutos).
tracksAs faixas, cada uma com id, kind (visual ou audio) e clips.
markersOpcional. Marcadores com id único.

Cada clipe:

CampoRegra
idMesma regra de id; único no documento, junto com os ids das faixas.
typevideo, image, overlay, audio, group, null ou effect. Faixas de áudio só aceitam audio.
startMs, durationMs, trimInMsstartMs e trimInMs a partir de 0, durationMs de pelo menos 100, e o clipe termina até o durationMs do documento. Os clipes de uma faixa não se sobrepõem.
volume, fadeInMs, fadeOutMsvolume de 0 a 2; os fades somam no máximo a duração do clipe.
assetIdObrigatório em video, image e audio.
fitcover ou contain, obrigatório em video e image.
layerObrigatório em overlay: uma camada desenhada sobre o vídeo, sem assetId.
transformNas faixas visuais: x e y de 0 a 1 (de -1 a 2 num clipe com parentId), opacity de 0 a 1, w e h de 0,001 a 4, rotation de -360 a 360.

Exemplo: criar um projeto de imagem

POST /studio/projects

{
  "kind": "image",
  "name": "Post de segunda",
  "document": {
    "schema": "studio.image",
    "version": 2,
    "artboards": [
      {
        "id": "feed",
        "name": "Feed",
        "x": 0,
        "y": 0,
        "canvas": { "width": 1080, "height": 1350, "background": "#f4efe6" },
        "layers": [
          {
            "id": "foto",
            "type": "image",
            "assetId": "9d2f6a1e-3b4c-4d5e-8f70-1a2b3c4d5e6f",
            "transform": { "x": 0.5, "y": 0.4, "w": 0.9, "h": 0.6, "rotation": 0, "opacity": 1 }
          },
          {
            "id": "faixa",
            "type": "shape",
            "shape": "rect",
            "fill": "#1f2937",
            "radius": 0.2,
            "transform": { "x": 0.5, "y": 0.85, "w": 0.8, "h": 0.12, "rotation": 0, "opacity": 1 }
          },
          {
            "id": "titulo",
            "type": "text",
            "text": "20% de desconto",
            "fontId": "poppins",
            "fontSize": 0.06,
            "fontWeight": 700,
            "align": "center",
            "fill": "#ffffff",
            "transform": { "x": 0.5, "y": 0.85, "w": 0.75, "h": 0.1, "rotation": 0, "opacity": 1 }
          }
        ]
      }
    ]
  }
}

Exemplo: documento de vídeo

{
  "schema": "studio.video",
  "version": 1,
  "canvas": { "aspect": "story", "background": "#000000" },
  "durationMs": 5000,
  "tracks": [
    {
      "id": "v1",
      "kind": "visual",
      "clips": [
        {
          "id": "foto",
          "type": "image",
          "assetId": "9d2f6a1e-3b4c-4d5e-8f70-1a2b3c4d5e6f",
          "startMs": 0,
          "durationMs": 5000,
          "trimInMs": 0,
          "volume": 0,
          "fadeInMs": 0,
          "fadeOutMs": 500,
          "fit": "cover",
          "transform": { "x": 0.5, "y": 0.5, "w": 1, "h": 1, "rotation": 0, "opacity": 1 }
        }
      ]
    },
    {
      "id": "a1",
      "kind": "audio",
      "clips": [
        {
          "id": "trilha",
          "type": "audio",
          "assetId": "7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b",
          "startMs": 0,
          "durationMs": 5000,
          "trimInMs": 0,
          "volume": 0.8,
          "fadeInMs": 0,
          "fadeOutMs": 1000
        }
      ]
    }
  ]
}

Salvar e conflitos

PATCH /studio/projects/{id} recebe name, document ou os dois, e a versão carregada no cabeçalho If-Match. Sem o cabeçalho, responde 428 version_required. Se o projeto foi salvo depois dessa versão, responde 409 version_conflict sem sobrescrever, com code, message e o projeto atual em current (no mesmo formato de GET /studio/projects/{id}).

Erros

Um documento recusado responde 422 invalid_request, com o código por campo em expected:

{
  "error": true,
  "code": "invalid_request",
  "message": "Há campos a corrigir",
  "expected": { "document.layers": "unknown" }
}

Os campos são kind, name, document, document.canvas, document.artboards, document.layers, document.tracks, document.markers e document.styles, e os códigos são required, invalid, unknown, too_large, too_many, out_of_range, duplicate e overlap. O exemplo acima é uma camada de texto com um fontId fora da lista.

CódigoStatusQuando
invalid_request422O nome ou o documento tem problemas.
version_required428Falta a versão no If-Match.
version_conflict409O projeto foi salvo depois da versão enviada.
origin_taken409O projeto ligado ao mesmo comando da Elo é de outra pessoa.
not_found404O projeto não existe no workspace ou foi arquivado.