Instruções para Integração da API SeeDream Images Generation

Este documento apresenta as instruções para integração da API SeeDream Images Generation, que permite gerar imagens oficiais do SeeDream a partir de parâmetros personalizados.

Processo de Solicitação

Para usar a API, é necessário primeiro solicitar o serviço na página correspondente do SeeDream Images Generation API. Ao acessar a 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 para se registrar e entrar. Após o login, você será redirecionado de volta para a página atual. Na primeira solicitação, há uma cota gratuita disponível para uso da API.

Uso Básico

Primeiro, entenda o modo básico de uso: basta inserir o prompt, a ação de geração (action) e o tamanho da imagem (size) para obter o resultado processado. Inicialmente, é necessário enviar um campo action com o valor generate, além do prompt. O conteúdo específico é o seguinte:

Aqui configuramos os Request Headers, incluindo:

accept: formato desejado para a resposta, aqui definido como application/json (formato JSON).
authorization: chave de acesso à API, que pode ser selecionada após a solicitação.

Também configuramos o Request Body, incluindo:

prompt: o prompt de texto.
model: modelo de geração, padrão doubao-seedream-5.0-lite. Suporta doubao-seedream-5.0-lite (mais recente), doubao-seedream-4.5, doubao-seedream-4.0, doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i.
image: informações da imagem de entrada, suportando URL ou codificação Base64. Os modelos doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 suportam entrada de uma ou múltiplas imagens; doubao-seededit-3.0-i2i suporta apenas uma imagem; doubao-seedream-3.0-t2i não suporta este parâmetro.
size: especifica o tamanho da imagem gerada, suportando duas formas, que não podem ser usadas simultaneamente.
Forma 1 | Define a resolução da imagem gerada e descreve a proporção da imagem em linguagem natural no prompt. Cada modelo suporta presets diferentes: doubao-seedream-5.0-lite suporta 2K/3K/4K; doubao-seedream-4.5 suporta apenas 2K/4K; doubao-seedream-4.0 suporta 1K/2K/4K; doubao-seedream-3.0-t2i e doubao-seededit-3.0-i2i não suportam presets, aceitando apenas a Forma 2.
Forma 2 | Define a largura e altura em pixels da imagem gerada: padrão 2048x2048. O intervalo de pixels totais e proporção varia conforme o modelo (por exemplo, limite inferior de pixels totais para 5.0 / 4.5 é 3.686.400, para 4.0 é 921.600, para 3.0-t2i / seededit-3.0-i2i é [512x512, 2048x2048]).
seed: semente aleatória para controlar a aleatoriedade da geração. Intervalo [-1, 2147483647]. Apenas doubao-seedream-3.0-t2i suporta este parâmetro.
sequential_image_generation: geração de conjunto de imagens relacionadas com base no conteúdo inserido. Suportado por doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0. Padrão disabled.
stream: controla se o modo de saída em streaming está ativado. Suportado por doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0. Padrão false.
guidance_scale: grau de correspondência do resultado do modelo com o prompt, quanto maior, maior a correlação. Intervalo [1, 10]. Valor padrão 2.5 para doubao-seedream-3.0-t2i, 5.5 para doubao-seededit-3.0-i2i. Não suportado por outros modelos.
response_format: formato de retorno da imagem gerada. Padrão url, também suporta b64_json.
watermark: se deve adicionar marca d’água na imagem gerada. Padrão true.
output_format: formato do arquivo da imagem gerada, suporta jpeg (padrão) e png. Apenas doubao-seedream-5.0-lite suporta.
tools: configura ferramentas que o modelo pode chamar, atualmente suporta web_search (pesquisa online). Apenas doubao-seedream-5.0-lite suporta.
callback_url: URL para callback do resultado.

Após a seleção, o código correspondente é gerado à direita, conforme a imagem:

Clique no botão “Try” para testar. Conforme a imagem acima, 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.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}

O resultado retornado contém vários campos, descritos a seguir:

success: status da tarefa de geração de imagem.
task_id: ID da tarefa de geração.
trace_id: ID de rastreamento da tarefa.
data: lista de resultados da tarefa de geração de imagem.
- image_url: link da imagem gerada.
- prompt: prompt utilizado.
- size: resolução da imagem gerada.

Assim, obtemos as informações da imagem desejada, bastando acessar o link em data para obter a imagem SeeDream gerada. Se desejar gerar o código de integração correspondente, pode copiar diretamente, por exemplo, o código CURL abaixo:

curl -X POST 'https://api.xhuoapi.ai/v1/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

Para editar uma imagem, o parâmetro image deve conter o link da imagem a ser editada.

model: modelo usado para a tarefa de edição, doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 suportam entrada de uma ou múltiplas imagens; doubao-seededit-3.0-i2i suporta apenas uma imagem.
image: imagem(s) a ser(em) editada(s), uma ou múltiplas.

Exemplo de preenchimento:

Código correspondente:

import requests

url = "https://api.xhuoapi.ai/v1/flux/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)

Ao executar, obteremos imediatamente o resultado:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

O resultado mostra o efeito da edição da imagem original, similar ao exemplo anterior.

Callback Assíncrono

Como a geração de imagens pela SeeDream Images Generation API pode levar de 1 a 2 minutos, se a API não responder por muito tempo, a requisição HTTP permanecerá aberta, consumindo recursos do sistema. Por isso, a API oferece suporte a callbacks assíncronos. O fluxo geral é: o cliente envia a requisição incluindo o campo callback_url. Após o envio, a API retorna imediatamente um resultado contendo o campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da geração da imagem será enviado via POST em JSON para o callback_url especificado, incluindo também o campo task_id, permitindo associar o resultado à tarefa. Vamos ver um exemplo prático. Ao executar, obteremos imediatamente o resultado:

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

Conteúdo do callback:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

O campo task_id permite associar o resultado à tarefa correspondente.

Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Exemplos:

400 token_mismatched: Requisição inválida, possivelmente por parâmetros ausentes ou inválidos.
400 api_not_implemented: Requisição inválida, possivelmente por 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 requisições, limite de taxa excedido.
500 api_error: Erro interno do servidor.

Exemplo de resposta de erro

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

Conclusão

Com este documento, você aprendeu como usar a SeeDream Images Generation API para gerar imagens a partir de prompts. Esperamos que este guia ajude você a integrar e utilizar a API de forma eficiente. Em caso de dúvidas, entre em contato com nossa equipe de suporte técnico.

Documentation Index

​Processo de Solicitação

​Uso Básico

​Tarefa de Edição de Imagem

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de resposta de erro

​Conclusão