Skip to content

Desenvolvedores

Vídeos com IA a partir dos seus sistemas

Uma API REST assíncrona e idempotente, webhooks assinados com novas tentativas, SDKs oficiais e um servidor MCP para agentes. Preço garantido antes de produzir.

A API, os webhooks e o MCP estão nos planos Pro e Agency.

Comece em 5 passos

  1. 1
    Crie uma chave de API

    No Studio: Integraciones → API REST → «Crear clave de API». Ela aparece uma só vez.

  2. 2
    Faça a cotação

    POST /v1/estimates com o mesmo pedido que vai criar: o preço máximo garantido em créditos (1 crédito = US$0,01).

  3. 3
    Crie o trabalho

    POST /v1/jobs com Idempotency-Key: repetir o pedido nunca cria nem cobra duas vezes. Responde 202 com o id.

  4. 4
    Acompanhe

    Com webhooks (recomendado), com eventos ao vivo (SSE) em /v1/jobs/{id}/events ou consultando GET /v1/jobs/{id}.

  5. 5
    Baixe ou publique

    Ao terminar, result.videos traz os arquivos; publique nas redes conectadas com POST /v1/publications.

# 1) cotiza · quote
curl https://api.creavideosconia.com/v1/estimates -H "Authorization: Bearer $AIVS_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"idea","idea":"3 errores al elegir zapatillas para correr","channels":["tiktok"]}'

# 2) crea · create (idempotent)
curl https://api.creavideosconia.com/v1/jobs -H "Authorization: Bearer $AIVS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{"kind":"idea","idea":"3 errores al elegir zapatillas para correr","channels":["tiktok"]}'
# → 202 {"id":"job_…","status":"queued",…}

# 3) sigue · follow
curl -N https://api.creavideosconia.com/v1/jobs/job_…/events -H "Authorization: Bearer $AIVS_API_KEY"

Autenticação, limites e erros

  • Envie Authorization: Bearer aivs_… em cada requisição. Guardamos só o hash da chave; revogue quando quiser.
  • Cada resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; acima do limite, 429 com Retry-After. Seu uso por chave: GET /v1/usage/api.
  • Os erros seguem a RFC 7807: type, title, status, detail e request_id (informe ao suporte).
  • Tudo via HTTPS (TLS 1.2 ou superior). Trabalhos que falham do nosso lado não são cobrados.

Webhooks

Avisamos seu servidor quando algo acontece. Assine em Integraciones ou com POST /v1/webhooks; o segredo de assinatura aparece uma só vez.

Eventos disponíveis
EventoO que significa
credits.lowThe available credits dropped below the low-balance threshold
job.canceledThe job was canceled
job.failedThe job failed; nothing was charged for the failed run
job.needs_reviewThe script is ready and waits for approval (approve or edit it)
job.queuedA job was accepted and waits for a worker
job.retryingA step failed and is being retried automatically
job.startedA worker started producing the job
job.succeededThe job finished: its videos and files are ready
order.paidA payment was confirmed: credits or a plan were added
order.refundedA payment was voided or refunded: its credits were taken back
publication.failedA scheduled publication failed for good
publication.publishedA video was published on a connected network
renewal.failedThe automatic renewal charge was declined
review.approvedYour client approved a video through an approval link
review.changes_requestedYour client asked for changes through an approval link

Verifique a assinatura

Cada aviso traz X-AIVS-Timestamp e X-AIVS-Signature = hex(HMAC-SHA256(segredo, timestamp + "." + corpo)). Verifique sobre o corpo bruto, em tempo constante, e rejeite timestamps com mais de 5 minutos. Durante a rotação, o segredo anterior assina em X-AIVS-Signature-Previous.

# Without the SDK (Python standard library)
import hashlib, hmac, time

def valid(body: bytes, ts: str, signature: str, secret: str) -> bool:
    if abs(time.time() - int(ts)) > 300:
        return False
    good = hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(good, signature)

Entregas e novas tentativas

  • Responda 2xx em até 10 s; processe em segundo plano se demorar.
  • Se falhar, tentamos de novo com esperas crescentes (10 s … 1 h) até 8 vezes, por cerca de um dia.
  • X-AIVS-Delivery traz o id do evento (o mesmo em cada nova tentativa): use-o para ignorar duplicados.
  • Se responder 410 Gone, pausamos o webhook. Veja cada entrega e sua resposta, e reenvie, em Integraciones ou pela API.

SDKs oficiais

Novas tentativas com espera, idempotência automática e verificação de webhooks incluídas.

npm install creavideosconia
import { CreaVideos, verifyWebhook, WebhookError } from "creavideosconia";

const api = new CreaVideos({ apiKey: process.env.AIVS_API_KEY! });
const job = await api.jobs.create({ kind: "idea", idea: "3 errores al elegir zapatillas", channels: ["tiktok"] });

// Next.js route handler (any Fetch-API runtime)
export async function POST(req: Request) {
  const raw = await req.text();                     // RAW body, before JSON.parse
  try {
    const event = await verifyWebhook(raw, req.headers, process.env.AIVS_WEBHOOK_SECRET!);
    if (event.type === "job.succeeded") { /* event.data.videos … */ }
    return new Response("ok");
  } catch (e) {
    if (e instanceof WebhookError) return new Response("bad signature", { status: 400 });
    throw e;
  }
}
pip install creavideosconia
from creavideosconia import Client, verify_webhook, WebhookError

api = Client("https://api.creavideosconia.com", "aivs_…")
job = api.create_job({"kind": "idea", "idea": "3 errores al elegir zapatillas", "channels": ["tiktok"]})

# Flask / FastAPI / Django: pass the RAW body and the headers
def webhook(body: bytes, headers) -> int:
    try:
        event = verify_webhook(body, headers, "whsec_…")
    except WebhookError:
        return 400
    if event["type"] == "job.succeeded":
        ...
    return 200

MCP para agentes de IA

Claude, ChatGPT, Cursor e outros agentes criam e publicam vídeos com sua conta. Conectam com OAuth (você clica «Permitir») ou com uma chave de API, e sempre cotam antes de produzir.

https://mcp.creavideosconia.com/mcp

Seu próximo vídeo está a uma ideia.

Crie uma conta grátis, escolha o seu setor e veja o seu primeiro vídeo sendo produzido em cerca de 4 minutos, com o custo ao centavo.

Sem cartão · créditos de teste · PT/ES/EN