API de adesivos de rosto

Pixian.AI oferece uma API diferenciada de adesivos de rosto. A API cria recortes de rostos divertidos e alegres, tanto para pets quanto para pessoas.

Obter a chave de API

Guia de início rápido

Faça POST de uma imagem bitmap e obtenha como retorno um adesivo de rosto:

$ curl https://api.pixian.ai/api/v2/face-sticker \
 -u xyz123:[secret] \
 -F image=@example.jpeg \
 -o pixian_result.png
// Requires: org.apache.httpcomponents.client5:httpclient5-fluent

Request request = Request.post("https://api.pixian.ai/api/v2/face-sticker")
   .addHeader("Authorization", "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd")
   .body(
      MultipartEntityBuilder.create()
         .addBinaryBody("image", new File("example.jpeg")) // TODO: Replace with your image
         // TODO: Add more upload parameters here
         .build()
      );
ClassicHttpResponse response = (ClassicHttpResponse) request.execute().returnResponse();

if (response.getCode() == 200) {
   // Write result to disk, TODO: or wherever you'd like
   try (FileOutputStream out = new FileOutputStream("pixian_result.png")) {
      response.getEntity().writeTo(out);
   }
} else {
   System.out.println("Request Failed: Status: " + response.getCode() + ", Reason: " + response.getReasonPhrase());
}
using (var client = new HttpClient())
using (var form = new MultipartFormDataContent())
{
   client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", "INSERT_API_KEY_HERE");
   form.Add(new ByteArrayContent(File.ReadAllBytes("example.jpeg")), "image", "example.jpeg"); // TODO: Replace with your image
   // TODO: Add more upload parameters here

   var response = client.PostAsync("https://api.pixian.ai/api/v2/face-sticker", form).Result;

   if (response.IsSuccessStatusCode)
   {
      // Write result to disk, TODO: or wherever you'd like
      FileStream outStream = new FileStream("pixian_result.png", FileMode.Create, FileAccess.Write, FileShare.None);
      response.Content.CopyToAsync(outStream).ContinueWith((copyTask) => { outStream.Close(); });
   }
   else
   {
       Console.WriteLine("Request Failed: Status: " + response.StatusCode + ", Reason: " + response.ReasonPhrase);
   }
}
// Requires "request" to be installed (see https://www.npmjs.com/package/request)
var request = require('request');
var fs = require('fs');

request.post({
  url: 'https://api.pixian.ai/api/v2/face-sticker',
  formData: {
    image: fs.createReadStream('example.jpeg'), // TODO: Replace with your image
    // TODO: Add more upload options here
  },
  auth: {user: 'xyz123', pass: '[secret]'},
  followAllRedirects: true,
  encoding: null
}, function(error, response, body) {
  if (error) {
    console.error('Request failed:', error);
  } else if (!response || response.statusCode != 200) {
    console.error('Error:', response && response.statusCode, body.toString('utf8'));
  } else {
    // Save result
    fs.writeFileSync("pixian_result.png", body);
  }
});
$ch = curl_init('https://api.pixian.ai/api/v2/face-sticker');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
    array('Authorization: Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd'));
curl_setopt($ch, CURLOPT_POSTFIELDS,
    array(
      'image' => curl_file_create('example.jpeg'),
      // TODO: Add more upload options here
    ));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$data = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
  // Save result
  file_put_contents("pixian_result.png", $data);
} else {
  echo "Error: " . $data;
}
curl_close($ch);
# Requires "requests" to be installed (see https://pypi.org/project/requests/)
import requests

response = requests.post(
    'https://api.pixian.ai/api/v2/face-sticker',
    files={'image': open('example.jpeg', 'rb')},
    data={
        # TODO: Add more upload options here
    },
    auth=('xyz123', '[secret]')
)
if response.status_code == requests.codes.ok:
    # Save result
    with open('pixian_result.png', 'wb') as out:
        out.write(response.content)
else:
    print("Error:", response.status_code, response.text)
# Requires: gem install httpclient
require 'httpclient'

client = HTTPClient.new default_header: {
  "Authorization" => "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd"
}

response = client.post("https://api.pixian.ai/api/v2/face-sticker", {
  "image" => File.open("example.jpeg", "rb"), # TODO: Replace with your image
  # TODO: Add more upload parameters here
})

if response.status == 200 then
  # Write result to disk, TODO: or wherever you'd like
  File.open("pixian_result.png", 'w') { |file| file.write(response.body) }
else
  puts "Error: Code: " + response.status.to_s + ", Reason: " + response.reason
end
$ curl https://api.pixian.ai/api/v2/face-sticker \
 -u xyz123:[secret] \
 -F 'image.url=https://example.com/example.jpeg' \
 -o pixian_result.png
// Requires: org.apache.httpcomponents.client5:httpclient5-fluent

Request request = Request.post("https://api.pixian.ai/api/v2/face-sticker")
   .addHeader("Authorization", "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd")
   .body(
      MultipartEntityBuilder.create()
         .addTextBody("image.url", "https://example.com/example.jpeg") // TODO: Replace with your image URL
         // TODO: Add more upload parameters here
         .build()
      );
ClassicHttpResponse response = (ClassicHttpResponse) request.execute().returnResponse();

if (response.getCode() == 200) {
   // Write result to disk, TODO: or wherever you'd like
   try (FileOutputStream out = new FileOutputStream("pixian_result.png")) {
      response.getEntity().writeTo(out);
   }
} else {
   System.out.println("Request Failed: Status: " + response.getCode() + ", Reason: " + response.getReasonPhrase());
}
using (var client = new HttpClient())
using (var form = new MultipartFormDataContent())
{
   client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", "INSERT_API_KEY_HERE");
   form.Add(new StringContent("https://example.com/example.jpeg"), "image.url"); // TODO: Replace with your image URL
   // TODO: Add more upload parameters here

   var response = client.PostAsync("https://api.pixian.ai/api/v2/face-sticker", form).Result;

   if (response.IsSuccessStatusCode)
   {
      // Write result to disk, TODO: or wherever you'd like
      FileStream outStream = new FileStream("pixian_result.png", FileMode.Create, FileAccess.Write, FileShare.None);
      response.Content.CopyToAsync(outStream).ContinueWith((copyTask) => { outStream.Close(); });
   }
   else
   {
       Console.WriteLine("Request Failed: Status: " + response.StatusCode + ", Reason: " + response.ReasonPhrase);
   }
}
// Requires "request" to be installed (see https://www.npmjs.com/package/request)
var request = require('request');
var fs = require('fs');

request.post({
  url: 'https://api.pixian.ai/api/v2/face-sticker',
  formData: {
    'image.url': 'https://example.com/example.jpeg', // TODO: Replace with your image
    // TODO: Add more upload options here
  },
  auth: {user: 'xyz123', pass: '[secret]'},
  followAllRedirects: true,
  encoding: null
}, function(error, response, body) {
  if (error) {
    console.error('Request failed:', error);
  } else if (!response || response.statusCode != 200) {
    console.error('Error:', response && response.statusCode, body.toString('utf8'));
  } else {
    // Save result
    fs.writeFileSync("pixian_result.png", body);
  }
});
$ch = curl_init('https://api.pixian.ai/api/v2/face-sticker');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
    array('Authorization: Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd'));
curl_setopt($ch, CURLOPT_POSTFIELDS,
    array(
      'image.url' => 'https://example.com/example.jpeg',
      // TODO: Add more upload options here
    ));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$data = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
  // Save result
  file_put_contents("pixian_result.png", $data);
} else {
  echo "Error: " . $data;
}
curl_close($ch);
# Requires "requests" to be installed (see https://pypi.org/project/requests/)
import requests

response = requests.post(
    'https://api.pixian.ai/api/v2/face-sticker',
    data={
        'image.url': 'https://example.com/example.jpeg',
        # TODO: Add more upload options here
    },
    auth=('xyz123', '[secret]')
)
if response.status_code == requests.codes.ok:
    # Save result
    with open('pixian_result.png', 'wb') as out:
        out.write(response.content)
else:
    print("Error:", response.status_code, response.text)
# Requires: gem install httpclient
require 'httpclient'

client = HTTPClient.new default_header: {
  "Authorization" => "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd"
}

response = client.post("https://api.pixian.ai/api/v2/face-sticker", {
  "image.url" => "https://example.com/example.jpeg", # TODO: Replace with your image URL
  # TODO: Add more upload parameters here
})

