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 da 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 estiver baixo, 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, conforme detalhado abaixo:

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, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828, doubao-seedream-3-0-t2i-250415, doubao-seededit-3-0-i2i-250628. O doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) é o modelo de imagem única, gerando apenas uma única imagem, não suporta geração de múltiplas imagens (sequential_image_generation), streaming (stream) e busca 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. Dentre eles, doubao-seedream-5-0-pro-260628 suporta entrada de uma ou várias imagens (2-10 imagens, a partir da segunda imagem será cobrado 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, doubao-seededit-3-0-i2i-250628 suporta apenas entrada de uma imagem, doubao-seedream-3-0-t2i-250415 não suporta esse parâmetro.
size: especifica as informações de tamanho da imagem gerada, suportando as seguintes duas formas, que não podem ser misturadas. Forma 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/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; doubao-seedream-3-0-t2i-250415 e doubao-seededit-3-0-i2i-250628 não suportam predefinições, aceitam apenas a forma 2. Forma 2 | Especifica os valores de pixel 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 intervalo total de pixels do 5.0 Pro é [921600, 4194304], o limite inferior do 5.0 Lite / 4.5 é 3.686.400, o limite inferior do 4.0 é 921.600, e o intervalo do 3.0-t2i / seededit-3.0-i2i é [512x512, 2048x2048]).
seed: semente de número aleatório, usada para controlar a aleatoriedade do conteúdo gerado pelo modelo. O intervalo de valores é [-1, 2147483647]. Apenas doubao-seedream-3-0-t2i-250415 suporta esse parâmetro.
sequential_image_generation: múltiplas imagens: um conjunto 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.
guidance_scale: grau de consistência entre o resultado da saída do modelo e o prompt, quanto maior o valor, mais forte a correlação. O intervalo de valores é [1, 10]. doubao-seedream-3-0-t2i-250415 tem valor padrão 2.5, doubao-seededit-3-0-i2i-250628 tem valor padrão 5.5, outros modelos não suportam.
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 (busca na web). Apenas doubao-seedream-5-0-260128 suporta.
callback_url: URL que precisa receber o resultado de retorno.
async: se deve processar em modo assíncrono. Se definido como true, a interface retorna imediatamente task_id, não sendo necessário fornecer callback_url, e em seguida, você pode obter 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 realista 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: a resolução 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 realista 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 específica, 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-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 suportam entrada de uma ou mais imagens, doubao-seededit-3-0-i2i-250628 suporta apenas entrada de uma imagem.
image: faça o 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/flux/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 ver 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 é uma edição da imagem original, e o resultado é semelhante ao mencionado acima.

Callback Assíncrono

Como a API de Geração de Imagens SeeDream leva um tempo relativamente longo para gerar, 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 callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo callback_url adicional. Após o cliente fazer a solicitação da API, a API retornará imediatamente um resultado, contendo um campo task_id, que representa 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 no formato JSON POST, que também incluirá o campo task_id, permitindo que o resultado da tarefa seja 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, 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á usar esse task_id para chamar a interface /seedream/tasks e consultar o status da tarefa para obter o resultado final. Vamos entender como operar isso através de um exemplo. Ao clicar em executar, você pode ver 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 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 resultado contém um campo task_id, e os outros campos são semelhantes ao mencionado acima, permitindo a associação da tarefa através desse campo.

Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem 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

Através deste documento, você já entendeu como usar a API de Geração de Imagens SeeDream para 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, sinta-se à vontade para entrar 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

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

Processo de Solicitação

Uso Básico

Editar Tarefa de Imagem

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão

​Processo de Solicitação

​Uso Básico

​Editar Tarefa de Imagem

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Uso Básico

Editar Tarefa de Imagem

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão