Saltar para o conteúdo principal
Este documento irá apresentar uma integração com a API SeeDream Images Generation, que pode gerar imagens oficiais da SeeDream através da entrada de parâmetros personalizados.

​
Processo de solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da SeeDream Images Generation API para solicitar o serviço correspondente. Após entrar na página, clique no botão “Acquire”, conforme mostrado na imagem: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

​
Uso básico

Primeiro, entenda a forma básica de uso, que é inserir a palavra-chave prompt, a ação action, e o tamanho da imagem size, para obter o resultado processado. Primeiro, você precisa passar um campo action, cujo valor é generate, e então precisamos inserir a palavra-chave, com o conteúdo específico abaixo:

Podemos ver que aqui configuramos os Headers da Requisição, incluindo:
  • accept: o formato de resposta desejado, aqui 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 Requisição, incluindo:
  • prompt: palavra-chave.
  • model: modelo de geração, padrão doubao-seedream-4.0.
  • image: informações da imagem de entrada, suportando URL ou codificação Base64. Entre eles, doubao-seedream-4.5, doubao-seedream-4.0 suportam entrada de uma ou várias imagens, doubao-seededit-3.0-i2i suporta apenas entrada de uma imagem, doubao-seededit-3.0-t2i não suporta este 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, forma ou uso da imagem em linguagem natural no prompt, sendo o modelo que determina o tamanho da imagem gerada. Forma 2 | Especifica os valores de pixel da largura e altura da imagem gerada: valor padrão: 2048x2048, que varia conforme o modelo.
  • 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, doubao-seededit-3.0-i2i suportam este parâmetro.
  • sequential_image_generation: grupo de imagens: uma série de imagens relacionadas geradas com base no conteúdo que você inseriu. Apenas doubao-seedream-4.5, doubao-seedream-4.0 suportam este parâmetro, padrão disabled.
  • stream: controla se o modo de saída em fluxo está ativado. Apenas doubao-seedream-4.5, doubao-seedream-4.0 suportam este parâmetro, padrão é false.
  • guidance_scale: grau de consistência entre o resultado do modelo e o prompt, liberdade na geração da imagem, também conhecido como peso do texto; quanto maior o valor, menor a liberdade do modelo, mais forte a correlação com a palavra-chave inserida pelo usuário. Intervalo de valores: [1, 10]. doubao-seedream-3.0-t2i valor padrão 2.5, doubao-seededit-3.0-i2i valor padrão 5.5, outros 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.
  • callback_url: URL para onde os resultados devem ser retornados.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e aqui obtemos o seguinte resultado: 
{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}
O resultado retornado contém vários campos, descritos a seguir:
  • 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, palavra-chave.
    • size: pixels da imagem gerada.
Podemos ver que obtivemos informações de imagem satisfatórias, e tudo o que precisamos fazer é acessar o link da imagem gerada no data para obter a imagem SeeDream. Além disso, se você quiser gerar o código de integração 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-4-0-250828",
  "prompt": "a white siamese cat"
}'

​
Tarefa de edição de imagem

Se você deseja 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 esta tarefa de edição de imagem, atualmente suporta doubao-seedream-4.5, doubao-seedream-4.0 que suportam entrada de uma ou várias imagens, doubao-seededit-3.0-i2i suporta apenas entrada de uma imagem.
  • image: faça o upload da 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/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 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)
Clique em executar, e você poderá ver que um resultado será imediatamente obtido, 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 fluida da vestimenta líquida inalteradas. Mude 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 efeito gerado é uma edição da imagem original, e o resultado é semelhante ao texto acima.

​
Callback 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 período, 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 à API, a API retornará imediatamente um resultado, contendo um campo de informação 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, também incluindo o campo task_id, assim o resultado da tarefa pode ser associado pelo ID. Abaixo, vamos entender como operar isso através de um exemplo. Clique em executar, e você 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 fluida da vestimenta líquida inalteradas. Mude 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 acima, permitindo que a tarefa seja associada por meio desse campo.

​
Tratamento de Erros

Ao chamar a API, se ocorrer 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 na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusão

Através deste documento, você já entendeu como usar a API SeeDream Images Generation 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, entre em contato com nossa equipe de suporte técnico.