if response.status == 200 then
  # Write result to disk, TODO: or wherever you'd like
  File.open("pixian_result.png", 'w') { |file| file.write(response.body) }
else
  puts "Error: Code: " + response.status.to_s + ", Reason: " + response.reason
end

Preços

Você pode integrar e testar a API gratuitamente. Não é necessário fazer a compra.

Para desenvolvimento, use test=true. Você pode avaliar a qualidade do resultado usando o app interativo da Web na página inicial do site.

Para obter os resultados de produção é preciso comprar um pacote de créditos. Consulte a nossa página de preços.

Autenticação e segurança

A API usa autenticação padrão HTTP básica de acesso. Todas as requisições para a API devem ser feitas em HTTPS e incluir suas credenciais da API, tendo API Id como usuário e API Secret como senha.

Sua biblioteca de cliente HTTP deve aceitar Indicação de Nome do Servidor (SNI) para fazer requisições corretamente. Se você estiver recebendo erros de handshake estranhos, provavelmente esta é a causa.

Limitação de velocidade

O uso da API tem limite de taxa com margens generosas e não há tetos definitivos.

Durante as operações conduzidas pelo usuário final, é improvável que você tenha limitações de velocidade, pois o uso é adaptado pelo sistema de forma transparente.

No entanto, para trabalhos em lote, recomendamos começar com no máximo cinco ramificações e adicionar uma nova ramificação a cada cinco minutos, até atingir o nível de paralelismo desejado. Se você precisa de mais de 100 ramificações simultâneas, fale conosco antes de começar.

Se enviar requisições em excesso, você começará a receber respostas do tipo 429 Too Many Requests. Se isso ocorrer, você deverá aplicar um algoritmo de back off linear: na primeira resposta desse tipo, aguarde 5 segundos até reenviar a requisição seguinte. Na segunda resposta 429 consecutiva, aguarde 2 x 5=10 segundos até reenviar a requisição seguinte. Na terceira, aguarde 3 x 5=15 segundos, e assim por diante.

Você poderá reinicializar o contador de back off após o processamento satisfatório de uma requisição, e o back off deve ser aplicado ramificação a ramificação, ou seja, as ramificações devem operar independentemente.

Limite de tempo de inatividade

Em geral, as solicitações de API são executadas em segundos, mas é possível que o tempo de processamento seja mais longo durante picos de carga.

Para assegurar que sua biblioteca de cliente não encerre solicitações de API prematuramente, ela deveria ser configurada com um limite de tempo de inatividade mínimo de 180 segundos

Objeto JSON de erro

Usamos status HTTP convencionais para indicar êxito ou falha de uma requisição de API e incluir informações importantes sobre erro no objeto JSON de erro retornado.

Tentamos sempre retornar um objeto JSON de erro com qualquer requisição problemática. Teoricamente, no entanto, sempre é possível haver falhas internas no servidor que resultam em uma resposta de erro não JSON.

Atributos

statusO status HTTP da resposta, repetido aqui para auxílio na depuração de erros.
codecódigo interno de erro Pixian.AI
messageMensagem de erro inteligível, para ajudar na depuração.

Se o status HTTP da sua requisição for 200, não haverá retorno de Objeto JSON de erro e você pode supor com segurança que a requisição foi, de forma geral, exitosa.

Algumas bibliotecas de cliente HTTP suscitam exceções para status HTTP no intervalo 400-599. Você deverá obter essas exceções e tratá-las adequadamente.

HTTP StatusSignificado
200-299

Êxito

400-499

Há um problema com as informações fornecidas na requisição, por exemplo, a falta de um parâmetro. Analise a mensagem de erro para resolver como solucioná-lo.

500-599

Houve um erro interno no Pixian.AI. Aguarde alguns momentos e tente novamente. Se o problema persistir, envie-nos um e-mail.

Exemplo de resposta de erro

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}

Adesivos de rosto POST
https://api.pixian.ai/api/v2/face-sticker

Para receber um adesivo de rosto de uma imagem, você faz um upload de arquivo padrão com HTTP POST. Lembre-se de que o Content-Type deve ser multipart/form-data no upload de arquivos binários.

Parâmetros

A imagem de entrada de ser fornecida como:


Binário

Um arquivo binário.


Cadeia de caracteres

