Image Generation

Base URL & Authentication

Base URL: https://api.animusai.co/v2
Authentication: Authorization: Bearer <ANIMUS_API_KEY>
Content type: application/json

Every response includes a generation_id that you can use to poll status or fetch historical results later.

Create a Generation

Use POST /generation/create to submit a single job. The API automatically infers the generation type from your payload:

Provide character_id to trigger a character LoRA render (face/body LoRA and face swap are enabled by default).
Provide source_image_url to run a Seedream photo edit.
Provide both source_image_url and convert_to_video: true to turn an image into a short video clip.
Omit both fields to default to text-to-image generation.

curl https://api.animusai.co/v2/generation/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANIMUS_API_KEY" \
  -d '{
    "prompt": "Cinematic portrait lighting on Chloe standing in a neon street",
    "character_id": "char_123",
    "num_images": 1,
    "seed": 42
  }'

import requests

url = "https://api.animusai.co/v2/generation/create"
payload = {
    "prompt": "Vintage postcard of a coastal lighthouse at sunrise",
    "source_image_url": "https://cdn.animusai.co/samples/lighthouse.png",
    "strength": 0.55,
    "guidance_scale": 8,
    "convert_to_video": False
}

resp = requests.post(
    url,
    headers={
        "Authorization": f"Bearer {ANIMUS_API_KEY}",
        "Content-Type": "application/json"
    },
    json=payload,
    timeout=30
)
print(resp.json())

const response = await fetch('https://api.animusai.co/v2/generation/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ANIMUS_API_KEY}`
  },
  body: JSON.stringify({
    prompt: 'Slow push-in shot of a futuristic city plaza at dusk',
    convert_to_video: true,
    source_image_url: 'https://cdn.animusai.co/samples/plaza.png',
    num_images: 1
  })
});

const data = await response.json();
console.log(data);

Request Body

Field	Type	Default	Required	Notes
`prompt`	string	—	✅	Text prompt used for all generation types.
`num_images`	integer	`1`	❌	Values >1 are submitted as a batch (see below).
`character_id`	string	`null`	❌	Required for character-based renders. Automatically validates subscription access.
`use_face_lora`	boolean	`true`	❌	Applies the character face LoRA. Only meaningful when `character_id` is set.
`use_body_lora`	boolean	`true`	❌	Applies the character body LoRA.
`face_swap`	boolean	`true`	❌	Enables default face swap pass.
`source_image_url`	string	`null`	❌	Publicly reachable image URL for photo edits or video conversion. Automatically uploaded to temporary storage when needed.
`convert_to_video`	boolean	`false`	❌	Converts the output into a short MP4 clip. Requires `source_image_url`.
`group_id`	string	`null`	❌	Attach the generation to an existing media group.
`group_title`	string	auto	❌	Title to use when creating a new group on the fly.

Response

A successful submission returns a GenerationResponse object:

{
  "generation_id": "gen_5f0c2d8fbf8b",
  "group_id": "grp_a12f39e1",
  "status": "submitted",
  "message": "Character Generation job submitted successfully",
  "estimated_time": 30,
  "credits_deducted": 4,
  "remaining_balance": 96
}

Use generation_id to poll status or subscribe to webhooks in your own system. If the user lacks the required plan or credits, the endpoint returns an HTTP 402 with additional context.

Track Generation Status

Use GET /generation/status/{generation_id} to retrieve the latest status, final media URLs, and performance metadata. The endpoint works for single renders and batches alike.

curl "https://api.animusai.co/v2/generation/status/gen_5f0c2d8fbf8b" \
  -H "Authorization: Bearer $ANIMUS_API_KEY"

Example response after completion:

{
  "generation_id": "gen_5f0c2d8fbf8b",
  "group_id": "grp_a12f39e1",
  "generation_type": "character_generation",
  "status": "completed",
  "progress": 100,
  "result_urls": [
    "https://link.storjshare.io/raw/animus-prod/.../character_generation_gen_5f0c2d8fbf8b_0.png"
  ],
  "error": null,
  "created_at": "2024-07-01T15:04:55.101231",
  "prompt": "Cinematic portrait lighting on Chloe standing in a neon street",
  "performance_metadata": {
    "duration": 24.1,
    "queue_position": 0
  }
}

