Documentação

API do Packia

Leve as IAs do Packia para o seu sistema: chat, imagem, vídeo, narração, música e planilhas, tudo por uma API REST com os créditos do seu plano.

Versão 1.2.0 · atualizada em 19/10/2026

Introdução

A API segue o padrão REST: recursos em URLs previsíveis, corpo e resposta em JSON, códigos HTTP padrão e nomes de campo em snake_case. Todas as rotas ficam sob a mesma URL base:

URL base

https://packia.com.br/api/v1

A versão faz parte do caminho (/v1). Mudanças que quebram compatibilidade saem numa versão nova; campos e rotas novas podem entrar na v1 a qualquer momento, então ignore campos que você não conhece. Toda resposta traz o header X-Request-Id, útil para falar com o suporte.

Prefere usar o Packia dentro do Claude Desktop ou do Claude Code? A mesma chave funciona no servidor MCP em https://packia.com.br/api/mcp.

Início rápido

Entre no painel e abra Perfil, aba API.
Gere uma chave e guarde em local seguro. Ela aparece uma única vez.
Salve a chave numa variável de ambiente, por exemplo PACKIA_API_KEY, e faça a primeira chamada:

Terminal

curl "https://packia.com.br/api/v1/images" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Logo minimalista de uma cafeteria, fundo branco" }'

Autenticação

Envie a chave em toda requisição no header Authorization, no formato Bearer. As chaves começam com pk_live_.

Header

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A chave tem o mesmo acesso da sua conta. Nunca coloque a chave em código que roda no navegador ou num aplicativo: chame a API a partir do seu servidor. Se uma chave vazar, revogue no Perfil e gere outra; a revogação vale na hora.

Créditos

A API consome os mesmos créditos do seu plano, nas mesmas regras do painel. Uma imagem gerada pela API custa o mesmo que uma imagem gerada no site, e tudo aparece no mesmo saldo. Consulte o saldo a qualquer momento em GET /v1/account.

Quando os créditos acabam, a API responde 402 insufficient_credits.

As criações feitas pela API também ficam salvas na sua galeria do Packia.

Erros

Respostas com status 4xx ou 5xx trazem sempre o mesmo formato. Use code para tratar o erro no seu código; message é um texto em português que pode ser mostrado ao usuário.

Resposta 402

{
  "error": {
    "code": "insufficient_credits",
    "message": "Seus créditos deste ciclo acabaram. Renove ou faça upgrade em packia.com.br.",
    "request_id": "req_Zx81Lq0aPb7cMn2V"
  }
}

Status	code	Quando acontece
400	`invalid_request`	Corpo ou parâmetro inválido. O campo param indica qual.
401	`invalid_api_key`	Chave ausente, inválida ou revogada.
402	`insufficient_credits`	Os créditos do ciclo acabaram. Recarregue ou faça upgrade no painel.
403	`plan_required`	O recurso não está incluído no seu plano.
403	`subscription_expired`	A assinatura ou o teste gratuito expirou.
404	`not_found`	Rota ou recurso inexistente (por exemplo, um job de outra conta).
409	`idempotency_in_progress`	Outra requisição com a mesma Idempotency-Key ainda está em andamento.
422	`idempotency_key_reused`	A Idempotency-Key já foi usada com outro corpo.
429	`rate_limited`	Limite de requisições por minuto atingido.
429	`daily_limit_reached`	Limite diário do teste gratuito atingido.
500	`internal_error`	Erro inesperado do Packia. Tente de novo.
502	`provider_error`	O provedor de IA falhou ou não respondeu.

Erros 429, 500 e 502 podem ser repetidos com segurança depois de alguns segundos, de preferência com a mesma Idempotency-Key.

Limites de uso

Cada chave pode fazer até 60 requisições por minuto. Acima disso a API responde 429 rate_limited. Os headers abaixo vão em toda resposta:

Header	Significado
`X-RateLimit-Limit`	Requisições permitidas por janela de 1 minuto.
`X-RateLimit-Remaining`	Quantas ainda restam na janela atual.
`X-RateLimit-Reset`	Momento em que a janela reinicia, em segundos Unix.

O chat tem ainda um limite de 30 mensagens por minuto por conta, somando o painel e a API.

Idempotência

Uma falha de rede no meio de uma geração deixa a dúvida: a requisição chegou ou não? Para repetir sem risco de cobrança dupla, envie o header Idempotency-Key com um valor único (um UUID, por exemplo) em toda rota que consome créditos.

Header

Idempotency-Key: 2b6f0f6c-1c8e-4c1e-9a7a-6f0e2a1d9b44

