API do Studii

Chama qualquer ferramenta do Studii a partir do teu próprio servidor, script ou produto. Plano Pro ou superior.

Autenticação

Emite uma chave em /app/settings/api-keys. Envia-a em cada pedido como um token Bearer (ou através de x-api-key):

Authorization: Bearer stu_<your-key>

Criar uma tarefa

Submete uma geração. Devolve imediatamente o ID da tarefa; consultastatus_urlaté o estado ser completed ou failed.

POST https://studii.tech/api/v1/jobs
Authorization: Bearer stu_<your-key>
Content-Type: application/json

{
  "tool": "studio",
  "inputs": {
    "mode": "image",
    "source": "text",
    "quality": "standard",
    "aspect_ratio": "16:9",
    "prompt": "A misty pine forest at dawn, shafts of golden light"
  }
}

Resposta 202:

{
  "id": "8a1f...",
  "status": "queued",
  "status_url": "https://studii.tech/api/v1/jobs/8a1f...",
  "credits_charged": 8
}

Consultar o estado

GET https://studii.tech/api/v1/jobs/<id>
Authorization: Bearer stu_<your-key>

Resposta 200:

{
  "id": "8a1f...",
  "status": "completed",
  "output_url": "https://...supabase.co/.../outputs/<key>",
  "output_kind": "image",
  "tool": "studio",
  "error": null,
  "created_at": "2026-05-14T...",
  "completed_at": "2026-05-14T...",
  "credits_charged": 8
}

Carregar uma imagem de origem

As ferramentas de imagem-para-imagem (virtual-staging, photo-restore, product-background, career-photo) precisam de uma imagem de origem. Fluxo em dois passos:

Passo 1 — pede um URL assinado:

POST https://studii.tech/api/v1/uploads
Authorization: Bearer stu_<your-key>
Content-Type: application/json

{
  "filename": "kitchen.jpg",
  "content_type": "image/jpeg"
}

Resposta 200:

{
  "object_key": "8a1f.../9c3e....jpg",
  "signed_url": "https://...supabase.co/storage/v1/...?token=...",
  "token": "...",
  "expires_in": 7200
}

Passo 2 — envia os bytes com PUT (sem cabeçalho de autenticação, o content-type tem de corresponder):

curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@kitchen.jpg"

Passo 3 — submete a tarefa com source_object_key definido com o object_key devolvido:

POST https://studii.tech/api/v1/jobs
Authorization: Bearer stu_<your-key>
Content-Type: application/json

{
  "tool": "virtual-staging",
  "inputs": { "style": "modern", "room": "living" },
  "source_object_key": "8a1f.../9c3e....jpg"
}

Slugs das ferramentas

• studio — geração de texto ou imagem-para-imagem / vídeo
• virtual-staging — requer source_object_key
• photo-restore — requer source_object_key
• product-background — requer source_object_key
• career-photo — requer source_object_key (um retrato de frente)

Erros

Limites de gasto

Cada chave pode ter um limite de créditos. Quando o limite é atingido, as tarefas devolvem 402. Os limites são indicativos — não reembolsam a meio de uma tarefa. Usa um limite baixo nas chaves de produção para conter custos descontrolados.

Limites de pedidos

Pro: 60 pedidos/min por chave. Team e Business: 300/min. Aumenta através do apoio, se necessário.