Instruções de Integração da API de Geração de Imagens SeeDream

Este documento apresentará uma instrução de integração da API de Geração de Imagens SeeDream, que pode gerar imagens oficiais da SeeDream através da entrada de parâmetros personalizados.

Processo de Solicitação

Para usar a API de Geração de Imagens SeeDream, primeiro acesse o console Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login. Após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar individualmente para cada serviço. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no console.

📘 Documentação Completa: API de Geração de Imagens SeeDream →

Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em inserir a palavra-chave prompt, a ação action e o tamanho da imagem size, para obter o resultado processado. Primeiro, é necessário passar um campo action, cujo valor deve ser generate, e em seguida, precisamos inserir a palavra-chave, cujo conteúdo específico é o seguinte:

Podemos ver que aqui configuramos os Cabeçalhos da Solicitação, incluindo:

accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Solicitação, incluindo:

prompt: palavra-chave.
model: modelo de geração, padrão doubao-seedream-5-0-260128 (SeeDream 5.0 Lite, o mais recente). Suporta doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128 (também aceita o nome alternativo oficial doubao-seedream-5-0-lite-260128), doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. O doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) é o modelo de imagem única, gerando apenas uma imagem, não suporta geração de múltiplas imagens (sequential_image_generation), streaming (stream) ou pesquisa na web (tools). O model deve ser passado como uma string completa do modelo (como doubao-seedream-5-0-260128), passar abreviações como doubao-seedream-5.0-lite resultará em erro 400.
image: informações da imagem de entrada, suportando URL ou codificação Base64. doubao-seedream-5-0-pro-260628 suporta entrada de uma ou várias imagens (de 2 a 10 imagens, a partir da segunda imagem é cobrada por imagem), doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 suportam entrada de uma ou várias imagens.
size: especifica as informações de tamanho da imagem gerada, suportando as seguintes duas maneiras, que não podem ser misturadas. Modo 1 | Especifica a resolução da imagem gerada e descreve a proporção largura-altura da imagem em linguagem natural no prompt. As predefinições suportadas variam entre os modelos: doubao-seedream-5-0-pro-260628 suporta 1K/1.5K/2K; doubao-seedream-5-0-260128 suporta 2K/3K/4K; doubao-seedream-4-5-251128 suporta apenas 2K/4K; doubao-seedream-4-0-250828 suporta 1K/2K/4K. Modo 2 | Especifica os valores de pixels da largura e altura da imagem gerada: padrão 2048x2048, o total de pixels e a proporção largura-altura variam conforme o modelo (por exemplo, o total de pixels do 5.0 Pro varia de [921600, 4624220], o limite inferior do total de pixels do 5.0 Lite / 4.5 é 3.686.400, e do 4.0 é 921.600).
sequential_image_generation: geração de múltiplas imagens: uma série de imagens relacionadas geradas com base no conteúdo que você inseriu. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 suportam esse parâmetro, padrão disabled.
stream: controla se o modo de saída em streaming está ativado. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 suportam esse parâmetro, padrão é false.
response_format: especifica o formato de retorno da imagem gerada. O padrão é url, também suporta b64_json.
watermark: se deve adicionar uma marca d’água à imagem gerada. O padrão é true.
output_format: especifica o formato do arquivo da imagem gerada, suportando jpeg (padrão) e png. Apenas doubao-seedream-5-0-pro-260628 e doubao-seedream-5-0-260128 suportam.
tools: configura os ferramentas que o modelo deve chamar, atualmente suporta web_search (pesquisa na web). Apenas o SeeDream 5.0 Lite suporta.
optimize_prompt_options: configuração de otimização da palavra-chave. 5.0 Pro suporta standard/fast; 5.0 Lite e 4.5 suportam apenas standard; 4.0 suporta standard/fast.
background: apenas edição de imagem única do 5.0 Pro suporta. transparent requer a entrada de uma PNG com canal alfa, e o output_format deve ser png; opaque é um fundo normal opaco.
layer_decomposition: apenas 5.0 Pro suporta. Quando definido como true, deve-se inserir uma PNG/JPEG, podendo não passar prompt para divisão automática, ou usar linguagem natural/<bbox> para especificar elementos; size suporta auto/1K/1.5K/2K. Este modo não pode ser usado com geração de múltiplas imagens, streaming, pesquisa na web ou background.
callback_url: URL para onde os resultados devem ser retornados.
async: se deve processar em modo assíncrono. Quando definido como true, a interface retorna imediatamente task_id, sem necessidade de fornecer callback_url, e em seguida, você pode consultar os resultados através de /seedream/tasks.

Após a seleção, você pode notar que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e aqui obtivemos o seguinte resultado:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "Uma foto de estúdio fotorealista de um frasco de perfume de vidro fosco sobre ardósia preta molhada, luz chave de softbox única, gotas de água, fundo escuro e sombrio, 85mm macro.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

Os resultados retornados têm vários campos, conforme descrito abaixo:

success, o estado atual da tarefa de geração de vídeo.
task_id, o ID da tarefa de geração de vídeo atual.
trace_id, o ID de rastreamento da geração de vídeo atual.
data, a lista de resultados da tarefa de geração de imagem atual.
- image_url, o link da tarefa de geração de imagem atual.
- prompt, a palavra-chave.
- size: os pixels da imagem gerada.