Se a mesma chave chegar de novo em até 24 horas com o mesmo corpo, a API devolve a resposta original sem gerar nada e sem cobrar. A resposta repetida traz o header Idempotent-Replayed: true.
Se a primeira requisição ainda estiver em andamento, a resposta é 409 idempotency_in_progress. Espere alguns segundos e tente de novo.
Reaproveitar a chave com outro corpo retorna 422 idempotency_key_reused.
Respostas 429 e 5xx não ficam guardadas, então dá para repetir com a mesma chave.

Jobs assíncronos

Vídeo e música levam alguns minutos. Por isso POST /v1/videos e POST /v1/music respondem na hora com status 202 e um objeto job. Há dois jeitos de saber quando ele termina:

Webhook (recomendado): envie webhook_url ao criar o job e receba um POST quando ele terminar.
Consulta: chame GET /v1/jobs/{id} a cada 10 a 15 segundos até o status sair de processing.

status	Significado
`processing`	A geração está em andamento.
`completed`	Pronto. O resultado está em result.
`failed`	Falhou. O motivo está em error.message.

Webhooks

Quando um job com webhook_url termina, o Packia envia um POST em JSON para essa URL. A URL precisa ser https e pública. Responda com qualquer status 2xx em até 10 segundos; faça o processamento pesado depois de responder.

Evento	Quando é enviado
`video.completed`	O vídeo ficou pronto. result.video_url traz o arquivo.
`video.failed`	A geração do vídeo falhou. error.message traz o motivo.
`music.completed`	A música ficou pronta. result.tracks traz as faixas.
`music.failed`	A geração da música falhou. error.message traz o motivo.

Corpo do evento

{
  "id": "evt_3HgK1pQ8sWb2nM0r",
  "object": "event",
  "type": "video.completed",
  "created_at": "2026-10-19T14:05:03.000Z",
  "data": {
    "id": "job_8kq2LmZ0pX4rT7vB",
    "object": "job",
    "kind": "video",
    "status": "completed",
    "result": {
      "video_url": "https://media.packia.com.br/videos/8kq2.mp4"
    },
    "error": null,
    "webhook_url": "https://seusite.com/webhooks/packia",
    "created_at": "2026-10-19T14:02:11.000Z",
    "completed_at": "2026-10-19T14:05:02.000Z"
  }
}

Verificando a assinatura

Todo evento traz o header Packia-Signature no formato t=1760882703,v1=5257a8.... O valor v1 é um HMAC SHA-256 de {t}.{corpo bruto}, usando o seu segredo de webhook (whsec_...), que fica no Perfil, aba API. Confira a assinatura antes de confiar no evento e recuse eventos com mais de 5 minutos para evitar reenvio malicioso.

Node.js (Express)

import crypto from 'crypto'

function verifyPackiaSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')))
  const age = Math.abs(Date.now() / 1000 - Number(parts.t))
  if (age > 300) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''))
}

app.post('/webhooks/packia', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyPackiaSignature(req.body.toString(), req.get('Packia-Signature') || '', process.env.PACKIA_WEBHOOK_SECRET)
  if (!ok) return res.status(400).end()

  const event = JSON.parse(req.body)
  if (event.type === 'video.completed') salvarVideo(event.data.result.video_url)
  res.status(200).end()
})

Python

import hashlib, hmac, os, time

def verify_packia_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{parts['t']}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Novas tentativas

Se a sua URL não responder 2xx, o Packia tenta de novo depois de 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas, num total de 6 tentativas. O mesmo evento pode chegar mais de uma vez: use o data.id do job para ignorar duplicados. O resultado continua disponível em GET /v1/jobs/{id} mesmo se todas as tentativas falharem.

Compatível com OpenAI

A rota POST /v1/chat/completions fala o mesmo formato de chat da OpenAI. Os SDKs oficiais da OpenAI e as ferramentas feitas para eles funcionam com o Packia trocando só a URL base e a chave. Use o id de um modelo do Packia em model.

Python (pip install openai)

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://packia.com.br/api/v1",
    api_key=os.environ["PACKIA_API_KEY"],
)

stream = client.chat.completions.create(
    model="claude-sonnet",
    messages=[{"role": "user", "content": "Crie 3 títulos para um post sobre café especial."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript (npm install openai)

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://packia.com.br/api/v1',
  apiKey: process.env.PACKIA_API_KEY,
})

const completion = await client.chat.completions.create({
  model: 'claude-sonnet',
  messages: [{ role: 'user', content: 'Crie 3 títulos para um post sobre café especial.' }],
})
console.log(completion.choices[0].message.content)

A conversa não fica salva no histórico do Packia. Mande o histórico inteiro em messages a cada chamada.
O consumo é cobrado em créditos, como no resto da API, e usage vem sempre zerado.
Só o chat de texto é compatível. Imagens na mensagem, tools e function calling não são aceitos; para imagem, vídeo e áudio use as rotas próprias da API.

Resposta com stream: true (text/event-stream)

data: {"id":"chatcmpl-Xr4bT1kQ9mZpL0aV","object":"chat.completion.chunk","created":1760882703,"model":"claude-sonnet","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-Xr4bT1kQ9mZpL0aV","object":"chat.completion.chunk","created":1760882703,"model":"claude-sonnet","choices":[{"index":0,"delta":{"content":"1. O segredo"},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-Xr4bT1kQ9mZpL0aV","object":"chat.completion.chunk","created":1760882703,"model":"claude-sonnet","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

data: [DONE]

Modelos

Os ids abaixo vão no parâmetro model. A mesma informação sai em GET /v1/models, que é a fonte mais atual para a sua integração.

Chat

model	Descrição
`gpt-5`	ChatGPT (OpenAI)
`claude-sonnet`	Claude (Anthropic)
`gemini-pro`	Gemini (Google)
`llama-4`	Llama (Meta)
`deepseek-v3`	DeepSeek
`grok-4`	Grok (xAI)
`mistral-large`	Mistral
`perplexity-sonar`	Perplexity
`copilot`	Copilot
`qwen`	Qwen
`command-r-plus`	Command R+
`poe`	Poe
`gemini-3-flash`	Gemini 3

Imagem

Todos aceitam as proporções 1:1, 16:9, 9:16, 4:3, 3:4 e 21:9.

model	Descrição	Ajustes aceitos
`gpt-image-2.5-flare`	GPT Image 2.5 (OpenAI), rápido e com alta aderência ao prompt, aceita imagens de referência	quality: low, medium, high, xhigh, max · output_format: png, jpeg, webp · até 3 referências
`gpt-image-2.5-sunburst`	GPT Image 2.5 Sunburst (OpenAI), edição mais precisa, mais lento	quality: low, medium, high, xhigh, max · output_format: png, jpeg, webp · até 3 referências
`gpt-image-2`	GPT Image 2 (OpenAI), opção mais barata, aceita imagens de referência	quality: low, medium, high · output_format: png, jpeg, webp · até 3 referências
`nano-banana-2`	Nano Banana 2 (Google), geração rápida em até 4K	resolution: 0.5K, 1K, 2K, 4K · n até 4 · até 14 referências
`grok-imagine`	Grok Imagine (xAI)	resolution: 1k, 2k · n até 4 · até 3 referências
`midjourney`	Midjourney	output_format: png, jpeg · n até 4 · enhance_prompt
`dalle3`	DALL-E 3 (OpenAI)	output_format: png, jpeg · n até 4 · enhance_prompt
`leonardo`	Leonardo AI	Só prompt e proporção
`flux`	Flux, fotorrealista e rápido	output_format: png, jpeg · n até 4 · enhance_prompt
`ideogram`	Ideogram, bom para texto dentro da imagem	rendering_speed: TURBO, BALANCED, QUALITY · n até 4
`stable-diffusion`	Stable Diffusion	Só prompt e proporção
`firefly`	Adobe Firefly	output_format: png, jpeg · n até 4 · enhance_prompt
`playground`	Playground AI	output_format: png, jpeg · n até 4 · enhance_prompt
`nano-banana-pro`	Nano Banana Pro (Google), até 4K, aceita até 14 imagens de referência	resolution: 1K, 2K, 4K · n até 4 · até 14 referências
`seedream-5`	Seedream 5 (ByteDance), aceita até 10 imagens de referência	n até 4 · até 10 referências
`qwen-image-3`	Qwen Image 3	Só prompt e proporção
`ideogram-character`	Ideogram Character, exige 1 imagem de referência do personagem	rendering_speed: TURBO, BALANCED, QUALITY · n até 4 · exige 1 referência

Vídeo

Todos aceitam as proporções 16:9, 9:16 e 1:1.

model	Modos	Duração	Resolução	Extras
`seedance`Seedance (ByteDance), modelo padrão	text, image, reference	4 a 15 s	480p, 720p	generate_audio · seed · end_image · referências: 9 imagensO modo reference exige plano Studio ou superior.
`seedance2`Seedance 2.0 Pro (ByteDance)	text, image	4 a 15 s	480p, 720p, 1080p	generate_audio · end_image · quality: standard, fastDisponível a partir do plano Starter.A variante fast vai até 720p.
`seedance25`Seedance 2.5 (ByteDance), até 30 segundos	text, image, reference	4 a 30 s	480p, 720p, 1080p	generate_audio · referências: 30 imagens, 10 vídeos, 10 áudiosDisponível a partir do plano Starter.
`kling`Kling 3 Pro	text, image	3 a 15 s	Não se aplica	negative_prompt
`kling26`Kling 2.6 Pro	text, image	5, 10 s	Não se aplica	generate_audio · negative_prompt · end_image
`klingo3`Kling O3 Pro, só a partir de imagem	image	4, 5, 6, 8, 10, 15 s	Não se aplica	generate_audio · end_image
`veo`Veo 3.1 (Google), até 4K	text, image, reference	4, 6, 8 s	720p, 1080p, 4k	generate_audio · negative_prompt · seed · quality: standard, fast · referências: 3 imagensNo modo reference a duração é sempre 8 segundos.
`wan`Wan 2.7	text, image	4, 5, 6, 8, 10, 12 s	720p, 1080p	negative_prompt · seed · optimize_prompt · end_image
`minimax`MiniMax Hailuo 2.3	text, image	6, 10 s	Não se aplica	optimize_prompt
`pixverse`PixVerse V6	text, image	3, 5, 8, 10 s	540p, 720p, 1080p	generate_audio · negative_prompt · optimize_prompt · style · style: anime, 3d_animation, clay, comic, cyberpunk
`ltx`LTX-2.3, até 2160p	text, image	6, 8, 10 s	1080p, 1440p, 2160p	generate_audio · end_image · fps · quality: standard, fast · fps: 24, 25, 48, 50
`happyhorse`Happy Horse 1.1	text, image, reference	3, 5, 8, 10, 15 s	720p, 1080p	seed · referências: 9 imagens
`pika`Pika 2.2	text, image	5, 10 s	720p, 1080p	negative_prompt · seed
`grok`Grok Imagine Video (xAI)	text, image	1 a 15 s	480p, 720p

Música

model	Descrição
`V6`	Suno V6, modelo padrão
`V6_WILD`	Suno V6 Wild
`V6_MINI`	Suno V6 Mini
`V5_5`	Suno V5.5
`V5`	Suno V5
`V4_5PLUS`	Suno V4.5+
`V4_5ALL`	Suno V4.5 All
`V4_5`	Suno V4.5
`V4`	Suno V4, letras de até 3000 caracteres

Conta

Consultar conta

GET/v1/account

Retorna o plano e o saldo de créditos da conta dona da chave. Use antes de uma geração cara para conferir se há saldo.

Esta rota não recebe parâmetros.

credits vem null no teste gratuito, que usa daily_limit (teto diário em dólares) no lugar.

curl "https://packia.com.br/api/v1/account" \
  -H "Authorization: Bearer $PACKIA_API_KEY"

Resposta 200

{
  "object": "account",
  "plan": "studio",
  "subscription_expires_at": "2026-11-19T12:00:00.000Z",
  "credits": {
    "balance": 1840,
    "monthly_allowance": 3000,
    "renews_at": "2026-11-19T12:00:00.000Z"
  },
  "daily_limit": null
}

Listar modelos

GET/v1/models

Lista os modelos de chat, imagem, vídeo e música, com o que cada um aceita: proporções, durações, resoluções, modos e parâmetros extras. O campo id é o valor aceito no parâmetro model das outras rotas.

Parâmetros de consulta

Campo	Tipo	Descrição
`type`	string	Filtra por chat, image, video ou music.

Em modelos de imagem, parameters traz os valores aceitos de cada ajuste e, em premium, os que exigem plano Pro, Studio, Creator ou Vitalício.

curl "https://packia.com.br/api/v1/models?type=video" \
  -H "Authorization: Bearer $PACKIA_API_KEY"

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "veo",
      "object": "model",
      "type": "video",
      "description": "Veo 3.1 (Google), até 4K",
      "modes": [
        "text",
        "image",
        "reference"
      ],
      "durations": [
        4,
        6,
        8
      ],
      "resolutions": [
        "720p",
        "1080p",
        "4k"
      ],
      "aspect_ratios": [
        "16:9",
        "9:16",
        "1:1"
      ],
      "quality": [
        "standard",
        "fast"
      ],
      "references": {
        "images": 3
      },
      "parameters": [
        "generate_audio",
        "negative_prompt",
        "seed"
      ],
      "notes": [
        "No modo reference a duração é sempre 8 segundos."
      ]
    }
  ]
}

Texto

Conversar com IA

POST/v1/chat

Envia o histórico da conversa e recebe a resposta do modelo. O histórico vai inteiro em messages, e a última mensagem precisa ser do usuário.

Corpo da requisição

Campo	Tipo	Descrição
`messages`obrigatório	array	Lista de mensagens { role, content }. role é user ou assistant. Máximo de 200 mensagens.
`model`	string	Id de um modelo de chat. Padrão: gpt-5.
`system`	string	Instrução de sistema para orientar o tom e o formato da resposta.
`conversation_id`	string (uuid)	Id devolvido numa resposta anterior. Agrupa as mensagens na mesma conversa do histórico do Packia.
`stream`	boolean	Quando true, a resposta chega aos poucos via Server-Sent Events. Padrão: false.

Com stream: true, o servidor envia eventos delta ({ "text": "..." }) e termina com done ({ "model", "conversation_id" }). Se algo falhar no meio, chega um evento error com code e message.

O chat tem um limite próprio de 30 mensagens por minuto por conta, além do limite geral da chave.

curl -X POST "https://packia.com.br/api/v1/chat" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-sonnet",
  "system": "Responda em português, de forma direta.",
  "messages": [
    {
      "role": "user",
      "content": "Crie 3 títulos para um post sobre café especial."
    }
  ]
}'

