Seedream 5.0 Pro API

Recursos

Preços e créditos

Os preços abaixo são por imagem retornada. A geração comum reserva uma imagem. O desmembramento de camadas reserva 17 imagens, cobra a quantidade real retornada (incluindo a imagem base) e devolve os créditos não utilizados ao seu saldo original. Tarefas que falharem são totalmente reembolsadas.

Na resolução padrão de 2K, o desmembramento de camadas reserva 136 créditos. Se quatro imagens forem retornadas, a cobrança final será de 32 créditos e 104 créditos serão devolvidos.

Não há suporte para idempotência de requisições. Cada chamada POST válida cria uma nova tarefa faturável. Se o resultado de um envio for incerto, consulte o taskId retornado; reenviar o POST pode criar outra tarefa.

Autenticação

Crie uma chave de API no painel. A chave completa é exibida apenas uma vez. Guarde-a com segurança no seu servidor e envie-a como um token Bearer em cada requisição.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Defina a variável de ambiente SEEVIO_API_KEY antes de rodar os exemplos. Os exemplos em JavaScript rodam no servidor com Node.js; os de Python utilizam a biblioteca requests.

Corpo da requisição

Parâmetros de entrada

Cada solicitação cria uma tarefa. As funções de texto para imagem e imagem para imagem retornam uma única imagem; a decomposição de camadas (layer-decomposition) retorna de 1 a 17 imagens, incluindo a imagem base. Não envie o parâmetro aspect_ratio em solicitações de decomposição de camadas.

Início rápido

Envie esta requisição simplificada, salve o taskId retornado e use o exemplo de consulta abaixo. O valor de créditos indicado na resposta de criação é o montante reservado.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Exemplo de resposta de criação de tarefa

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

Texto para imagem

Gere imagens, edite referências ou desmembre uma imagem em camadas com a sua chave de API do Seevio. As tarefas são executadas de forma assíncrona; salve o taskId e consulte o endpoint de tarefas ou receba um callback.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Imagem para imagem

Para edição de imagem, defina generation_type como image-to-image e forneça as image_urls. Todos os outros parâmetros seguem a mesma estrutura padrão.

Substitua as URLs de exemplo de media.com pelos seus próprios arquivos HTTPS públicos. Os links de exemplo servem apenas para ilustrar a estrutura da requisição e não representam arquivos reais para download.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Desmembramento de camadas

Defina generation_type como layer-decomposition e forneça exatamente um URL de imagem. Omita aspect_ratio. output_format controla apenas o formato da imagem base. As camadas separadas são sempre retornadas como PNG com transparência preservada. Salve todos os URLs retornados em data.results.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

O desmembramento de camadas pode retornar várias URLs de imagem em data.results: a imagem base e as camadas separadas. Cada URL aponta para uma imagem distinta. O número de resultados varia conforme a tarefa (de 1 a 17 imagens no total); processe todo o array em vez de apenas data.results[0]. Tanto a consulta de tarefa concluída quanto o webhook de conclusão contêm este array. A resposta de criação inicial contém o taskId e os créditos reservados, não as URLs das imagens.

Exemplo de resposta de criação de tarefa

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

Desmembramento de camadas concluído: várias URLs de imagem

Esta resposta ilustrativa exibe quatro imagens de saída: uma imagem base e três camadas. Sua tarefa pode retornar uma quantidade diferente. Na resolução de 2K solicitada, o campo credits representa a cobrança final pelas quatro imagens; a parte não utilizada da reserva inicial de 17 imagens foi devolvida.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Processe todas as imagens retornadas

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

Consultar tarefa

Substitua o ID de exemplo pelo taskId recebido no retorno da criação. As consultas só retornam tarefas de propriedade do usuário associado à chave de API; IDs inexistentes ou de terceiros retornam HTTP 404.

Recomendamos consultar a cada 10 ou 20 segundos inicialmente, aplicar recuo (backoff) caso receba HTTP 429 e parar assim que o status for completed ou failed. Para produção, prefira webhooks. Cada exemplo abaixo executa uma consulta única.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Na fila

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Concluído

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Falhou

Quando a consulta retornar status=failed, significa que a geração falhou. Verifique o motivo em failed_reason e o resultado do estorno em billing_status. Neste exemplo, refunded indica que os créditos foram devolvidos. O campo credits mantém o valor original reservado, e a resposta não inclui data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Os links de resultado ficam disponíveis por 30 dias após o armazenamento. Após a expiração, o campo results ficará vazio.

Webhooks

Defina o callback_url na requisição de criação para receber um POST em JSON assim que a tarefa for concluída ou falhar. Responda com status 2xx em até 15 segundos. Envios malsucedidos serão reentados; trate as requisições de forma idempotente utilizando o ID da tarefa.

O seu endpoint de callback deve aceitar requisições POST com um corpo no formato JSON (Content-Type: application/json).

Criar tarefa contendo callback

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Os callbacks utilizam a estrutura de resposta da consulta de tarefas; as notificações de falha reembolsadas também incluem credits_refunded no nível superior. Utilize id para identificar a tarefa e status para distinguir as concluídas das malsucedidas. As notificações podem se repetir: processe-as de forma idempotente por id e status. Os callbacks não são assinados; verifique a tarefa usando o endpoint de consulta autenticado. Falhas de entrega não geram reembolso de tarefas concluídas com sucesso.

Tarefa concluída: payload de callback de sucesso

created_at indica a criação do evento; task_created_at indica a criação da tarefa, em segundos Unix. Os exemplos mostram os campos recomendados; as respostas podem incluir campos adicionais.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Falha na tarefa: payload de callback de erro

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

Exemplo de código receptor

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

Este exemplo em Next.js lê o corpo do callback em JSON e trata diretamente as tarefas concluídas e com falha. Recomendamos implementar persistência e eliminação de duplicidades por ID de tarefa na sua aplicação, além de enfileirar processos demorados antes de responder ao callback.

Erros

Erros de requisição retornam um objeto contendo code e message. Uma tarefa aceita com sucesso ainda pode falhar posteriormente durante o processamento; monitore seu status por consulta ou configure um callback de falha.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Os erros usam error.code e error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. O erro 402 insufficient_credits significa que seus créditos disponíveis são insuficientes para esta requisição.

Limites de requisição

Criação de tarefas: por padrão, cada chave de API permite até 100 requisições por minuto. No momento, limites personalizados não estão disponíveis.

Consulta de tarefas: por padrão, cada chave de API permite até 120 requisições por minuto. As requisições de consulta e de criação de tarefas são contabilizadas separadamente.

As requisições de criação de imagem e vídeo compartilham o mesmo limite de taxa (rate limit) da chave de API.

Respostas com HTTP 429 incluem o cabeçalho Retry-After: 60 para criação e Retry-After: 5 para consultas. Implemente recuo gradual (backoff) e evite consultas mais frequentes do que o recomendado.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}