Conceitos

Fazendo requisições

Um endpoint para tudo. Imagem, vídeo, áudio e tools passam pelo mesmo POST /generations — muda só o model e os params.

Base URL

Todos os caminhos são relativos a:

text

https://caranguejo.art/api/v1/dev

Respostas são sempre JSON. Sucesso é { "data": … } (listas adicionam "meta"); erros são { "success": false, "error": { "code", "message" } }.

O endpoint universal

POST /generations aceita alguns campos de primeira classe e um saco livre de params validado contra o schema do modelo:

Campo	Tipo	Para quê
`model` obrigatório	string	Slug de um modelo ou tool (de `GET /models`).
`prompt`	string	Texto guia (opcional para tools).
`image_urls`	string[]	Referências / edição / origem da tool. Suba com `POST /uploads`.
`start_frame_url` / `end_frame_url`	string	Primeiro / último frame para imagem→vídeo.
`audio_url`	string	Áudio de condicionamento (lip-sync / avatar).
`aspect_ratio`, `duration_seconds`, `quality`, `resolution`, `n`	—	Comuns; use os que o modelo suportar.
`params`	object	Qualquer campo específico do modelo (veja `GET /models/:slug`).
`webhook_url`	string	Callback https assinado ao terminar.

Um endpoint, três mídias

bash

curl -X POST https://caranguejo.art/api/v1/dev/generations \
  -H "Authorization: Bearer $CK" -H "Content-Type: application/json" \
  -d '{ "model": "gpt-image-2", "prompt": "um caranguejo numa praia neon",
       "params": { "quality": "high", "resolution": "2K" } }'

bash

curl -X POST https://caranguejo.art/api/v1/dev/generations \
  -H "Authorization: Bearer $CK" -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2", "prompt": "gire o produto 360°",
       "start_frame_url": "https://media.caranguejo.art/inputs/…/produto.png",
       "duration_seconds": 5, "aspect_ratio": "9:16" }'

bash

curl -X POST https://caranguejo.art/api/v1/dev/generations \
  -H "Authorization: Bearer $CK" -H "Content-Type: application/json" \
  -d '{ "model": "upscale",
       "image_urls": ["https://media.caranguejo.art/inputs/…/foto.png"] }'

Enviando arquivos

Para editar/condicionar com mídia local, suba primeiro com POST /uploads (multipart, até 25 MB). Você recebe uma URL permanente e pública para usar em image_urls, start_frame_url etc. Arquivos idênticos são de-duplicados.

bash

curl -X POST https://caranguejo.art/api/v1/dev/uploads \
  -H "Authorization: Bearer $CK" \
  -F file=@./produto.png

json

{ "data": { "url": "https://media.caranguejo.art/inputs/…/produto.png",
           "mime_type": "image/png", "size": 482113 } }

Formato da resposta

Um job aceito volta como processing. Quando completa, output.assets traz cada URL de saída com seu type (jobs de imagem também mantêm output.images por compatibilidade):

json

{
  "data": {
    "id": "9f0c…",
    "status": "completed",
    "type": "image",
    "credits_charged": 40,
    "output": {
      "assets": [{ "url": "https://media.caranguejo.art/…", "type": "image" }],
      "images": [{ "url": "https://media.caranguejo.art/…" }]
    }
  }
}

Síncrono vs. assíncrono

A API é assíncrona por natureza: POST /generations retorna na hora com status: "processing". Para saber o resultado você tem duas opções — fazer polling em GET /generations/:id ou passar um webhook_url. As superfícies de alto nível (CLI, SDK, MCP) oferecem um modo de esperar (ex.: --wait / waitForGeneration) que faz o polling por você. Detalhes em Assíncrono & webhooks.