Resposta 200

{
  "id": "chat_Qm9vZ2xlU2VhcmNo",
  "object": "chat.completion",
  "model": "claude-sonnet",
  "conversation_id": "5f1c2a8e-3b7d-4e0a-9c61-2d8f4b7a1e30",
  "message": {
    "role": "assistant",
    "content": "1. O segredo do café especial..."
  }
}

Resposta com stream: true (text/event-stream)

event: delta
data: {"text":"1. O segredo"}

event: delta
data: {"text":" do café especial..."}

event: done
data: {"model":"claude-sonnet","conversation_id":"5f1c2a8e-3b7d-4e0a-9c61-2d8f4b7a1e30"}

Chat compatível com OpenAI

POST/v1/chat/completions

Mesmo chat da rota anterior, no formato de chat completions da OpenAI. Serve para usar os SDKs oficiais da OpenAI e ferramentas feitas para eles, trocando só a URL base e a chave.

Corpo da requisição

Campo	Tipo	Descrição
`messages`obrigatório	array	Lista de mensagens { role, content }. role é system, developer, user ou assistant; system e developer viram a instrução de sistema. content é texto ou uma lista de partes { type: "text", text }. Máximo de 200 mensagens.
`model`	string	Id de um modelo de chat do Packia. Padrão: gpt-5.
`stream`	boolean	Quando true, a resposta chega em chunks chat.completion.chunk e termina com data: [DONE]. Padrão: false.
`stream_options`	object	Com { "include_usage": true }, o último chunk antes do [DONE] traz usage.

A conversa não fica salva no histórico do Packia. Mande o histórico inteiro em messages a cada chamada.

usage vem sempre zerado: o consumo é cobrado em créditos, como no resto da API.

Parâmetros como temperature, max_tokens e top_p são aceitos e ignorados. tools, functions, mensagens com role tool, partes que não são texto e n diferente de 1 retornam 400.

Nesta rota, os erros trazem também error.type no padrão da OpenAI, como invalid_request_error e insufficient_quota.

curl -X POST "https://packia.com.br/api/v1/chat/completions" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-sonnet",
  "messages": [
    {
      "role": "system",
      "content": "Responda em português, de forma direta."
    },
    {
      "role": "user",
      "content": "Crie 3 títulos para um post sobre café especial."
    }
  ]
}'

Resposta 200

{
  "id": "chatcmpl-Xr4bT1kQ9mZpL0aV",
  "object": "chat.completion",
  "created": 1760882703,
  "model": "claude-sonnet",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. O segredo do café especial...",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Melhorar prompt

POST/v1/prompts/improveAceita Idempotency-Key

Reescreve e enriquece um prompt curto para que ele renda mais na geração de imagem, vídeo, música ou texto.

Corpo da requisição

Campo	Tipo	Descrição
`prompt`obrigatório	string	Prompt original. Máximo de 5000 caracteres.
`context`	string	Uso do prompt: general, image, video, music, avatar ou chat. Padrão: general.

curl -X POST "https://packia.com.br/api/v1/prompts/improve" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "gato astronauta",
  "context": "image"
}'

Resposta 200

{
  "object": "prompt",
  "context": "image",
  "prompt": "Um gato malhado de traje espacial branco flutuando dentro de uma estação orbital, luz suave da Terra pela janela..."
}

Imagem e áudio

Gerar imagem

POST/v1/imagesAceita Idempotency-Key