Podemos ver que recebemos informações de imagem satisfatórias, e só precisamos obter a imagem gerada do SeeDream com base no link da imagem no resultado data. Além disso, se você quiser gerar o código correspondente, pode copiá-lo diretamente, como o código CURL abaixo:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-260128",
  "prompt": "Uma foto de estúdio fotorealista de um frasco de perfume de vidro fosco sobre ardósia preta molhada, luz chave de softbox única, gotas de água, fundo escuro e sombrio, 85mm macro."
}'

Editar Tarefa de Imagem

Se você quiser editar uma imagem, primeiro o parâmetro image deve conter o link da imagem que precisa ser editada.

model: o modelo utilizado para a tarefa de edição de imagem, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 suportam entrada de imagem.
image: faça upload da imagem que precisa ser editada, uma ou mais.

Um exemplo de preenchimento é o seguinte:

Código correspondente:

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Mantenha a pose do modelo e a forma do vestido líquido inalteradas. Mude o material da roupa de metal prateado para água completamente transparente (ou vidro). Através do fluxo do líquido, os detalhes da pele do modelo são visíveis. O efeito de luz e sombra muda de reflexão para refração.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Ao clicar em executar, você pode descobrir que receberá imediatamente um resultado, como abaixo:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Mantenha a pose do modelo e a forma do vestido líquido inalteradas. Mude o material da roupa de metal prateado para água completamente transparente (ou vidro). Através do fluxo do líquido, os detalhes da pele do modelo são visíveis. O efeito de luz e sombra muda de reflexão para refração.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Podemos ver que o efeito gerado é o efeito de edição da imagem original, e o resultado é semelhante ao mencionado acima.

Desdobramento de Camadas (Seedream 5.0 Pro)

O desdobramento de camadas dividirá uma imagem de entrada em 1 imagem de fundo e até 16 camadas PNG transparentes que podem ser editadas independentemente. A seguinte solicitação permite que o modelo reconheça automaticamente os principais elementos; se você quiser especificar elementos, pode adicionar prompt, ou também pode usar coordenadas normalizadas <bbox> nas palavras-chave.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

Os data retornados são organizados por z_index de baixo para cima. O z_index da imagem de fundo é 0; as camadas também incluem name, description e bounding_box.absolute/normalized. Ao reorganizar usando coordenadas absolutas, as camadas são escalonadas para [right-left, bottom-top], colocadas em [left, top], e depois empilhadas em ordem crescente de z_index. Se qualquer camada falhar na geração, toda a divisão falhará.

Saída em Fluxo

Lite/4.x define stream: true, e o cabeçalho da solicitação usa accept: application/x-ndjson. A interface retorna linha por linha image_generation.partial_succeeded ou image_generation.partial_failed, e finalmente retorna um evento único image_generation.completed e o usage final; apenas o evento de conclusão aciona uma cobrança. O modo de fluxo não pode ser usado com async ou callback_url.

Retorno Assíncrono

Como o tempo de geração da API SeeDream Images Generation é relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo tempo, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema, portanto, esta API também oferece suporte a retorno assíncrono. O fluxo geral é: quando o cliente inicia a solicitação, especifica um campo callback_url adicional, após o cliente fazer a solicitação da API, a API retornará imediatamente um resultado, contendo um campo de informação task_id, representando o ID da tarefa atual. Quando a tarefa for concluída, o resultado da imagem gerada será enviado para o callback_url especificado pelo cliente em formato JSON POST, que também inclui o campo task_id, assim o resultado da tarefa pode ser associado pelo ID. Se você não tiver um endereço público disponível para retorno, também pode não especificar callback_url, mas definir o campo async como true na solicitação. Nesse caso, a interface também retornará imediatamente o task_id, mas não enviará o resultado, você precisará levar esse task_id para chamar a interface /seedream/tasks para consultar o status da tarefa e obter o resultado final. Abaixo, vamos entender como operar isso através de um exemplo. Ao clicar em executar, você pode descobrir que receberá imediatamente um resultado, como abaixo:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

O conteúdo é o seguinte:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Mantenha a pose do modelo e a forma fluida da vestimenta líquida inalteradas. Altere o material da roupa de metal prateado para água completamente transparente (ou vidro). Através do fluxo líquido, os detalhes da pele do modelo são visíveis. O efeito de luz e sombra muda de reflexão para refração.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Pode-se ver que o resultado contém um campo task_id, e os outros campos são semelhantes ao texto anterior, e através desse campo é possível realizar a associação da tarefa.

Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o código de erro e a informação correspondente. Por exemplo:

400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha ao buscar"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Através deste documento, você já entendeu como usar a API de Geração de Imagens SeeDream, que pode gerar imagens através da entrada de palavras-chave. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

Instruções de Integração da API de Geração de Imagens SeeDream

Processo de Solicitação

Uso Básico

Editar Tarefa de Imagem

Desdobramento de Camadas (Seedream 5.0 Pro)

Saída em Fluxo

Retorno Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão

​Processo de Solicitação

​Uso Básico

​Editar Tarefa de Imagem

​Desdobramento de Camadas (Seedream 5.0 Pro)

​Saída em Fluxo

​Retorno Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Uso Básico

Editar Tarefa de Imagem

Desdobramento de Camadas (Seedream 5.0 Pro)

Saída em Fluxo

Retorno Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão