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 caminho | Para que serve |
|---|---|
GET /studio/projects | Lista 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/projects | Cria 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}/exports | Guarda na biblioteca um arquivo exportado pelo editor (MP4, GIF e WebP animado em vídeo; PDF e SVG em imagem). |
GET /studio/animation-presets | Predefinições de animação prontas e do workspace. |
Projeto
| Campo | Tipo | Regra |
|---|---|---|
kind | string | image ou video. Não muda depois de criado. |
name | string | Obrigatório, até 120 caracteres; espaços repetidos viram um só. |
document | objeto | O documento do tipo, validado inteiro. Até 10 MB. |
version | inteiro | Na 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)
| Campo | Regra |
|---|---|
schema | studio.image. |
version | 2. O formato anterior (version 1, com canvas, layers e groups no topo) continua aceito. |
artboards | Ao menos uma prancheta. |
styles | Opcional. Estilos que as camadas referenciam por id. |
Cada prancheta:
| Campo | Regra |
|---|---|
id | Letras minúsculas, dígitos, _ e -, começando por letra ou dígito, até 64 caracteres. Único no documento. |
name | Opcional, até 128 caracteres. |
x, y | Posição na área de trabalho, de -100000 a 100000. |
component | Opcional. Uma prancheta componente pode ser repetida em outras por camadas instance. |
canvas | width e height de 100 a 4096, background em #rrggbb ou #rrggbbaa e gradient opcional. |
layers | As camadas, de baixo para cima. Os ids seguem a regra do id e são únicos no documento inteiro. |
groups | Opcional. Grupos de camadas, que podem ser aninhados sem ciclos. |
Tipos de camada (type):
| Tipo | Campos principais |
|---|---|
image | assetId obrigatório; crop e filters opcionais. |
text | text (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. |
shape | shape: rect, ellipse, line, arrow, triangle, star, polygon ou path (com path). |
icon | iconId. |
paint | surface, a pintura à mão. |
instance | componentId, o id de uma prancheta componente. |
chart, table, qr | chart, 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)
| Campo | Regra |
|---|---|
schema | studio.video. |
version | 1. |
canvas | aspect (square, portrait, story ou landscape) e background em #rrggbb. |
durationMs | De 0 a 600000 (10 minutos). |
tracks | As faixas, cada uma com id, kind (visual ou audio) e clips. |
markers | Opcional. Marcadores com id único. |
Cada clipe:
| Campo | Regra |
|---|---|
id | Mesma regra de id; único no documento, junto com os ids das faixas. |
type | video, image, overlay, audio, group, null ou effect. Faixas de áudio só aceitam audio. |
startMs, durationMs, trimInMs | startMs 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, fadeOutMs | volume de 0 a 2; os fades somam no máximo a duração do clipe. |
assetId | Obrigatório em video, image e audio. |
fit | cover ou contain, obrigatório em video e image. |
layer | Obrigatório em overlay: uma camada desenhada sobre o vídeo, sem assetId. |
transform | Nas 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ódigo | Status | Quando |
|---|---|---|
invalid_request | 422 | O nome ou o documento tem problemas. |
version_required | 428 | Falta a versão no If-Match. |
version_conflict | 409 | O projeto foi salvo depois da versão enviada. |
origin_taken | 409 | O projeto ligado ao mesmo comando da Elo é de outra pessoa. |
not_found | 404 | O projeto não existe no workspace ou foi arquivado. |