Gera uma ou mais imagens a partir de um prompt de texto, ou edita a partir de imagens de referência. A resposta só volta quando a imagem está pronta. Cada modelo aceita ajustes diferentes; veja a seção Modelos ou GET /v1/models.

Corpo da requisição

Campo	Tipo	Descrição
`prompt`obrigatório	string	Descrição da imagem. Máximo de 5000 caracteres.
`model`	string	Id de um modelo de imagem. Padrão: gpt-image-2.5-flare.
`aspect_ratio`	string	1:1, 16:9, 9:16, 4:3, 3:4 ou 21:9. Padrão: 1:1.
`quality`	string	Modelos GPT Image. low, medium ou high; no GPT Image 2.5 também xhigh e max.
`resolution`	string	Nano Banana: 0.5K, 1K, 2K ou 4K (o Pro não tem 0.5K). Grok Imagine: 1k ou 2k.
`output_format`	string	png, jpeg ou webp nos modelos GPT Image; png ou jpeg nos modelos Flux.
`rendering_speed`	string	Modelos Ideogram: TURBO, BALANCED ou QUALITY.
`n`	integer	Quantidade de imagens por chamada, de 1 a 4, nos modelos que aceitam lote.
`enhance_prompt`	boolean	Modelos Flux: reescreve o prompt automaticamente antes de gerar.
`reference_images`	array de string	Imagens de referência para edição ou personagem: URL https pública ou data URL base64. Até 3 (GPT Image, Grok), 10 (Seedream 5) ou 14 (Nano Banana). Obrigatório no ideogram-character (1 imagem).

Enviar um parâmetro que o modelo não aceita retorna 400 invalid_request com o nome do parâmetro em param.

Ajustes premium (qualidade xhigh e max, high no GPT Image 2, resolução 2K e 4K, QUALITY no Ideogram e n acima de 1) exigem plano Pro, Studio, Creator ou Vitalício. No Starter a imagem é gerada com o ajuste padrão do modelo.

Prefira URLs a base64: o corpo da requisição tem limite de 4,5 MB.

Alguns modelos devolvem a imagem embutida: nesse caso o item vem com b64_json e mime_type no lugar de url.

curl -X POST "https://packia.com.br/api/v1/images" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Coloque o produto sobre uma mesa de mármore, luz de estúdio",
  "model": "nano-banana-2",
  "aspect_ratio": "4:3",
  "resolution": "1K",
  "n": 1,
  "reference_images": [
    "https://seusite.com/produto.png"
  ]
}'

Resposta 200

{
  "object": "image.generation",
  "model": "nano-banana-2",
  "data": [
    {
      "url": "https://media.packia.com.br/images/abc123.png"
    }
  ]
}

Listar vozes

GET/v1/voices

Lista as vozes disponíveis para narração, incluindo as vozes clonadas da sua conta.

Esta rota não recebe parâmetros.

curl "https://packia.com.br/api/v1/voices" \
  -H "Authorization: Bearer $PACKIA_API_KEY"

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "21m00Tcm4TlvDq8ikWAM",
      "object": "voice",
      "name": "Rachel",
      "description": "Feminina, calma"
    }
  ]
}

Gerar narração

POST/v1/audio/speechAceita Idempotency-Key

Converte texto em áudio (text-to-speech) e devolve a URL do arquivo MP3.

Corpo da requisição

Campo	Tipo	Descrição
`text`obrigatório	string	Texto a narrar. Máximo de 5000 caracteres.
`voice_id`	string	Id de uma voz de GET /voices. Padrão: Rachel.
`speed`	number	Velocidade, de 0.7 a 1.2. Padrão: 1.0.
`stability`	number	Estabilidade da voz, de 0 a 1. Padrão: 0.5.
`similarity`	number	Fidelidade à voz original, de 0 a 1. Padrão: 0.75.
`style`	number	Exagero de estilo, de 0 a 1. Padrão: 0.

curl -X POST "https://packia.com.br/api/v1/audio/speech" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "text": "Bem-vindo ao Packia.",
  "voice_id": "21m00Tcm4TlvDq8ikWAM",
  "speed": 1
}'

Resposta 200

{
  "object": "audio.speech",
  "audio_url": "https://media.packia.com.br/voice/xyz789.mp3"
}

Gerar planilha

POST/v1/spreadsheetsAceita Idempotency-Key

Gera uma planilha Excel (.xlsx) a partir de uma descrição. O arquivo volta em base64 no próprio corpo da resposta.

Corpo da requisição

Campo	Tipo	Descrição
`prompt`obrigatório	string	Descrição da planilha. Máximo de 6000 caracteres.

curl -X POST "https://packia.com.br/api/v1/spreadsheets" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Controle de fluxo de caixa mensal com entradas, saídas e saldo acumulado"
}'

Resposta 200

{
  "object": "spreadsheet",
  "file_name": "fluxo-de-caixa.xlsx",
  "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "file_base64": "UEsDBBQABgAIAAAAIQ...",
  "sheets": [
    {
      "name": "Fluxo de caixa",
      "rows": 12,
      "columns": 5
    }
  ]
}

Vídeo e música

Gerar vídeo

POST/v1/videosAceita Idempotency-Key

Inicia a geração de um vídeo a partir de texto, de uma imagem ou de referências. A resposta volta na hora com status 202 e um job; o vídeo fica pronto em alguns minutos. Cada modelo aceita modos, durações e ajustes diferentes; veja a seção Modelos ou GET /v1/models?type=video.

Corpo da requisição

Campo	Tipo	Descrição
`prompt`obrigatório	string	Descrição do vídeo. Máximo de 2500 caracteres.
`model`	string	Id de um modelo de vídeo. Padrão: seedance.
`mode`	string	text, image ou reference. Se não vier, a API deduz pelos campos enviados.
`aspect_ratio`	string	16:9, 9:16 ou 1:1. Padrão: 16:9.
`duration`	integer	Duração em segundos, dentro do que o modelo aceita. Padrão: 5, ou o valor mais próximo do modelo.
`resolution`	string	Uma das resoluções do modelo, por exemplo 720p ou 1080p.
`quality`	string	standard ou fast, nos modelos que têm variante fast (seedance2, veo, ltx).
`image`	string	Modo image: imagem inicial, como URL https pública ou data URL base64. Mínimo de 300x300 pixels.
`end_image`	string	Modo image: imagem final, nos modelos que aceitam.
`reference_images`	array de string	Modo reference: imagens de referência (seedance, seedance25, veo, happyhorse).
`reference_videos`	array de string	Modo reference no seedance25: até 10 vídeos mp4 ou mov.
`reference_audios`	array de string	Modo reference no seedance25: até 10 áudios mp3 ou wav.
`generate_audio`	boolean	Gera trilha e som junto com o vídeo, nos modelos que aceitam.
`negative_prompt`	string	O que evitar no vídeo, nos modelos que aceitam.
`seed`	integer	Semente para resultados reproduzíveis, nos modelos que aceitam.
`style`	string	pixverse: anime, 3d_animation, clay, comic ou cyberpunk.
`optimize_prompt`	boolean	wan, minimax e pixverse: liga ou desliga a otimização automática do prompt.
`fps`	integer	ltx: 24, 25, 48 ou 50 quadros por segundo.
`webhook_url`	string	URL https pública que recebe o evento quando o job terminar.

Duração acima de 5 segundos exige plano Pro, Studio, Creator ou Vitalício. No Starter o vídeo sai com 5 segundos, ou com a duração mais próxima que o modelo aceita.

Nos modelos seedance2, seedance25 e pika, 1080p segue a mesma regra; no Starter o vídeo sai em 720p.

seedance2 e seedance25 estão disponíveis a partir do plano Starter, e o modo reference do seedance a partir do Studio. Fora disso a resposta é 403 plan_required.

Enviar um parâmetro, modo, duração ou resolução que o modelo não aceita retorna 400 invalid_request com o campo em param.

Prefira URLs a base64 nas imagens: o corpo da requisição tem limite de 4,5 MB.

curl -X POST "https://packia.com.br/api/v1/videos" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Drone sobrevoando uma plantação de café ao nascer do sol",
  "model": "veo",
  "aspect_ratio": "9:16",
  "duration": 6,
  "resolution": "1080p",
  "generate_audio": true,
  "webhook_url": "https://seusite.com/webhooks/packia"
}'

Resposta 202

{
  "id": "job_8kq2LmZ0pX4rT7vB",
  "object": "job",
  "kind": "video",
  "status": "processing",
  "result": null,
  "error": null,
  "webhook_url": "https://seusite.com/webhooks/packia",
  "created_at": "2026-10-19T14:02:11.000Z",
  "completed_at": null
}

Gerar música

POST/v1/musicAceita Idempotency-Key

Inicia a geração de uma música a partir de uma descrição ou de uma letra. Funciona como o vídeo: devolve um job e avisa por webhook.

Corpo da requisição

Campo	Tipo	Descrição
`prompt`obrigatório	string	Descrição da música ou letra completa.
`instrumental`	boolean	Gera sem vocais. Padrão: false.
`title`	string	Título da música.
`style`	string	Estilo ou gênero, por exemplo "bossa nova, violão".
`model`	string	V6, V6_WILD, V6_MINI, V5_5, V5, V4_5PLUS, V4_5ALL, V4_5 ou V4. Padrão: V6.
`negative_tags`	string	Estilos ou elementos a evitar.
`vocal_gender`	string	m ou f, para a voz principal.
`style_weight`	number	De 0 a 1: o quanto o estilo pedido pesa no resultado.
`weirdness`	number	De 0 a 1: o quanto a música pode fugir do convencional.
`audio_weight`	number	De 0 a 1: peso do áudio de referência, quando houver.
`webhook_url`	string	URL https pública que recebe o evento quando o job terminar.

curl -X POST "https://packia.com.br/api/v1/music" \
  -H "Authorization: Bearer $PACKIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Jingle alegre para uma cafeteria de bairro",
  "model": "V6",
  "style": "samba, cavaquinho",
  "instrumental": false
}'

Resposta 202

{
  "id": "job_Vt3nQ9sLw2aYc6Hd",
  "object": "job",
  "kind": "music",
  "status": "processing",
  "result": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-10-19T14:05:40.000Z",
  "completed_at": null
}

Consultar job

GET/v1/jobs/{id}

Retorna o estado atual de um job de vídeo ou música. status vai de processing para completed ou failed.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	string	Id do job, no formato job_...

Em música, result vem como { tracks: [{ id, title, audio_url, image_url, duration }] }. Cada geração costuma trazer duas faixas.

Se não usar webhook, consulte a cada 10 a 15 segundos. Um job que não termina em 24 horas vira failed.

curl "https://packia.com.br/api/v1/jobs/job_8kq2LmZ0pX4rT7vB" \
  -H "Authorization: Bearer $PACKIA_API_KEY"

Resposta 200

{
  "id": "job_8kq2LmZ0pX4rT7vB",
  "object": "job",
  "kind": "video",
  "status": "completed",
  "result": {
    "video_url": "https://media.packia.com.br/videos/8kq2.mp4"
  },
  "error": null,
  "webhook_url": "https://seusite.com/webhooks/packia",
  "created_at": "2026-10-19T14:02:11.000Z",
  "completed_at": "2026-10-19T14:05:02.000Z"
}

Biblioteca

Listar criações

GET/v1/creations

Lista as criações da galeria da conta, da mais recente para a mais antiga. Inclui o que foi feito pelo painel e pela API.

Parâmetros de consulta

Campo	Tipo	Descrição
`kind`	string	Filtra por image, video, audio ou doc.
`page`	integer	Página, começando em 1. Padrão: 1.
`limit`	integer	Itens por página, de 1 a 60. Padrão: 20.

curl "https://packia.com.br/api/v1/creations?kind=image&limit=2" \
  -H "Authorization: Bearer $PACKIA_API_KEY"

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "b1d0e7c2-6a4f-4f1e-8a51-0c9e2d7f3a11",
      "object": "creation",
      "kind": "image",
      "tool": "flux",
      "title": "Xícara de café sobre mesa de madeira",
      "url": "https://media.packia.com.br/images/abc123.png",
      "thumbnail_url": null,
      "created_at": "2026-10-19T13:58:20.000Z"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 148,
  "has_more": true
}

Changelog

v1.2.019/10/2026

POST /v1/chat/completions no formato da OpenAI, com e sem stream, para usar os SDKs oficiais da OpenAI apontando para o Packia. A conversa não fica salva no histórico.

v1.1.019/10/2026

GET /v1/models lista também vídeo e música, com o que cada modelo aceita, e filtra por type.
Imagem: modelos nano-banana-pro, seedream-5, qwen-image-3 e ideogram-character, proporções 4:3 e 3:4, e os parâmetros quality, resolution, output_format, rendering_speed, n, enhance_prompt e reference_images.
Vídeo: 14 modelos, modos text, image e reference, e os parâmetros resolution, quality, generate_audio, negative_prompt, seed, style, optimize_prompt, fps, image, end_image e referências.
Música: escolha entre os 9 modelos Suno e os ajustes negative_tags, vocal_gender, style_weight, weirdness e audio_weight.

v1.0.019/10/2026

Lançamento da API v1: chat, imagem, melhoria de prompt, narração, planilha, vídeo, música, jobs, criações, modelos e conta.
Idempotency-Key em todas as rotas que consomem créditos.
Webhooks assinados com HMAC SHA-256 para jobs de vídeo e música.

Dúvidas ou ideias para a API? Fale com a gente pelo WhatsApp do suporte .