Instruções de integração da API SeeDream Images Generation

Este artigo apresentará um tipo de instruções de integração da API SeeDream Images Generation, que pode gerar imagens oficiais do SeeDream por meio da inserção de parâmetros personalizados.

Processo de solicitação

Para usar a API SeeDream Images Generation, primeiro obtenha seu API Token no Console do Ace Data Cloud e guarde-o para uso posterior.

Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login para se registrar e fazer login, e retornará automaticamente à página atual após a conclusão. Um API Token pode chamar todos os serviços da plataforma, não sendo necessário solicitar separadamente para cada serviço. A primeira solicitação oferecerá créditos gratuitos para experimentar gratuitamente; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.

📘 Documentação completa: SeeDream Images Generation API →

Uso básico

Primeiro, vamos entender o método básico de uso: basta inserir o texto de prompt prompt, a ação de geração action e o tamanho da imagem size para obter o resultado processado. Primeiro, é necessário simplesmente passar um campo action, cujo valor é generate, e então também precisamos inserir o texto de prompt. O conteúdo específico é o seguinte:

Pode-se ver que aqui definimos os Request Headers, incluindo:

accept: o formato de resultado da resposta que se deseja receber; aqui é preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente no menu suspenso após a solicitação.

Além disso, definimos o Request Body, incluindo:

prompt: texto de prompt.
model: modelo de geração, o padrão é doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, o mais recente). Compatível com doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Entre eles, doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) é o modelo principal de imagem única, gerando apenas uma imagem, não oferecendo suporte a grupo de imagens (sequential_image_generation), streaming (stream) e pesquisa na web (tools). model deve receber a string completa do modelo (como doubao-seedream-5-0-lite-260128); passar abreviações como doubao-seedream-5.0-lite retornará 400.
image: informações da imagem de entrada, compatível com URL ou codificação Base64. doubao-seedream-5-0-pro-260628 oferece suporte à entrada de uma ou várias imagens (no máximo 10), e doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 oferecem suporte à entrada de uma ou várias imagens.
size: especifica as informações de tamanho da imagem gerada, com suporte às duas formas a seguir, que não podem ser combinadas. Forma 1 | Especifica a resolução da imagem gerada e descreve a proporção de largura e altura da imagem em linguagem natural no prompt. Os presets compatíveis variam entre os modelos: doubao-seedream-5-0-pro-260628 oferece suporte a 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 oferece suporte a 2K/3K/4K; doubao-seedream-4-5-251128 oferece suporte apenas a 2K/4K; doubao-seedream-4-0-250828 oferece suporte a 1K/2K/4K. Forma 2 | Especifica os valores em pixels de largura e altura da imagem gerada: o padrão é 2048x2048; o total de pixels e o intervalo de proporção de largura e altura variam conforme o modelo (por exemplo, o intervalo total de pixels do 5.0 Pro é [921600, 4624220], o limite inferior do total de pixels do 5.0 Lite / 4.5 é 3,686,400 e o limite inferior do 4.0 é 921,600).
sequential_image_generation: grupo de imagens: com base no conteúdo inserido, gera um grupo de imagens com conteúdo relacionado. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 oferecem suporte a esse parâmetro, cujo padrão é disabled.
stream: controla se o modo de saída por streaming será ativado. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 oferecem suporte a esse parâmetro, cujo padrão é false.
response_format: especifica o formato de retorno da imagem gerada. O padrão é url, e também oferece suporte a b64_json.
watermark: define se uma marca d’água será adicionada à imagem gerada. O padrão é true.
output_format: especifica o formato de arquivo da imagem gerada, com suporte a jpeg (padrão) e png. Somente doubao-seedream-5-0-pro-260628 e doubao-seedream-5-0-lite-260128 oferecem suporte.
tools: configura as ferramentas que o modelo deve chamar; atualmente, oferece suporte a web_search (pesquisa na web). Somente o Seedream 5.0 Lite oferece suporte.
optimize_prompt_options: configuração de otimização do texto de prompt. O 5.0 Pro oferece suporte a standard/fast; o 5.0 Lite e o 4.5 oferecem suporte apenas a standard; o 4.0 oferece suporte a standard/fast.
background: suportado apenas pela edição de imagem única do 5.0 Pro. transparent exige a entrada de uma imagem PNG com canal de transparência, e output_format deve ser png; opaque corresponde a um fundo opaco comum.
layer_decomposition: somente o 5.0 Pro oferece suporte. Quando definido como true, é necessário inserir uma PNG/JPEG; é possível não passar prompt para dividir automaticamente, ou especificar elementos com linguagem natural/<bbox>; size oferece suporte a auto/1K/1.5K/2K. Esse modo não pode ser usado junto com grupo de imagens, streaming, pesquisa na web ou background.
callback_url: URL que precisa receber o resultado de retorno.
async: define se será processado no modo assíncrono. Quando definido como true, a interface retorna imediatamente task_id, não sendo necessário fornecer callback_url; em seguida, obtenha o resultado por polling por meio de /seedream/tasks.

Após selecionar, é possível ver que o código correspondente também é gerado à direita, como mostrado na imagem:

Clique no botão «Try» para realizar o teste; como mostrado na imagem acima, aqui obtemos o seguinte resultado:

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

O resultado retornado possui vários campos, apresentados a seguir:

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

Podemos ver que obtivemos informações satisfatórias da imagem; basta obter a imagem SeeDream gerada com base no endereço do link da imagem em data no resultado. Além disso, se desejar gerar o código de integração correspondente, você pode copiá-lo diretamente para gerar; por exemplo, o código CURL é o seguinte:

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-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Tarefa de edição de imagem

Se desejar editar uma imagem, primeiro o parâmetro image deve receber o link da imagem que precisa ser editada.

model: o modelo utilizado nesta tarefa de edição de imagem; doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 todos oferecem suporte à entrada de imagem.
image: envie a imagem que precisa ser editada, uma ou várias.

O exemplo de preenchimento é o seguinte:

O 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": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "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)

Clique em executar e você verá que um resultado será obtido imediatamente, conforme a seguir:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "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 apresentado acima.

Separação de camadas (Seedream 5.0 Pro)

A separação de camadas divide uma imagem de entrada em 1 imagem de fundo e até 16 camadas PNG transparentes que podem ser editadas independentemente. A solicitação a seguir permite que o modelo reconheça automaticamente os elementos principais; se precisar especificar elementos, você pode adicionar prompt e também pode usar coordenadas <bbox> normalizadas no prompt.

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 de baixo para cima conforme z_index. O z_index da imagem de fundo é 0; as camadas também incluem name, description e bounding_box.absolute/normalized. Ao recompor usando coordenadas absolutas, redimensione a camada para [right-left, bottom-top], coloque-a em [left, top] e, em seguida, sobreponha-as em ordem crescente de z_index. Se a geração de qualquer camada falhar, toda a separação falhará.

Saída em streaming

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

Callback assíncrono

Como o tempo de geração da SeeDream Images Generation API é relativamente longo, levando aproximadamente 1 a 2 minutos, se a API não responder por muito tempo, a solicitação HTTP manterá a conexão aberta, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia uma solicitação, ele especifica adicionalmente um campo callback_url; após o cliente iniciar a solicitação da API, a API retornará imediatamente um resultado contendo um campo task_id, que representa o ID da tarefa atual. Após a conclusão da tarefa, o resultado da imagem gerada será enviado na forma de POST JSON para o callback_url especificado pelo cliente, incluindo também o campo task_id, de modo que o resultado da tarefa possa ser associado pelo ID. Se você não tiver um endereço público disponível para callback, também pode não especificar callback_url e, em vez disso, definir o campo async como true na solicitação. Nesse caso, a interface também retornará imediatamente task_id, mas não enviará o resultado; você precisará usar esse task_id para chamar a interface /seedream/tasks e consultar o status da tarefa para obter o resultado final. A seguir, vamos entender como operar especificamente por meio de um exemplo. Clique em executar e você verá que um resultado será obtido imediatamente, conforme a seguir:

{
  "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": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Pode-se ver que há um campo task_id no resultado; os outros campos são semelhantes aos mencionados acima, e a associação da tarefa pode ser realizada por meio desse campo.

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e as informações de erro correspondentes. 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Por meio deste documento, você já aprendeu como usar a API de Geração de Imagens SeeDream para gerar imagens inserindo textos de comando. 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 a qualquer momento.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Instruções de integração da API SeeDream Images Generation

Processo de solicitação

Uso básico

Tarefa de edição de imagem

Separação de camadas (Seedream 5.0 Pro)

Saída em streaming

Callback assíncrono

Tratamento de erros

Exemplo de resposta de erro

Conclusão

​Processo de solicitação

​Uso básico

​Tarefa de edição de imagem

​Separação de camadas (Seedream 5.0 Pro)

​Saída em streaming

​Callback assíncrono

​Tratamento de erros

​Exemplo de resposta de erro

​Conclusão

Processo de solicitação

Uso básico

Tarefa de edição de imagem

Separação de camadas (Seedream 5.0 Pro)

Saída em streaming

Callback assíncrono

Tratamento de erros

Exemplo de resposta de erro

Conclusão