Uma cadeia de caracteres codificada como base 64. A cadeia de caracteres pode ter o comprimento máximo de 1 megabyte.


Cadeia de caracteres

Um URL para buscar e processar.

O arquivo deve ser .bmp, .gif, .jpeg, .png ou tiff.

O tamanho máximo de imagem para upload (= largura × altura) é 32.000.000 pixels, que é reduzido para max_pixels.


Booleano, padrão: false

Informe true para indicar que esta é uma imagem de teste.

Omitir ou passar false para imagens de produção.

Imagens de teste têm processamento gratuito, mas o resultado incorpora uma marca d'água.


Inteiro, de 100 a 25000000, padrão: 25000000

O tamanho máximo da imagem de entrada (largura × altura). Imagens maiores serão reduzidas para esse tamanho antes do processamento.


Formato: '#RRGGBB', por exemplo, #0055FF

A cor de fundo a ser aplicada no resultado. Omita para usar o fundo transparente.

Não deixe de incluir o prefixo '#'.


Booleano, padrão: true

Estabelece se o resultado deve ser cortado ao objeto do primeiro plano.

É muito útil com result.margin e result.target_size para obter sempre um resultado dimensionado e centralizado.


Formato: '(x.y%|px){1,4}', por exemplo, 10px 20% 5px 15%, padrão: 1px

Margem a ser adicionada ao resultado.

É adicionada, seja o resultado cortado ao primeiro plano ou não.

Caso seja especificado result.target_size, a imagem será introduzida, ou seja, não aumentará o tamanho real do resultado.

As unidades aceitas são % e px. A semântica CSS é seguida, portanto, é possível usar:

  • [all]
  • [top/bottom] [left/right]
  • [top] [left/right] [bottom]
  • [top] [right] [bottom] [left]


Formato: 'w h', por exemplo, 1920 1080

Impõe um tamanho de resultado em pixels específico. O resultado será dimensionado para caber no tamanho especificado. Em caso de espaço em excesso, a centralização é sempre horizontal, e result.vertical_alignment controla o tratamento vertical.


Enum, padrão: middle

Especifica como alocar o espaço vertical excedente quando result.target_size é usado.


Enum, padrão: auto

Formato de saída. auto é interpretado como png para resultados transparentes e jpeg para resultados opacos, ou seja, quando uma background.color é especificada.

delta_png é um formato avançado, rápido e altamente compacto, útil principalmente em situações de baixa latência e restrição de largura de banda, como é o caso de apps móveis. Ele codifica o fundo como preto transparente 0x00000000 e o primeiro plano como branco transparente 0x00FFFFFF. Pixels parcialmente transparentes têm os valores reais das cores. Combinado à imagem de entrada, é usado para reconstruir o resultado completo. Learn more about the Delta PNG format

background.color, result.crop_to_foreground, result.margin, result.target_size e result.vertical_alignment são ignorados quando delta_png é usado. O resultado deve ter o mesmo tamanho da imagem de entrada. Caso contrário, a decodificação não funcionará. Portanto, max_pixels não deve provocar a redução da entrada.


Inteiro, de 1 a 100, padrão: 75

A qualidade a ser usada na codificação dos resultados JPEG.

Cabeçalhos do resultado

X-Credits-Charged Os créditos efetivamente cobrados.
X-Credits-Calculated Os créditos calculados que seriam cobrados se isso fosse solicitado em produção. Retornados apenas para solicitações de teste.
X-Input-Orientation A tag de orientação no EXIF a ser lida e aplicada à imagem de entrada. É um inteiro entre 1 e 8, inclusive. Isso é útil se a sua biblioteca de carregamento de imagens não tem suporte para a orientação EXIF. Read more about EXIF orientation here
X-Input-Size [width] [height] da imagem de entrada em pixels, antes da aplicação de restrições de tamanho.
X-Result-Size [width] [height] da imagem resultante, em pixels.
X-Input-Foreground [top] [left] [width] [height] da caixa de contorno do primeiro plano nas coordenadas da imagem de entrada.
X-Result-Foreground [top] [left] [width] [height] da caixa de contorno do primeiro plano nas coordenadas da imagem resultante.

Histórico de alteração da API de adesivos de rosto

DataAlterar
11 de abr. de 2024 Liberação inicial.
Obter a chave de API