Search by

adachsoft / ai-3d-generation-tripo

Arkadiusz Adach

Tripo API adapter for asynchronous text-to-3D and image-to-3D model generation.

Package info

gitlab.com/a.adach/ai-3d-generation-tripo

Issues

pkg:composer/adachsoft/ai-3d-generation-tripo

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

v0.2.0 2026-11-20 10:07 UTC

This package is auto-updated.

Last update: 2026-11-20 09:08:37 UTC


README

A PHP adapter for Tripo's asynchronous text-to-3D and image-to-3D API. It implements adachsoft/ai-3d-generation-contracts 0.2 and keeps estimated provider credits separate from API-reported usage.

Installation

composer require adachsoft/ai-3d-generation-tripo

Requirements

  • PHP 8.3 or later.
  • adachsoft/ai-3d-generation-contracts 0.2 or later within the ^0.2 constraint.
  • symfony/http-client.

Configuration

Create a Tripo API key and provide it to the factory. Keep the key in your application's secret store or environment configuration; this package does not load environment variables for normal use.

use AdachSoft\Ai3dGenerationTripo\TripoModelGeneratorFactory;

$generator = TripoModelGeneratorFactory::create($_ENV['TRIPO_API_KEY']);

The factory configures the Tripo v3 base URI and sends the key as a Bearer authorization header. A Symfony HttpClientInterface can be injected as the optional second argument for custom transports and deterministic tests. An empty API key raises InvalidInputException.

Composer plugin

The package declares AdachSoft\Ai3dGenerationTripo\Plugin\TripoModelGeneratorPlugin under the adachsoft/ai-3d-generation-contracts Composer discovery key. Its required parameter is api_key:

use AdachSoft\Ai3dGenerationContracts\Plugins\PluginParametersDto;
use AdachSoft\Ai3dGenerationTripo\Plugin\TripoModelGeneratorPlugin;

$generator = (new TripoModelGeneratorPlugin())->create(
    new PluginParametersDto(['api_key' => $_ENV['TRIPO_API_KEY']]),
);

Usage

Text generation

use AdachSoft\Ai3dGenerationContracts\Models\GenerationRequestDto;
use AdachSoft\Ai3dGenerationContracts\Models\Enums\TaskStatusEnum;
use AdachSoft\Ai3dGenerationContracts\ValueObjects\TextPromptVo;

$request = new GenerationRequestDto(new TextPromptVo('a small wooden chair'));
$estimate = $generator->estimateCost($request);
$task = $generator->createTask($request);

while (in_array($task->status, [TaskStatusEnum::QUEUED, TaskStatusEnum::RUNNING], true)) {
    sleep(5);
    $task = $generator->getTask($task->reference);
}

if ($task->status === TaskStatusEnum::SUCCEEDED) {
    foreach ($task->models as $model) {
        echo $model->url->value . PHP_EOL;
    }
}

Tripo estimates 100 credits without texture and 110 credits with standard texture. Estimates and reported usage are CostItemCollection values in the tripo_credits unit. Reported usage is null until Tripo returns credits_consumed.

Image generation and uploads

Provide an HTTP(S) URL, Base64 image data URI, or local file path with ImageInputVo:

use AdachSoft\Ai3dGenerationContracts\Models\GenerationRequestDto;
use AdachSoft\Ai3dGenerationContracts\ValueObjects\ImageInputVo;

$request = new GenerationRequestDto(new ImageInputVo('/path/to/reference.png'));
$task = $generator->createTask($request);

HTTP(S) URLs are sent directly to Tripo. Local files and data URIs are decoded, checked by their signature bytes, and uploaded to POST /files as a multipart file before the image-to-model request. Only PNG and JPEG images up to 20 MB are accepted; an unsupported, unreadable, or oversized local image raises InvalidInputException before an API request is made. Image uploads do not change the generation estimate.

Failures

Invalid inputs raise InvalidInputException. Permanent API or response failures raise GenerationFailedException, which may include errorCode and requestId. HTTP 429, HTTP 5xx, and transport failures raise RetryableException; for HTTP 429, refreshTime uses the Retry-After response header when available. API keys are redacted from provider messages.

Upgrade from contracts 0.1 to 0.2

Version 0.2 replaces the provider-specific contract with ModelGeneratorInterface and provider-neutral request, task, cost, and model DTOs. Use GenerationRequestDto, TaskReferenceDto, and GenerationTaskDto; costs and generated models are returned in CostItemCollection and GeneratedModelCollection. Replace the old factory with TripoModelGeneratorFactory, and use the Composer plugin's api_key parameter for plugin-based configuration. There are no compatibility aliases for the 0.1 API.

Live API tests

Live tests are in the live group, excluded from the default PHPUnit suite, and make real Tripo requests when run explicitly. Configure TRIPO_API_KEY in the repository-root .env file or process environment. The local-image test also requires TRIPO_LIVE_IMAGE_PATH to point to a PNG or JPEG file no larger than 20 MB.

Run live tests only when you intend to spend Tripo credits:

vendor/bin/phpunit --group live