If you submit num_images > 1, the status payload includes aggregate counts so you can expose progress bars in your UI.

Batch Submissions

Send multiple prompts (or the same prompt repeated) with POST /generation/batch. The API creates a shared group automatically and returns a single batch_id you can poll through the standard status endpoint.

{
  "prompts": [
    { "prompt": "Moody editorial portrait of Sora", "face_swap": true },
    { "prompt": "Profile shot of Sora in cinema lighting" },
    { "prompt": "Wide shot: Sora in a sci-fi hangar" }
  ],
  "character_id": "char_123",
  "group_title": "Sora editorial set"
}

The response reports how many jobs were accepted, any immediate validation errors, and the total credits deducted. Each generated asset will still appear in the group and status APIs.

Organize Results with Groups

Every generation belongs to a group so you can fetch cohesive sessions or albums later.

GET /generation/groups returns paginated groups for the authenticated organization.
GET /generation/groups/{group_id} returns group metadata plus individual generations (with URLs) for galleries and download flows.

List groups:

curl "https://api.animusai.co/v2/generation/groups?limit=20&offset=0" \
  -H "Authorization: Bearer $ANIMUS_API_KEY"

Typical response snippet:

{
  "groups": [
    {
      "group_id": "grp_a12f39e1",
      "title": "Chloe Neon Portraits",
      "group_type": "character_generation",
      "generation_count": 4,
      "preview_image_url": "https://link.storjshare.io/raw/.../character_generation_gen_5f0c2d8fbf8b_0.png",
      "created_at": "2024-07-01T15:04:50.102300",
      "updated_at": "2024-07-01T15:06:10.775220"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "returned": 1,
    "has_more": false
  }
}

Group detail:

curl "https://api.animusai.co/v2/generation/groups/grp_a12f39e1?limit=12" \
  -H "Authorization: Bearer $ANIMUS_API_KEY"

{
  "group_id": "grp_a12f39e1",
  "title": "Chloe Neon Portraits",
  "generations": [
    {
      "generation_id": "gen_5f0c2d8fbf8b",
      "status": "completed",
      "result_urls": [
        "https://link.storjshare.io/raw/.../character_generation_gen_5f0c2d8fbf8b_0.png"
      ],
      "created_at": "2024-07-01T15:04:55.101231"
    }
  ],
  "pagination": {
    "limit": 12,
    "offset": 0,
    "returned": 1,
    "has_more": false
  }
}

Cleanup Endpoints

You can let users curate storage directly from your product:

DELETE /generation/generations/{generation_id} removes a specific job and purges all associated media from Storj.
DELETE /generation/groups/{group_id} deletes the group, every generation inside it, and their assets in a single operation.

Both endpoints enforce organization scoping and return summaries of what was removed.

Error Handling & Credits

HTTP 402 responses indicate missing credits or subscription access for the requested character. The JSON payload includes error, message, and character_id fields so you can upsell or reroute the user.
HTTP 409 responses appear when you attempt to delete a group while generations are still reconciling. Retry after active jobs finish.
Most write operations deduct credits immediately and automatically refund them if submission fails before processing. Always check remaining_balance on the create responses to drive UX copy.

Next Steps

Use the status endpoint to power polling loops or push notifications.
Combine group listings with your own asset selectors to build download or approval workflows.
Pair these endpoints with the Animus SDK to offer one-click generation directly in chat experiences.

Get Started

SDK Features

Advanced SDK

REST API Integration

Models

Base URL & Authentication

Create a Generation

Request Body

Response

Track Generation Status

Batch Submissions

Organize Results with Groups

Cleanup Endpoints

Error Handling & Credits

Next Steps

​Base URL & Authentication

​Create a Generation

​Request Body

​Response

​Track Generation Status

​Batch Submissions

​Organize Results with Groups

​Cleanup Endpoints

​Error Handling & Credits

​Next Steps

Base URL & Authentication

Create a Generation

Request Body

Response

Track Generation Status

Batch Submissions

Organize Results with Groups

Cleanup Endpoints

Error Handling & Credits

Next Steps