Skip to main content

​
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
  }'

​
Request Body

FieldTypeDefaultRequiredNotes
promptstring—✅Text prompt used for all generation types.
num_imagesinteger1❌Values >1 are submitted as a batch (see below).
character_idstringnull❌Required for character-based renders. Automatically validates subscription access.
use_face_lorabooleantrue❌Applies the character face LoRA. Only meaningful when character_id is set.
use_body_lorabooleantrue❌Applies the character body LoRA.
face_swapbooleantrue❌Enables default face swap pass.
source_image_urlstringnull❌Publicly reachable image URL for photo edits or video conversion. Automatically uploaded to temporary storage when needed.
convert_to_videobooleanfalse❌Converts the output into a short MP4 clip. Requires source_image_url.
group_idstringnull❌Attach the generation to an existing media group.
group_titlestringauto❌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.